pp-strava

Strava — Printing Press CLI

前提条件：CLI をインストールする

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

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

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

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

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

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

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

この CLI を使用する場面

エージェントがアスリートの過去のトレーニングデータを照会したり、Strava のウェブインターフェースでは利用できないフィットネス指標を算出したり、アクティビティを一括管理したり、トレーニング分析パイプラインを構築したりする場合は、strava-pp-cli を使用してください。5 件を超えるアクティビティを集計する場合、ストリームレベルのデータ（心拍数、パワー、GPS）を扱う場合、または Strava データへのオフラインアクセスが必要な場合に最適です。

独自の機能

この API で、ほかのツールでは利用できない機能です。

蓄積されるローカル状態

• segments progress — セグメントでの過去の努力をすべて確認できます。日付、タイム、平均パワー、平均心拍数、PR との差が表示されるため、実際に成長しているか追跡できます。

  エージェントがシーズンを通じて、対象のトレーニングセグメントでアスリートが成長しているか評価する必要がある場合に使用します。

  strava-pp-cli segments progress 229781 --json --select start_date,elapsed,avg_watts,delta_pr_seconds
  

• training load — 慢性トレーニング負荷、急性トレーニング負荷、トレーニングストレスバランスをスパークラインで確認できるため、レース前のオーバートレーニングやテーパリング不足を見つけられます。

  エージェントが、アスリートのフィットネス／疲労状態や、今後のイベントに向けた準備状況を評価する必要がある場合に使用します。

  strava-pp-cli training load --weeks 12 --ftp 285 --agent
  

• training zones — 心拍数またはパワーの各ゾーンで、実際に週あたり何分間トレーニングしたかを確認できます。トレーニングの分布が計画に合っているか判断できます。

  トレーニングブロックが計画どおりに実施されたか（分極化、スイートスポット、ベース）を評価する場合に使用します。

  strava-pp-cli training zones --weeks 8 --type Run --zone-type heartrate --agent
  

• athlete power-curve — 標準的な各時間（1s〜60min）での最大平均パワーを確認できるため、シーズンを通じた強み、弱み、フィットネスの変化を特定できます。

  エージェントがサイクリストの生理的特性を把握したり、トレーニングブロック間でピークパワーを比較したりする必要がある場合に使用します。

  strava-pp-cli athlete power-curve --since 2025-01-01 --weight 75 --agent
  

• activities drift — アクティビティ中の有酸素デカップリングを測定します。後半における心拍数の上昇とペース低下の比率から、ラボでの検査なしに有酸素フィットネスを評価できます。

  エージェントが、有酸素性閾値を超えていたことを示す有酸素デカップリングが見られた長距離ランやライドを特定する必要がある場合に使用します。

  strava-pp-cli activities drift --min-duration 45m --since 2025-01-01 --threshold 5 --agent
  

• segments kom-gap — スター付きの各セグメントで KOM までどれだけ離れているかを正確に確認し、記録を更新できる可能性の高い順に表示します。

  エージェントが、トレーニング計画やライド前の目標設定に向けて、最も達成可能性の高い KOM 目標を提示する必要がある場合に使用します。

  strava-pp-cli segments kom-gap --top 10 --agent
  

エージェント向けの連携機能

• activities bulk-update — プレビューしてから確定する安全機能付きで、ギア、名前のテンプレート、説明を数百件のアクティビティに一括で反映できます。

  エージェントが、装備の交換後にギアの割り当てを一括で移行したり、トレーニングブロックのアクティビティをさかのぼって整理したりする必要がある場合に使用します。

  strava-pp-cli activities bulk-update --type Ride --after 2024-01-01 --set-gear b12345678 --dry-run
  

• gear status — 各シューズと自転車の総走行距離、設定済みの交換しきい値、最近の使用率に基づく推定引退日を確認できます。

  エージェントが重要なレースを前に、交換時期が近いギアがないか確認する必要がある場合に使用します。

  strava-pp-cli gear status --threshold shoes=500mi --agent
  

コマンドリファレンス

activities — アクティビティを管理します

• strava-pp-cli activities create-activity — アスリートの手動アクティビティを作成します。activity:write スコープが必要です。
• strava-pp-cli activities get-activity-by-id — 認証済みアスリートが所有する、指定されたアクティビティを返します。
• strava-pp-cli activities update-activity-by-id — 認証済みアスリートが所有する、指定されたアクティビティを更新します。activity:write が必要です。

athlete — アスリートを管理します

• strava-pp-cli athlete get-logged-in — 現在認証されているアスリートを返します。
• strava-pp-cli athlete get-logged-in-activities — 指定された識別子のアスリートのアクティビティを返します。activity:read が必要です。
• strava-pp-cli athlete get-logged-in-clubs — 認証済みアスリートが所属するクラブの一覧を返します。
• strava-pp-cli athlete get-logged-in-zones — 認証済みアスリートの心拍数ゾーンとパワーゾーンを返します。profile:read_all が必要です。
• strava-pp-cli athlete update-logged-in — 現在認証されているアスリートを更新します。profile:write スコープが必要です。

athletes — アスリートを管理します

clubs — クラブを管理します

• strava-pp-cli clubs <id> — 識別子を使って指定されたクラブを返します。

gear — ギアを管理します

• strava-pp-cli gear <id> — 識別子を使って機材を返します。

routes — ルートを管理します

• strava-pp-cli routes <id> — 識別子を使ってルートを返します。非公開ルートには read_all スコープが必要です。

segment-efforts — セグメントの記録を管理します

