openrouter-cli スキル

openrouter は OpenRouter API をラップするゼロ依存の Node CLI です。人間にもLLMエージェントにも対応するよう設計されており、すべてのコマンドは --json で機械可読出力に対応し、安定した終了コードを持ち、有用な場合は標準入力を読み込みます。

このスキルを使用すべき場合

以下をユーザーが要求した場合にトリガーします：

• シェル、スクリプト、またはエージェントループから OpenRouter を呼び出す
• より安価で高速、信頼性の高いモデルまたはプロバイダーを選択する
• モデルの価格、スループット、レイテンシ、またはサポートされているパラメータを検索する
• クレジット、キー別支出、日次/週次/月次使用状況、またはレート制限を確認する
• 特定の生成（gen-... id）を検査または監査する — 入力、出力、コスト、レイテンシ、終了理由
• OpenRouter API キーをプログラムで作成・一覧表示・無効化・削除する
• ガードレール、ワークスペース、または組織メンバーを管理する
• 新しいマシンから OpenRouter にログインする（ブラウザで OAuth PKCE）

OpenAI / Anthropic / Cohere SDK を OpenRouter なしで直接使用している場合、またはモデル選択戦略に関するもので実際の API 呼び出しを伴わない場合はスキップします。

インストール

# 推奨
npm install -g @aaronjmars/openroutercli

# インストール不要
npx -p @aaronjmars/openroutercli openrouter --help

# ソースから
git clone https://github.com/aaronjmars/openroutercli && cd openroutercli && npm link

Node.js 20 以上が必要です。インストール後、2 つのバイナリが利用可能になります：openrouter と短いエイリアス or。

認証

優先順位順に 3 つの方法があります。最初にマッチしたものが使用されます：

1. コマンド上の --key sk-or-... フラグ（すべてをオーバーライド）
2. 環境変数：OPENROUTER_API_KEY（ユーザー） / OPENROUTER_MANAGEMENT_KEY（管理）
3. openrouter login で保存されたキー（~/.config/openrouter/config.json、パーミッション 0600）

# ブラウザ OAuth（PKCE）— 人間向けの推奨方法
openrouter login

# 既存のキーを非対話的に保存
openrouter login --key sk-or-v1-...
echo "sk-or-v1-..." | openrouter login --stdin
openrouter login --no-browser    # SSH / ヘッドレス — URL を出力し、手動で開く

# 確認 / 削除
openrouter whoami
openrouter logout

2 つのキースロット：ユーザー vs 管理

OpenRouter には 2 つのキータイプがあります。CLI は各スロットを保持し、コマンドごとに自動的にルーティングします。

スロット	使用対象	取得方法
ユーザーキー	chat、messages、responses、embed、rerank、speech、video、generation、credits、whoami	OAuth（openrouter login）またはダッシュボードから貼り付け
管理キー	keys、guardrails、workspaces、activity、org members、auth-code	ダッシュボードのみ — https://openrouter.ai/settings/provisioning-keys。OAuth では取得できません。openrouter login --management で保存します。

両方を保存できます。設定ファイル内に並んで存在します。--key sk-or-... は常に両者に優先します。推論コマンドはユーザーキーを優先し、管理コマンドは管理キーを優先します。優先スロットが空の場合は、どちらかが他方にフォールバックします。

出力：ストリーミング vs JSON

• TTY + 対話的コマンド → トークンを標準出力にストリーミング、ステータスを標準エラーに出力
• --json → パースされた JSON を標準出力に出力、ストリーミング、色、スピナーなし
• パイプされた標準出力（--json なし）→ コマンドがテーブルをフォーマットしない限りストリーミング継続、フォーマットする場合は安定したテキスト形式に切り替わり

エージェントの場合、常に --json を渡して応答をパースしてください。 標準エラーは診断メッセージ用にクリーンに保たれます。

終了コード

コード	意味
0	成功
1	使用法エラー / 不明なコマンド / 引数不足
2	API エラー（4xx / 5xx）。メッセージ形式：標準エラーに error: <status> <message>
3	API キー未設定
4	非同期ジョブが失敗/キャンセル状態で終了（例：video wait）

スタックトレースを出力するには OPENROUTER_DEBUG=1 を設定します。

よく使われるコマンド

推論

# ストリーミングチャット（TTY ではデフォルト）
openrouter chat "Write a haiku about caching" -m anthropic/claude-sonnet-4.5

# ワンショット、スクリプト用 JSON
openrouter --json chat "Reply: ok" -m openai/gpt-4o-mini --no-stream

