pp-openrouter

OpenRouter — Printing Press CLI

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

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

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

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

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

この CLI がパブリックライブラリのカテゴリに対応する前に npx のインストールが失敗した場合は、Node をインストールするか、公開後にカテゴリ固有の Go フォールバックを使用してください。

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

ほかの OpenRouter ツールはどれもチャットをラップしますが、これはその制御を担います。モデル、生成、クレジットのローカルミラーを同期することで、cron ごとのコスト attribution（usage cost-by）、事前の予算ゲート（budget check）、劣化の監視（providers degraded）、残存期間の予測（credits runway）を実現します。これらは単一の API 呼び出しでは答えられません。カタログ、キー管理、アクティビティ、分析といったエンドポイント一式も、型付きコマンドとして同梱されています。

この CLI を使用する場面

OpenRouter 経由で LLM ワークロードを運用するタスクでは、この CLI を使用してください。cron やエージェントへの支出の帰属、予算に基づくスケジュール実行の制御、性能と価格に基づくモデルの絞り込み、実行前のプロバイダーの健全性監視、クレジットと上限の残存期間の予測などに適しています。ローカルの履歴と API の両方にまたがる質問、つまり単一の生の HTTP 呼び出しでは答えられない質問には、この CLI が最適です。

使用しない場面

次の場合は、この CLI を使用しないでください。

• 対話型チャットセッションや会話型プレイグラウンドには、チャットクライアントを使用します。ここでのチャットコマンドはエージェント向けの処理であり、ユーザー向けのインターフェースではありません。
• アプリケーションの推論経路を構築するには、CLI をシェルから呼び出すのではなく、アプリ内で OpenRouter 公式 SDK を使用します。
• 組織メンバーの管理、SCIM プロビジョニング、SSO の設定には、OpenRouter ダッシュボードを使用します。
• リアルタイムのトークンストリーミング表示には使用しないでください。CLI が返すのは完全な応答であり、ストリーム表示機能ではありません。

独自の機能

この API では、以下の機能を利用できるツールはほかにありません。

カタログの分析

• models query — 同期済みカタログに対する構造化クエリを使用して、性能、価格、コンテキストウィンドウに基づいてモデルを絞り込みます。オフラインで即座に実行できます。

  カタログ全体を取得する代わりにこちらを使用してください。数百 KB ではなく、約 200 トークンで候補を絞り込めます。

  openrouter-pp-cli models query "tools=true cost.completion<5 ctx>=128k" --agent
  

• models churn — 同期間のモデルカタログの変更点（追加、削除、価格改定とその差分）を確認します。

  請求書が届く前に、固定していたモデルの値上げや消失を検知するために使用してください。

  openrouter-pp-cli models churn --since 7d --agent
  

エージェント群のコスト管理

• usage cost-by — 任意の期間について、発生した cron、エージェント、または系統に支出を割り当てます。

  「どのモデルか」ではなく「どのジョブが費用を使ったか」を知りたいときに使用してください。

  openrouter-pp-cli usage cost-by --since 7d --agent
  

• usage anomaly — 直近の基準値と比較し、モデルごとのコスト急増が拡大する前に検出します。

  日次 cron で実行し、請求時ではなく、系統の動作が悪化した当日に問題を検知してください。

  openrouter-pp-cli usage anomaly --since 24h --agent
  

• budget — cron またはエージェントごとに支出上限を設定し、型付きの終了コードを使用して事前に適用します。

  終了コード 0/8 を条件としてスケジュール実行を制御し、予算超過の系統が実行されないようにします。

  openrouter-pp-cli budget check nightly-drafter
  

• generation explain — 1 回の生成について、トークン数、レイテンシ、最安のプロバイダーとの差分というコストの内訳を確認します。

  異常を検知した後に実行するコマンドです。「コストが急増した」を「この呼び出し、このプロバイダー、この差分」へと具体化します。

  openrouter-pp-cli generation explain gen-abc123 --agent
  

• usage reconcile — ローカルの利用状況ミラーを上流の日次合計と照合し、一致しない日を検出します。

  ローカルのコスト分析を信頼する前に実行してください。他の利用状況コマンドの信頼性の基盤となります。

  openrouter-pp-cli usage reconcile --since 7d --agent
  

プロバイダーのヘルスとディスパッチ

