pp-alltrails

Alltrails — Printing Press CLI

前提条件：CLI のインストール

このスキルは alltrails-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。 インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使用してインストールします。バイナリの既定のインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin です。

   npx -y @mvanhorn/printing-press-library install alltrails --cli-only
   

2. 確認します：alltrails-pp-cli --version
3. スキルを実行するエージェント／ランタイムから参照できるよう、表示されたインストール先のディレクトリが $PATH に含まれていることを確認します。

npx でのインストールに失敗した場合（Node がない、オフラインなど）は、Go による直接インストールに切り替えてください（Go 1.26.6 以降が必要です）。

go install github.com/mvanhorn/printing-press-library/library/travel/alltrails/cmd/alltrails-pp-cli@latest

インストール後に --version が「command not found」と表示する場合、ランタイムからバイナリのディレクトリを $PATH 経由で参照できていません。確認に成功するまで、スキルのコマンドを実行しないでください。

HTTP トランスポート

この CLI は標準の Go HTTP トランスポートを使用し、AllTrails がネゴシエートした場合は HTTP/2 を有効にします。通常の API 呼び出しに、常駐するブラウザーのプロセスは必要ありません。

コマンドリファレンス

alltrails — alltrails を管理します

• alltrails-pp-cli alltrails create — 新しいアクティビティ記録をアップロードします
• alltrails-pp-cli alltrails get — GPS／統計データを含むアクティビティの詳細を取得します
• alltrails-pp-cli alltrails get-v3 — トレイルの詳細ペイロードを取得します
• alltrails-pp-cli alltrails get-v3-2 — オフラインマップのメタデータを取得します
• alltrails-pp-cli alltrails get-v3-3 — マップの静的画像のメタデータ／レンダリングエンドポイントを取得します
• alltrails-pp-cli alltrails get-v3-4 — トレイルの静的マップ画像のメタデータ／レンダリングエンドポイントを取得します
• alltrails-pp-cli alltrails get-v3-5 — ユーザーのアクティビティ一覧を取得します
• alltrails-pp-cli alltrails list — テキスト、場所、フィルターでトレイルを検索します
• alltrails-pp-cli alltrails list-v3 — 現在のアカウントのプロフィールを取得します

適切なコマンドを見つける

実行したい操作は分かっていても、どのコマンドを使うか分からない場合は、CLI に直接問い合わせてください。

alltrails-pp-cli which "<capability in your own words>"

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 件の一致が見つかったことを示し、終了コード 2 は確かな一致がないことを示します。一致がない場合は --help を使うか、より絞り込んだ問い合わせをしてください。

認証の設定

公開データの読み取りは、認証情報がなくても利用できる場合があります。アカウント関連のルートでは、呼び出し元が所有する認証情報を使用します。

• ALLTRAILS_ACCESS_TOKEN — 認証済み API リクエスト用のベアラートークン。
• ALLTRAILS_COOKIE — 認証が必要なルートで使用するブラウザーの Cookie ヘッダー。
• ALLTRAILS_CSRF_TOKEN — 必要に応じて、ブラウザー経由の書き込みルートで使用する CSRF ヘッダー。

alltrails-pp-cli doctor を実行して設定を確認してください。

書き込みの安全性

既定では読み取りコマンドを使用してください。書き込みルートには mcp:read-only=false と mcp:risk=<level> の注釈が付いています。

PP 側の安全措置により、次の両方の条件を満たさない限り、AllTrails への実際の書き込みはブロックされます。

1. 既定の書き込みドライランではなく、--live-write を指定してコマンドを呼び出すこと。
2. 環境内に ALLTRAILS_PP_ALLOW_WRITES=1 が設定されていること。

どちらかの条件が満たされない場合、書き込みルートはリクエストをプレビューするか、HTTP トランスポートの実行前にフェイルクローズします。ユーザーが対象となるアカウント変更を明示的に承認していない限り、ALLTRAILS_PP_ALLOW_WRITES を設定しないでください。

エージェントモード

任意のコマンドに --agent を追加できます。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプ処理可能 — JSON は標準出力に、エラーは標準エラー出力に出力されます

• フィルタリング可能 — --select でフィールドの一部を選択できます。ドット区切りのパスはネストされた構造をたどり、配列では各要素をたどります。出力の多い API でコンテキストを小さく保つのに役立ちます：

  alltrails-pp-cli alltrails list --agent --select id,name,status
  