# 標準入力から
echo "summarize this" | openrouter chat -m openai/gpt-4o-mini

# マルチモーダル
openrouter chat "What's in this picture?" -m google/gemini-2.5-flash --image ./photo.jpg
openrouter chat "Caption this" -m openai/gpt-4o --image https://example.com/cat.png

# 厳密な構造化出力（JSON スキーマ、厳密モード）
openrouter chat "Pick 3 fruits" -m openai/gpt-4o-mini \
  --schema '{"type":"object","properties":{"fruits":{"type":"array","items":{"type":"string"}}},"required":["fruits"],"additionalProperties":false}'

# ツール呼び出し
openrouter chat "What is 2+2?" -m openai/gpt-4o-mini \
  --tool '{"name":"add","parameters":{"type":"object","properties":{"a":{"type":"number"},"b":{"type":"number"}},"required":["a","b"]}}' \
  --tool-choice required --raw

# 推論努力
openrouter chat "tricky question" -m anthropic/claude-sonnet-4.5 --reasoning high

# プロバイダーのルーティング / フォールバックモデル
openrouter chat "..." -m primary/model --models fallback1/m,fallback2/m
openrouter chat "..." -m anthropic/claude-sonnet-4.5 --provider '{"order":["Google","Anthropic"]}'

# 対話的 REPL
openrouter chat -i -m openrouter/auto
# REPL 内：/model <id>、/reset、/exit

# Anthropic 形式と OpenAI Responses API も利用可能
openrouter messages "..." -m anthropic/claude-sonnet-4.5
openrouter responses "..." -m openai/gpt-4o-mini

# エンベディング、リランク、TTS、ビデオ
openrouter embed -m openai/text-embedding-3-small "hello" "world"
openrouter rerank -m cohere/rerank-v3.5 --query "italian food" -d pizza -d sushi -d pasta
openrouter speech "Hello there" -m elevenlabs/eleven-turbo-v2 --voice alloy -o out.mp3
openrouter video create "a sunset over mountains" -m google/veo-3
openrouter video wait <jobId> && openrouter video download <jobId> -o out.mp4

発見と価格設定

# カタログを閲覧・フィルタ・ソート
openrouter models                                       # すべて（約 370）
openrouter models --filter sonnet --sort prompt         # 最安優先
openrouter models --free                                # :free モデルのみ
openrouter models --output-modalities image             # 画像出力モデル
openrouter models --supported tools                     # 機能でフィルタ

# 1 モデルの完全詳細：価格内訳、アーキテクチャ、サポートパラメータ
openrouter models show anthropic/claude-sonnet-4.5

# 1 つのモデルのプロバイダーバリアント比較 — 最適なものを検索
openrouter models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best
openrouter models endpoints openai/gpt-4o-mini --sort latency
openrouter models endpoints openai/gpt-4o-mini --sort prompt

# サポートメタデータ
openrouter providers                                    # すべてのプロバイダー
openrouter embed models                                 # エンベディングモデル
openrouter video models                                 # ビデオ生成モデル
openrouter zdr                                          # ZDR 対応エンドポイント

アカウント / 支出 / 実行

openrouter credits                       # 総残高 + 総使用量
openrouter whoami                        # ラベル、日次/週次/月次使用状況、レート制限
openrouter generation gen-1234567890     # 完全なリクエスト別メタデータ + コスト
openrouter generation gen-1234567890 --content   # + 入力/出力コンテンツ

# アクティビティ（管理キー必須） — エンドポイント別の日次集計
openrouter activity --date 2026-04-28
openrouter activity --api-key-hash <hash>

注：activity は過去 30 日間内の完了した UTC 日のみをカバーします。本日のデータは明日まで照会できません。リクエスト別ログエンドポイントはありません。呼び出し時に ID を保存した場合、特定のインフライトリクエストを検査する唯一の方法は generation <id> によるものです。

generation の検索には、リクエスト完了後、約 30 秒の伝播遅延があります。

キー管理（管理キー必須）

openrouter keys list
openrouter keys create "agent key" --limit 25 --limit-reset monthly
openrouter keys get <hash>
openrouter keys update <hash> --name "renamed" --limit 50
openrouter keys update <hash> --disabled
openrouter keys delete <hash>

完全な sk-or-v1-... シークレットは create レスポンスで1 回だけ返されます。その時点でキャプチャしてください。

ガードレール / ワークスペース / 組織

openrouter guardrails list
openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-zdr
openrouter guardrails update <id> --limit-usd 10 --reset-interval daily
openrouter guardrails assign-key <id> <key-hash>
openrouter guardrails delete <id>