• providers degraded — 作業をディスパッチする前に、現在どのプロバイダーまたはモデルがデグレードしているかを確認します。

  ディスパッチ前にこれをチェックして、問題にリトライし続けるのではなく、トラブルを回避するルートを取ります。

  openrouter-pp-cli providers degraded --agent
  

• endpoints failover — 1 つのモデルを提供するプロバイダーを、ステータス、価格、観測されたレイテンシーでランク付けし、ディスパッチ順を決定します。

  これをルーターに渡して、特定のモデルについてデグレードしたプロバイダーを事前に回避します。

  openrouter-pp-cli endpoints failover deepseek/deepseek-v4 --agent
  

ランウェイとレート制限の余裕

• key eta — 観測されたバーンレートから、キーの支出上限に到達する日を予測します。

  これを利用して、実行中に気づくのではなく、その週の実行を上限に対して計画します。

  openrouter-pp-cli key eta --agent
  

• limits status — 現在の余裕を一覧表示します: キー上限の残量、無料枠の日次クォータ、本日の無料モデルの消費量。

  無料枠の開発ループやフリートのディスパッチの前にチェックして、原因不明の 429 を避けます。

  openrouter-pp-cli limits status --agent
  

• credits runway — 直近のバーンレートに基づき、プリペイドクレジットがゼロになるまでの日数を予測します — 402 の先行指標です。

  これに対する毎日の cron は、まだチャージする余裕があるうちに「いつ 402 に到達するか」に答えます。

  openrouter-pp-cli credits runway --agent
  

コマンドリファレンス

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

• openrouter-pp-cli activity — 過去 30（完了した）UTC 日間のエンドポイント別にグループ化されたユーザーアクティビティデータを返します。

audio — オーディオを管理します

• openrouter-pp-cli audio create-speech — 入力テキストから音声を合成します。要求された形式（例: mp3、pcm、wav）の生のオーディオバイトストリームを返します。
• openrouter-pp-cli audio create-transcriptions — 音声をテキストに文字起こしします。

benchmarks — エンドポイントをベンチマークします

• openrouter-pp-cli benchmarks — 複数のベンチマークソース（Artificial Analysis、Design Arena

byok — BYOK エンドポイント

• openrouter-pp-cli byok create-byokkey — 新しい bring-your-own-key（BYOK）プロバイダー資格情報を作成します。
• openrouter-pp-cli byok delete-byokkey — id によって bring-your-own-key（BYOK）プロバイダー資格情報を削除（ソフト削除）します。
• openrouter-pp-cli byok get-byokkey — id によって単一の bring-your-own-key（BYOK）プロバイダー資格情報を取得します。
• openrouter-pp-cli byok list-byokkeys — 認証されたエンティティのデフォルトワークスペースの bring-your-own-key（BYOK）プロバイダー資格情報を一覧表示します。
• openrouter-pp-cli byok update-byokkey — id によって既存の bring-your-own-key（BYOK）プロバイダー資格情報を更新します。

chat — チャット補完エンドポイント

• openrouter-pp-cli chat — 指定されたチャット会話に対するモデル応答のリクエストを送信します。ストリーミングモードと非ストリーミングモードの両方をサポートします。

classifications — タスク分類のマーケットシェアエンドポイント

• openrouter-pp-cli classifications — タスク分類別の OpenRouter トラフィックのマーケットシェア内訳を返します（例:

containers — コンテナエンドポイント

credits — クレジット管理エンドポイント

• openrouter-pp-cli credits create-coinbase-charge — 非推奨。
• openrouter-pp-cli credits get — 認証されたユーザーの購入済みおよび使用済みの合計クレジットを取得します。

datasets — 公開 OpenRouter 使用状況データセット。これらのエンドポイントによって返されるデータは CC BY 4.0（https://creativecommons.org/licenses/by/4.0/）の下でライセンスされています: OpenRouter への帰属表示を行えば、商用を含めて再利用および再公開できます。

• openrouter-pp-cli datasets get-app-rankings — 要求された日付ウィンドウ内のトークン使用量でランク付けされた OpenRouter 上のトップ公開アプリを返します
• openrouter-pp-cli datasets get-rankings-daily — OpenRouter 上の合計トークン使用量による日次のトップ 50 公開モデルを返します
• openrouter-pp-cli datasets get-session-cost — 公開されているハーネスの週次で更新される集計済みのセッションあたりコストセルを返します。

embeddings — テキスト埋め込みエンドポイント