• strava-pp-cli segment-efforts get-by-id — 認証済みアスリートが所有するアクティビティのセグメント記録を返します。サブスクリプションが必要です。
• strava-pp-cli segment-efforts get-efforts-by-segment-id — 指定されたセグメントについて、認証済みアスリートのセグメント記録を返します。サブスクリプションが必要です。

segments — セグメントを管理します

• strava-pp-cli segments explore — 指定されたクエリに一致する上位 10 件のセグメントを返します。
• strava-pp-cli segments get-by-id — 指定されたセグメントを返します。
• strava-pp-cli segments get-logged-in-athlete-starred — 認証済みアスリートがお気に入りに登録したセグメントの一覧です。

uploads — アップロードを管理します

• strava-pp-cli uploads create — アクティビティの作成に使う新しいデータファイルをアップロードします。activity:write スコープが必要です。
• strava-pp-cli uploads get-by-id — 指定された識別子のアップロードを返します。activity:write スコープが必要です。

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

実行したいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接尋ねてください。

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

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

レシピ

レース前にトレーニングの準備状況を確認する

strava-pp-cli training load --weeks 8 --ftp 285 --agent --select ctl,atl,tsb,label

過去 8 週間それぞれの TSB（フレッシュネス）を表示します。TSB がマイナスなら疲労、プラスならフレッシュな状態です。レース週の目標は TSB > 10 が理想です。

今年の最高パワー記録を見つける

strava-pp-cli athlete power-curve --since 2025-01-01 --weight 72 --agent --select duration,watts,wkg

標準的な各時間枠での平均パワーの最高値を W/kg に換算して返します。生理学的プロファイリングのためにコーチと共有できます。

有酸素運動のデカップリングが起きたロングランを特定する

strava-pp-cli activities drift --type Run --min-duration 60m --threshold 8 --agent --select id,name,start_date,drift_pct

後半にペースに対する心拍数の上昇が 8% を超えたランをすべて一覧表示します。これらは追い込みすぎたトレーニング日です。

今シーズンのセグメントの進捗を見る

strava-pp-cli segments progress 229781 --since 2025-01-01 --agent --select start_date,elapsed,avg_watts,delta_pr_seconds

セグメント 229781 のすべての記録を日付順に表示し、自己ベストとの差も示すので、傾向をはっきり確認できます。

マラソン前にギアの交換時期を確認する

strava-pp-cli gear status --threshold run_shoes=400 --agent --select gear_name,total_distance_mi,pct_threshold,est_retirement_date

すべてのランニング用ギアについて、走行距離と推定交換日を表示します。レース当日のチェックリストに必要な項目に絞るには、--select を使います。

認証の設定

Strava は OAuth2 を使用します。strava-pp-cli auth login を実行すると、ブラウザーで認証ページが開きます。CLI がローカルコールバック、トークン交換、保存を自動的に処理します。実行前に STRAVA_CLIENT_ID と STRAVA_CLIENT_SECRET を設定してください。再認証するには、もう一度 auth login を実行します。

strava-pp-cli doctor を実行して、設定を確認します。

エージェントモード

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

• パイプ可能 — JSON は stdout に、エラーは stderr に出力されます

• フィルタリング可能 — --select でフィールドを絞り込みます。ドット区切りのパスはネストされた構造に進み、配列は各要素を走査します。詳細な API でコンテキストを小さく保つうえで重要です：

  strava-pp-cli activities create-activity --name example-resource --agent --select id,name,status
  

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

• オフラインでも利用可能 — 同期／検索コマンドは、利用可能な場合にローカル SQLite ストアを使用できます

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

• 明示的な再試行 — すでに存在する項目の作成を成功として扱う場合に限り、--idempotent を使用します

レスポンスエンベロープ

ローカルストアまたは API からデータを読み取るコマンドは、出力を情報源のエンベロープでラップします：

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

データには .results を、ライブデータかローカルデータかの確認には .meta.source を解析します。人間向けの N results (live) という概要は、stdout がターミナルであり、かつ機械処理用の形式フラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合に限り stderr に出力されます。パイプやエージェントによる利用、および明示的な形式指定では、stdout には純粋な JSON が出力されます。

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

この CLI について気になる点に（あなた、またはエージェントが）気付いたら、記録してください：

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

記録は ~/.strava-pp-cli/feedback.jsonl にローカル保存されます。STRAVA_FEEDBACK_ENDPOINT が設定され、かつ --send が渡された場合、または STRAVA_FEEDBACK_AUTO_SEND=true の場合を除き、POST されることはありません。デフォルトの動作はローカルのみです。

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

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は stdout への出力に加えて（または stdout の代わりに）指定したシンクに送られるため、エージェントはコマンド結果を手動でパイプせずに振り分けられます。サポートされているシンクは 3 種類です：

シンク	動作
stdout	デフォルト。stdout のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（tmp + rename）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

不明なスキームは、サポート対象を示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードを返し、stderr に URL と HTTP ステータスを記録します。

名前付きプロファイル

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

strava-pp-cli profile save briefing --json
strava-pp-cli --profile briefing activities create-activity --name example-resource
strava-pp-cli profile list --json
strava-pp-cli profile show briefing
strava-pp-cli profile delete briefing --yes

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

終了コード

コード	意味
0	成功
2	使用エラー（引数が不正）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待機してから再試行）
10	設定エラー

引数の解析

$ARGUMENTS を解析します：

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

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

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

claude mcp add strava-pp-mcp -- strava-pp-mcp

確認：claude mcp list

直接使用

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

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

4. 不明な点がある場合は、サブコマンドのヘルプを確認します：strava-pp-cli <command> --help。