• プレビュー可能 — --dry-run で、送信せずにリクエストを表示します

• オフラインに対応 — sync／search コマンドは、利用可能な場合にローカル SQLite ストアを使用できます

• 非対話型 — プロンプトは表示されず、すべての入力をフラグで指定します

• 再試行を明示 — 既存のリソースの作成を成功として扱う場合に限り、--idempotent を使用します

AllTrails のブラウザー API は、ログイン済みブラウザーのコンテキスト外では DataDome によって保護されているため、sync は安全のため何もしない動作がデフォルトです。呼び出し元が所有する認証情報／Cookie が設定され、ライブデータの読み取りが明示的に必要な場合に限り、sync --resources routing_info を使用してください。

レスポンスのエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力を来歴エンベロープで囲みます：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を、ライブデータかローカルデータかの確認には .meta.source を解析してください。人間が読みやすい N results (live) という概要は、標準出力が端末であり、かつ機械可読形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合に限り、標準エラー出力に表示されます。パイプ処理／エージェントによる利用時と、形式を明示した実行時は、標準出力に純粋な JSON が出力されます。

エージェントからのフィードバック

この CLI に問題があると気づいた場合（エージェントが気づいた場合も含む）は、記録してください：

alltrails-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
alltrails-pp-cli feedback --stdin < notes.txt
alltrails-pp-cli feedback list --json --limit 10

エントリーは ~/.local/share/alltrails-pp-cli/feedback.jsonl にローカル保存されます。ALLTRAILS_FEEDBACK_ENDPOINT が設定され、かつ --send が渡されるか ALLTRAILS_FEEDBACK_AUTO_SEND=true が設定されていない限り、POST されることはありません。デフォルトの動作はローカル保存のみです。

バグ報告ではなく、意外に感じたことを書いてください。短く、具体的に、1 行で記録してください。そこから積み重ねが生まれます。

出力の送信先

すべてのコマンドで --deliver <sink> を使用できます。出力は標準出力に加えて、または標準出力の代わりに指定した送信先へ出力されるため、エージェントは手動でパイプ処理することなくコマンド結果を振り分けられます。次の 3 つの送信先に対応しています：

送信先	動作
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイル + リネーム）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

不明なスキームは、対応している送信先を示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードが返され、URL と HTTP ステータスが標準エラー出力に記録されます。

名前付きプロファイル

プロファイルは、呼び出しのたびに再利用できるフラグ値の保存セットです。スケジュールされたエージェントが毎回同じ設定で同じコマンドを呼び出す場合に使用します。これは HeyGen の「Beacon」パターンです。

alltrails-pp-cli profile save briefing --json
alltrails-pp-cli --profile briefing alltrails list
alltrails-pp-cli profile list --json
alltrails-pp-cli profile show briefing
alltrails-pp-cli profile delete briefing --yes

明示的なフラグは常にプロファイルの値より優先され、プロファイルの値はデフォルトより優先されます。agent-context は、利用可能なすべてのプロファイルを available_profiles に一覧表示するため、情報を調べるエージェントは実行時にそれらを検出できます。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が不正）
3	リソースが見つかりません
5	API エラー（上流の問題）
7	レート制限中（待機して再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します：

1. 空、help、または --help → alltrails-pp-cli --help の出力を表示します
2. install で始まる場合 → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の前提条件を参照してください
3. それ以外 → 直接使用（CLI コマンドとして --agent を付けて実行します）

MCP サーバーのインストール

この CLI の公開ライブラリのエントリーまたはビルド済みリリースから MCP バイナリをインストールし、登録します：

claude mcp add alltrails-pp-mcp -- alltrails-pp-mcp

確認：claude mcp list

直接使用

1. インストールされているか確認します：which alltrails-pp-cli 見つからない場合は、インストールを提案します（このスキルの最初にある前提条件を参照してください）。
2. ユーザーのクエリに最適なコマンドを、上記の「独自の機能」と「コマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します：

   alltrails-pp-cli <command> [subcommand] [args] --agent
   

4. 曖昧な場合は、サブコマンドのヘルプを確認します：alltrails-pp-cli <command> --help。