• openrouter-pp-cli embeddings create — 埋め込みリクエストを埋め込みルーターに送信します
• openrouter-pp-cli embeddings list-models — 利用可能なすべての埋め込みモデルとそのプロパティのリストを返します

endpoints — エンドポイント情報

• openrouter-pp-cli endpoints — ZDR が利用可能なエンドポイントに与える影響をプレビューします

files — ファイルのエンドポイント

• openrouter-pp-cli files delete — リクエスト元のワークスペースが所有するファイルを削除します。削除は取り消せません。
• openrouter-pp-cli files get-metadata — リクエスト元のワークスペースが所有する単一ファイルのメタデータを取得します。
• openrouter-pp-cli files list — 認証に使用した API キーのワークスペースに属するファイルを一覧表示します。
• openrouter-pp-cli files upload — 今後の API 呼び出しで参照するファイルをアップロードします。

generation — 生成履歴のエンドポイント

• openrouter-pp-cli generation get — 生成に関するリクエストと使用状況のメタデータを取得します
• openrouter-pp-cli generation list-content — 生成に保存されたプロンプト、完了内容、エラー内容を取得します
• openrouter-pp-cli generation submit-feedback — 認証済みユーザーが行った生成について、構造化されたフィードバックを送信します。

guardrails — ガードレールのエンドポイント

• openrouter-pp-cli guardrails create — 認証済みユーザー用の新しいガードレールを作成します。
• openrouter-pp-cli guardrails delete — 既存のガードレールを削除します。Management key が必要です。
• openrouter-pp-cli guardrails get — ID で単一のガードレールを取得します。Management key が必要です。
• openrouter-pp-cli guardrails list — 認証済みユーザーのすべてのガードレールを一覧表示します。
• openrouter-pp-cli guardrails list-key-assignments — 認証済みユーザーのすべての API キーのガードレール割り当てを一覧表示します。
• openrouter-pp-cli guardrails list-member-assignments — 認証済みユーザーのすべての組織メンバーのガードレール割り当てを一覧表示します。
• openrouter-pp-cli guardrails update — 既存のガードレールを更新するか、未設定のワークスペース既定ガードレールを具体化します。

images — 画像のエンドポイント

• openrouter-pp-cli images create — 画像生成ルーターを通じて、テキストプロンプトから画像を生成します
• openrouter-pp-cli images list-model-endpoints — 画像モデルのエンドポイントごとの詳細なレコードを返します。各エンドポイントで確実にサポートされるパラメーターと価格が含まれます
• openrouter-pp-cli images list-models — サポートされるパラメーターの最上位の集合と、エンドポイントごとの詳細情報への URL を含む、すべての画像生成モデルを一覧表示します

key — キーの管理

• openrouter-pp-cli key — 現在の認証セッションに関連付けられた API キーの情報を取得します

keys — キーの管理

• openrouter-pp-cli keys create — 認証済みユーザー用の新しい API キーを作成します。プレーンテキストの key はこのレスポンスでのみ返されます。
• openrouter-pp-cli keys delete — 既存の API キーを削除します。
• openrouter-pp-cli keys get — ハッシュで単一の API キーを取得します。Management key が必要です。
• openrouter-pp-cli keys list — 認証済みユーザーのすべての API キーを一覧表示します。Management key が必要です。
• openrouter-pp-cli keys update — 既存の API キーを更新します。

messages — メッセージの管理

• openrouter-pp-cli messages — Anthropic Messages API 形式を使用してメッセージを作成します。テキスト、画像、PDF、ツール、拡張思考に対応しています。

model — モデル情報のエンドポイント

• openrouter-pp-cli model <author> <slug> — 作成者とスラッグで識別される単一モデルの詳細を返します（例：openai/gpt-4）。

models — モデル情報のエンドポイント