openrouter workspaces list
openrouter workspaces create "staging" --slug staging --default-text-model openai/gpt-4o-mini
openrouter workspaces add-members <id|slug> <user_id> [<user_id>...]
openrouter workspaces delete <id|slug>

openrouter org members

生エスケープハッチ

まだファーストクラスサブコマンドを持たないエンドポイント（または OpenRouter が提供する新しいエンドポイント）の場合：

openrouter request GET /credits
openrouter request POST /chat/completions --body @body.json
openrouter request POST /chat/completions --body - < body.json     # 標準入力
openrouter request GET /models --query category=programming --query supported_parameters=tools
openrouter request POST /audio/speech --body @speech.json --binary out.mp3
openrouter request GET /key --header "X-Custom: value"

エージェント向けパターン

jq にパイプ

openrouter --json models --filter sonnet | jq -r '.data[].id'
openrouter --json chat "Say hi" -m openrouter/auto | jq -r '.choices[0].message.content'
openrouter --json credits | jq '.data.total_credits - .data.total_usage'

高速失敗

if ! openrouter --json chat "..." -m model > /tmp/r.json; then
  echo "API call failed (exit $?)" >&2
  exit 1
fi

後の監査用に生成 ID を保存

out=$(openrouter --json chat "..." -m openai/gpt-4o-mini)
gen_id=$(echo "$out" | jq -r '.id')
echo "$out" | jq -r '.choices[0].message.content'
# ...後で、約 30 秒後...
openrouter generation "$gen_id" --content

ロックする前に最適なプロバイダーバリアントを選択

# 指定されたモデルの最安プロバイダー
openrouter --json models endpoints openai/gpt-4o-mini --sort prompt --best \
  | jq -r '.data.endpoints[0] | "\(.provider_name): $\(.pricing.prompt)/tok"'

# 最高スループットプロバイダー
openrouter --json models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best \
  | jq -r '.data.endpoints[0] | "\(.provider_name) @ \(.throughput_last_30m.p50) tok/s"'

特定のキーの支出を確認

openrouter --json keys get <hash> | jq '.data | {usage, usage_daily, limit_remaining}'

落とし穴と注意点

• --json はサブコマンド BEFORE に来る必要があります。グローバルプリパーサーが確実に選択するためです。openrouter --json chat ...（正しい）、openrouter chat ... --json も機能しますが、ポジショナル引数の場合は若干堅牢性が低くなります。
• 生成検索には約 30 秒のラグがあります。 これより高速にポーリングしないでください。404 が返されるだけです。
• アクティビティは日次集計で、完了した UTC 日のみをカバーします。 本日の問い合わせは 400 Date must be within the last 30 (completed) UTC days を返します。
• スピーチ（/audio/speech）は現在 OpenRouter でのモデル可用性が限定的です。 CLI は有効なリクエストを送信しますが、API は多くのモデル ID について Model X does not exist を返す場合があります。
• auth-code は OpenAPI spec が管理キーでも機能することを示唆しているにもかかわらず、Clerk セッション JWT が必要です。 OpenRouter がサーバー動作をスペックに合わせるまで、そのサブコマンドをベストエフォートとして扱います。
• rate_limit フィールドは OpenRouter で非推奨です。 -1 req / 10s として表示される場合があります。逐語的に表示されます。
• 管理キーは推論を実行できません。 管理キーのみを保存していて openrouter chat を実行すると、OpenRouter は 401 User not found で拒否します。ユーザーキーも保存してください。

設定リファレンス

フラグ	環境変数	デフォルト
-k, --key	OPENROUTER_API_KEY / OPENROUTER_MANAGEMENT_KEY	config から
--base-url	OPENROUTER_BASE_URL	https://openrouter.ai/api/v1
--referer	OPENROUTER_REFERER	https://github.com/openrouter-cli
--title	OPENROUTER_TITLE	openrouter-cli
--json	—	オフ
-q, --quiet	—	オフ
—	NO_COLOR	TTY では色オン
—	OPENROUTER_DEBUG=1	オフ

設定ファイルの場所：$XDG_CONFIG_HOME/openrouter/config.json（デフォルトは ~/.config/openrouter/config.json）。0700 ディレクトリ / 0600 ファイルで作成されます。

ヘルプ

すべてのコマンドは独自の --help を持ちます：

openrouter --help
openrouter chat --help
openrouter models --help
openrouter keys --help
openrouter guardrails --help
# ...など

リポジトリ：https://github.com/aaronjmars/openroutercli OpenRouter ドキュメント：https://openrouter.ai/docs