• openrouter-pp-cli models get — すべてのモデルとそのプロパティを一覧表示します
• openrouter-pp-cli models list-count — 利用可能なモデルの合計数を取得します
• openrouter-pp-cli models list-user — ユーザーのプロバイダー設定と[プライバシー設定](https://openrouter.

observability — オブザーバビリティのエンドポイント

• openrouter-pp-cli observability create-destination — 新しいオブザーバビリティの送信先を作成します。タイプごとに最大5件の送信先を設定できます。
• openrouter-pp-cli observability delete-destination — 既存のオブザーバビリティの送信先を削除します。これは論理削除を実行します。
• openrouter-pp-cli observability get-destination — UUIDを指定して、単一のオブザーバビリティの送信先を取得します。
• openrouter-pp-cli observability list-destinations — 認証済みエンティティのデフォルトワークスペースに設定されているオブザーバビリティの送信先を一覧表示します。
• openrouter-pp-cli observability update-destination — 既存のオブザーバビリティの送信先を更新します。リクエスト本文で指定したフィールドのみが更新されます。

openrouter-analytics — openrouter の分析を管理

• openrouter-pp-cli openrouter-analytics get-meta — 分析クエリエンドポイントで利用可能なメトリクス、ディメンション、フィルター演算子、粒度を返します。
• openrouter-pp-cli openrouter-analytics query — 指定したメトリクス、ディメンション、フィルター、期間で分析クエリを実行します。

openrouter-auth — openrouter の認証を管理

• openrouter-pp-cli openrouter-auth create-keys-code — ユーザーが管理する API キーを生成するための PKCE フロー用認可コードを作成します
• openrouter-pp-cli openrouter-auth exchange-code-for-apikey — PKCE フローの認可コードを、ユーザーが管理する API キーと交換します

organization — 組織のエンドポイント

• openrouter-pp-cli organization — 認証済みの管理キーに関連付けられた組織のメンバーをすべて一覧表示します。

presets — プリセットのエンドポイント

• openrouter-pp-cli presets get — スラッグでプリセットを取得し、現在指定されているバージョンをインラインで表示します。
• openrouter-pp-cli presets list — 認証済みユーザーのすべてのプリセットを、更新日時の新しい順に一覧表示します。

providers — プロバイダー情報のエンドポイント

• openrouter-pp-cli providers — すべてのプロバイダーを一覧表示します

rerank — リランクのエンドポイント

• openrouter-pp-cli rerank — リランクルーターにリランクリクエストを送信します

responses — OpenAI 互換の Responses API エンドポイント

• openrouter-pp-cli responses — OpenResponses API 形式を使用して、ストリーミングまたは非ストリーミングのレスポンスを作成します

scim — SCIM のエンドポイント

• openrouter-pp-cli scim create-group-mapping — SCIM グループとワークスペースのロールのマッピングを作成します。
• openrouter-pp-cli scim delete-group-mapping — SCIM グループとワークスペースのマッピングを削除します。管理キーが必要です。
• openrouter-pp-cli scim get-group-mapping — SCIM グループとワークスペースのマッピングを取得します。管理キーが必要です。
• openrouter-pp-cli scim list-group-mappings — 組織の SCIM グループとワークスペースのマッピングを一覧表示します。
• openrouter-pp-cli scim list-groups — 組織の SCIM グループを一覧表示します。管理キーが必要です。
• openrouter-pp-cli scim update-group-mapping — SCIM グループのマッピングロールを更新します。管理キーが必要です。

videos — 動画を管理

• openrouter-pp-cli videos create — 動画生成リクエストを送信し、ステータス確認用のポーリング URL を返します
• openrouter-pp-cli videos get — ジョブのステータスと、完了時にコンテンツ URL を返します
• openrouter-pp-cli videos list-models — 利用可能なすべての動画生成モデルとそのプロパティの一覧を返します

workspaces — ワークスペースのエンドポイント

• openrouter-pp-cli workspaces create — 認証済みユーザー用の新しいワークスペースを作成します。
• openrouter-pp-cli workspaces delete — 既存のワークスペースを削除します。有効な API キーがあるワークスペースは削除できません。先にキーを削除してください。
• openrouter-pp-cli workspaces get — ID またはスラッグで単一のワークスペースを取得します。管理キーが必要です。
• openrouter-pp-cli workspaces list — 認証済みユーザーのすべてのワークスペースを一覧表示します。
• openrouter-pp-cli workspaces update — ID またはスラッグで既存のワークスペースを更新します。管理キーが必要です。

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

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

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

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

レシピ

月曜日のコストレビュー

openrouter-pp-cli usage cost-by --since 7d --agent

週次のアトリビューション処理です。cron／エージェントのタグごとの支出を確認し、レビュー用のメモにそのまま貼り付けられます。

2 つのコマンドで異常から根本原因を特定

openrouter-pp-cli usage anomaly --since 24h --agent

モデルで異常が検出されたら、続けて「generation explain 」を実行し、問題の呼び出しに関するトークン数、レイテンシ、最安プロバイダーとの差を確認します。

ディスパッチ前のヘルスチェック

openrouter-pp-cli providers degraded --agent

リネージを実行する前に実行してください。「endpoints failover 」と組み合わせると、これから使用するモデルのディスパッチ順序を選択できます。

エンドポイントの詳細なペイロードを絞り込む

openrouter-pp-cli models endpoints list deepseek deepseek-v4 --agent --select data.endpoints.provider_name,data.endpoints.pricing.completion,data.endpoints.status

モデルごとのプロバイダー一覧は深くネストされています。--select を使うと、ルーターが実際に必要とする 3 つのフィールドだけに結果を絞り込めます。

予算で制御する cron のパターン

openrouter-pp-cli budget check nightly-drafter

上限内なら終了コードは 0、超過時は 8 です。スケジュール実行が開始される前に、これを使って実行を制御します（例：「budget check X && systemctl --user start X.service」）。

認証の設定

OPENROUTER_API_KEY を使った標準的なベアラー認証で、モデル、クレジット、キーのステータス、チャットを利用できます。2 つの機能には、ダッシュボードで作成する別個のプロビジョニング（管理）キーが必要です。キー管理（/keys）と、アカウント全体の使用状況の集計（/activity、分析）が対象です。通常のキーでは問題なく動作するのに、これらのコマンドで 401 または 403 が返る場合は、管理キーが必要なところで推論キーを使用しています。設定が壊れているわけではありません。2026-09 の実機検証では、推論キーで /activity を呼び出すと 403「Only management keys can fetch activity」が返ります。

CLI が読み取る環境変数は 1 つ（OPENROUTER_API_KEY）で、OPENROUTER_MANAGEMENT_KEY は読み取りません。管理キーを必要とするエンドポイントを呼び出すには、その呼び出しの API キーとして管理キーを設定してください。まず、環境に OPENROUTER_MANAGEMENT_KEY が設定されていることを確認します。

# Prerequisite: export OPENROUTER_MANAGEMENT_KEY=<your-management-key>
OPENROUTER_API_KEY="${OPENROUTER_MANAGEMENT_KEY}" openrouter-pp-cli keys list --agent
OPENROUTER_API_KEY="${OPENROUTER_MANAGEMENT_KEY}" openrouter-pp-cli activity --agent

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

エージェントモード

任意のコマンドに --agent を追加します。次のオプションが有効になります。--json --compact --no-input --no-color

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

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

  openrouter-pp-cli benchmarks --agent --select accuracy,accuracy_stddev,agentic_index
  

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

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

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

• 明示的な確認 — --agent を指定しても --yes は自動的に有効になりません。対象、引数、副作用を確認してから、必要な場合にのみ別途 --yes を指定してください。

• 明示的な再試行 — 既存の作成対象を成功として扱う場合にのみ --idempotent を使用し、削除対象が見つからない場合を成功として扱う場合にのみ --ignore-missing を使用してください。

レスポンスエンベロープ

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

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

データには .results を、ライブデータかローカルデータかの判定には .meta.source を解析してください。人間が読みやすい N results (live) のサマリーは、標準出力がターミナルで、かつ機械向けフォーマットのフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合に限り、標準エラー出力に表示されます。パイプやエージェントの利用時、およびフォーマットを明示した実行時は、標準出力に純粋な JSON が出力されます。

パスと状態

エージェントは、CLI のパス解決をランタイム契約の一部として扱ってください。

• 1 回の呼び出しに限って移動するには --home <dir> を使用するか、OPENROUTER_HOME=<dir> を設定して、4 種類すべてのパスを 1 つのルート配下に移動します。

• 特定の種類のパスだけを別の場所にする必要がある場合に限り、種類別の環境変数 OPENROUTER_CONFIG_DIR、OPENROUTER_DATA_DIR、OPENROUTER_STATE_DIR、OPENROUTER_CACHE_DIR を使用します。

• 解決順序は、種類別の環境変数、--home、OPENROUTER_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME）、プラットフォームのデフォルトの順です。

• config には、config.toml やプロファイルなどの設定が格納されます。data には、credentials.toml、data.db、Cookie、認証サイドカーが格納されます。state には、永続化されたクエリ、ジョブ、teach.log が格納されます。cache には、再生成可能な HTTP ファイルやキャッシュファイルが格納されます。

• 保存されたシークレットは、データディレクトリ内の credentials.toml にあります。互換性のため、従来の config.toml にあるシークレットも読み込まれ、最初に認証情報を書き込む際に config.toml から移動されます。

• openrouter-pp-cli doctor --fail-on warn を実行すると、パスと認証情報の保存場所に関する警告を確認できます。agent-context は、解決済みディレクトリが必要なエージェント向けに、スキーマ v4 の paths ブロックを公開します。

• MCP の場合、MCP ホストの設定を通じて移動先を渡してください。MCP バイナリは CLI フラグを継承しません。

  {
    "mcpServers": {
      "openrouter": {
        "command": "openrouter-pp-mcp",
        "env": {
          "OPENROUTER_HOME": "/srv/openrouter"
        }
      }
    }
  }
  

フリートでの優先順位：継承された種類別環境変数は、その種類に対する明示的な --home より優先されます。フリート全体で長期的に使用する設定には OPENROUTER_HOME または種類別の環境変数を使い、--home は 1 回の呼び出しに限って使用してください。環境変数の設定を解除しても、移動は元に戻りません。OPENROUTER_HOME をクリアする前にファイルを手動で移動してください。そうしないと、doctor は以前のルートに残された認証情報を見つけられません。

自動学習

この CLI には、学習内容を自動収集するループが備わっています。CLI が記録管理を行います。呼び出しのたびにローカルに記録し、失敗したフラグの後に修正して再試行すると flag_alias 候補を自動で導出し、プレイブックのないクエリファミリーに対して teach を実行すると、セッションの記録から playbook_candidate を自動で合成します。あなたが行うのは判断だけです。まず recall を実行し、提示された候補に基づいて行動し、最終回答を teach し、修正に気付いたら playbook amend を実行してください。失敗を手動で記録する必要はありません。

ステップ 1：探索の前に recall を実行

新しいユーザーの質問について、一覧表示、検索、詳細確認のコマンドを実行する前に、次を実行してください。

openrouter-pp-cli recall "<user's question>" --agent

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

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "openrouter-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

空ストアのショートサーキット：ストアに学習内容、プレイブック、候補がまだなく（recall で何も見つからず、learnings list と learnings candidates もどちらも空の場合）、このセッションの残りではクエリごとの負荷を避けるため recall を省略し、何かを教えた後に再び recall を最初に実行してください。

ステップ 2：判断ツリー

candidates、playbook、notes、results[0]、警告の順に確認します。

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `openrouter-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook と Notes は、リソースごとの経路とは独立しています。recall の応答には Playbook と Results[] のヒットの両方が含まれる場合があります。両方を使ってください。Playbook は実行する手順を示し、リソースのヒットが特定の手順を省略できるようにします。デフォルトでは mismatches をスキップし、コールドスタート時の予想外の挙動を調査する場合に限り --debug-mismatches を渡してください。

候補の判定に関する詳細：learnings confirm <id> を実行すると、候補を確定する前に完全なペイロードが表示されます。表示されたペイロードが、確認した動作と一致することを確かめてください。learnings reject <id> を実行すると、導出シグネチャが tombstone され、同じ候補が再び表示されなくなります。エンベロープに含まれるのは、今対処する価値のある少数の候補だけです。openrouter-pp-cli learnings candidates を実行すると、未処理の候補すべてを一覧表示できます。

グレースフルデグラデーション：learnings confirm が不明なコマンドの場合、古いバイナリを操作しています。候補に関する案内は無視し、残りのプロトコルに従ってください。

ステップ 3：常に warnings を確認する

• low_confidence：confidence<2 の行が存在します。スキップ可能な発見結果ではなく、ヒントとして扱ってください。
• resource_not_in_store：ローカルストアに、学習内容が参照するリソースがありません。一致検証でエンティティを分類できなかったため、直接取得して再評価してください。
• cross_alias_match（結果ごと）：その行は別のエイリアスで学習され、entity_lookups を介して、現在のクエリの正規エンティティと一致しました（例：「USA」での学習が「United States」の recall を満たす場合）。resource_id を信頼してください。
• similar_shape_different_entity:<canonical>（トップレベル）：構造的に一致する行はありますが、その正規エンティティは現在のクエリと異なります。コールドスタートとして扱います。この警告にはヒントとして競合する正規エンティティが含まれますが、その行は Results に昇格されません。
• ambiguous_alias（トップレベル）：1 つのクエリエンティティが複数の正規エンティティに解決されました（例：「Cards」→ Arizona Cardinals + St. Louis Cardinals）。リソースを決定する前に、コンテキストから曖昧さを明らかにしてください。
• candidates_present（トップレベル）：エンベロープに candidates セクションが含まれています。ステップ 2 の候補分岐に従い、ほかの作業より先に処理してください。
• lookup_refresh_available（トップレベル）：クエリ内のエンティティに lookup 行がまだありませんが、同期済みデータから補完できる可能性があります。openrouter-pp-cli sync を実行して、エンティティ lookup を更新してください。
• トップレベルの no_learnings_for_query_family：Jaccard の下限を超える行がテーブルにありません。完全なコールドスタートです。

ステップ 4：応答の確定後、必ず teach & を実行する

teach は無条件で行います。ストアが回答できなかったクエリを解決した後は、最終的なリソースの対応関係をバックグラウンドで teach してください。呼び出し回数のしきい値はなく、学習する「価値」があったかどうかを判断する必要もありません。teach はループの要です。Playbook がないファミリーに対する Playbook の合成を開始し、同じ参照先を指す表現は 1 つのファミリーにまとめられるため、ほぼ重複する teach によってストアが分断されることはありません。ユーザー向けの応答を組み立てた後、送信する前に、シェルの & を付けて実行すると、呼び出しはすぐに戻ります。

openrouter-pp-cli teach --query "<user's question>" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

成功時は何も出力されません。エラーは、解決済みの state ディレクトリにある teach.log にのみ記録されます。最も具体的なリソースを teach してください。ユーザーが広い範囲の質問をしていて、親レコードをたどって具体的な回答を見つけた場合は、親ではなく末端の ID を teach します。CLI は recall 時にシード済みの entity_lookups を使ってエイリアスをまたいで解決するため、1 つのエイリアス（例：「Niners」）で teach すれば、別のエイリアス（例：「49ers」、「San Francisco」）を使った今後のクエリにも自動的に対応できます。

PII に関するルール：識別子を削除した構造的な質問を teach してください。teach するクエリやメモに、氏名、メールアドレス、電話番号、アカウント ID、その他の個人識別子を含めないでください。CLI は teach クエリをスキャンし、明らかなメールアドレスや電話番号の形式を検出すると警告しますが、ブロックはしません。警告に頼るのではなく、teach する前に削除してください。

Step 5: playbook - オプションのフラグ、自動生成

セッションがプレイブックに「値する」かどうかを判断する必要はありません。プレイブックがないファミリーについて teach を実行すると、セッションのジャーナルから playbook_candidate が自動生成され、次のセッションで confirm/reject によって判定されます。明示的なプレイブックフラグを付けるのは、そのまま記録する価値のある手順をすでに把握している場合に限ります。たとえば、CLI では明らかにならなかった回避策（ひそかに無視されるフラグ、未文書化のパラメーター、ページネーションの工夫、ペイロードに関する注意点）です。統合型のワンコール形式を優先してください。リソースの学習内容とプレイブックを、同じ teach 呼び出しで記録します。

# Common case: record both the resource learning AND the playbook in one call.
openrouter-pp-cli teach \
  --query "<user's question>" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
openrouter-pp-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

プレイブックファイルは steps、entity_slots、expected_tool_calls を含む JSON です。ノートファイルは注意点をそのまま記載した Markdown です。ファイルを使わない呼び出し元（MCP 専用エージェント）は、同じ内容をインラインで渡します。統合型の teach 形式では --playbook-json と --playbook-notes、teach-playbook では --playbook-json と --notes を使います。統合型の teach 形式ではプレイブックフラグは任意です。リソースのみを教える場合は、フラグをすべて省略してください。単独の teach-playbook 形式では、プレイブックフラグとノートフラグの少なくとも一方を設定する必要があります。両方が空の場合は拒否されます。プレイブックは構造的なクエリファミリー（エンティティを除去したもの）をキーとするため、あるエンティティ形式のクエリから学習した手順は、同じ形のほかのすべてのクエリに適用されます。想起時には slots_resolved が、実際のクエリに含まれる正規化済みの値に対応付けます。

今後の想起時にプレイブックが見つかった場合は、それを確定情報として扱います。slots_resolved の置換値を使って手順を再実行し、手順にすでに記載されている調査は省略し、どの手順よりも先に notes を読んでください。

Step 6: デバッグ応答で修正点を特定した場合は playbook amend & を実行する

デバッグプロトコルへの応答で、ノートやプレイブックに反映すべき具体的な修正点（回避策、未文書化のエンドポイント形式、古いフィールド名、確認されたスキーマの変化、空のペイロードに対するフォールバック）を特定した場合は、ユーザー向けの応答を出す前に playbook amend を実行してください。teach と同様に、実行結果を待たずに進めます。

openrouter-pp-cli playbook amend \
  --query "<exact recall query string>" \
  --add-note "<your concrete correction>"
# (append shell `&` to background it)

追記する価値があるもの：このセッションで実際に確認した、今後の自分にとって役立つ挙動です。追記する価値がある例：

• フラグをひそかに無視したり、順序を入れ替えたりする CLI のインターフェースに対する回避策。
• 未文書化のエンドポイント形式（レスポンスが {meta, results} でラップされる、ペイロードがドキュメントの記述より 2 階層深くネストされているなど）。
• 確認されたスキーマの変化（フィールド名の変更、シーズンごとに変わるインデックス、API が小文字で返すようになったカテゴリラベルなど）。

ノートに含めてはいけないもの：

• ユーザーの質問に対する、年やエンティティ固有の回答。それは応答であり、学習内容ではありません。
• プレイブックが実行時にすでに取得している、チーム、選手、行ごとのデータ。
• 既存のノートの内容を言い換えただけの記述。

amend コマンドは、ファミリーの既存のノートにタイムスタンプ付きのマーカー（[amend YYYY-MM-DDTHH:MMZ]: <text>）を付けて追記します。複数の amend が蓄積され、監査証跡を確認できます。そのファミリーにプレイブックがまだない場合、amend はノートのみのプレイブックを作成します（そのため、初回利用時の修正も記録されます）。

amend ノートにおける PII の取り扱い

playbook amend のノートは、Printing Press の今後のバージョンで共有ナレッジとして上流に提供される可能性があります。遡及的な削除をせずに上流への提供を可能にするため、ユーザーを特定できる情報を含めないでください。

• 埋め込まないでください：ユーザーのファイルシステム上のパス、個人用 API キーやトークン、ユーザーのメールアドレス、ユーザーの GitHub ハンドル、特定のユーザーに結び付いたクエリ履歴。
• 含めてもよいもの：エンドポイントの形式、未文書化のフィールド名、API の注意点、確認されたスキーマの変化、CLI インターフェースに対する回避策、一般化できるページネーションや再試行の方法。

修正内容がユーザー固有のコンテキストでしか意味をなさない場合は、プレイブック amend ではなく個人用ノートに記録してください。

ループの測定

openrouter-pp-cli learnings stats では、ローカルの learn_events テーブルから、再呼び出しのヒット率、教示内容の再利用率、プレイブックの解決率、候補の確認／却下数が報告されます。分母となる値が得られるまでは、各率は null です。すべてのデータはこのマシン内にとどまります。この CLI でループが効果を発揮しているか確認するために使ってください。

学習の無効化

• 単一のコマンドに --no-learn を指定すると、recall と teach の書き込み処理がどちらもスキップされます。蓄積された学習内容の影響を受けてはいけない決定的なエージェントのワークフローやテストで使用してください。
• 環境変数に OPENROUTER_NO_LEARN=true を設定すると、パイプラインが全体で無効になります。

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

この CLI の問題に気づいたときは、あなた自身またはエージェントがその内容を記録してください。

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

エントリーは、解決済みのデータディレクトリにある feedback.jsonl にローカル保存されます。OPENROUTER_FEEDBACK_ENDPOINT が設定され、かつ --send が指定されている場合、または OPENROUTER_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 ステータスが標準エラー出力に記録されます。

名前付きプロファイル

プロファイルは、保存済みのフラグ値のセットで、複数回の実行で再利用されます。定期的に実行するエージェントが毎回異なる入力を受け取りながら、同じフラグを繰り返し使う場合に使用してください。

openrouter-pp-cli profile save briefing --json
openrouter-pp-cli --profile briefing benchmarks
openrouter-pp-cli profile list --json
openrouter-pp-cli profile show briefing
openrouter-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

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

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

claude mcp add openrouter-pp-mcp -- openrouter-pp-mcp

確認します：claude mcp list

直接使用

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

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

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