pp-openrouter
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseOpenRouter — Printing Press CLI
OpenRouter — Printing Press CLI
Prerequisites: Install the CLI
前提条件:安装CLI
This skill drives the binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
openrouter-pp-cli- Install via the Printing Press installer:
bash
npx -y @mvanhorn/printing-press install openrouter --cli-only - Verify:
openrouter-pp-cli --version - Ensure (or
$GOPATH/bin) is on$HOME/go/bin.$PATH
If the install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):
npxbash
go install github.com/mvanhorn/printing-press-library/library/ai/openrouter/cmd/openrouter-pp-cli@latestIf reports "command not found" after install, the install step did not put the binary on . Do not proceed with skill commands until verification succeeds.
--version$PATHOther OpenRouter CLIs are chat REPLs. This one is built for the cron job and the AI agent calling out to . Absorbed introspection commands (, , , , ) honor the global flag (sets --json --compact --no-input). Eight novel commands (, , , , , , , ) ship a mode that returns under 200 tokens of key:value output. A local SQLite catalog lets you query the 400+ model list with instead of pasting 425KB of JSON into context.
Bashcreditsmodelskeygenerationproviders--agentusage cost-bymodels querykey etaproviders degradedgeneration explainusage anomalyendpoints failoverbudget--llmmodels query "tools=true cost.completion<1"本Skill驱动二进制文件。在调用本Skill的任何命令之前,您必须确认CLI已安装。 如果未安装,请先执行以下步骤:
openrouter-pp-cli- 通过Printing Press安装器安装:
bash
npx -y @mvanhorn/printing-press install openrouter --cli-only - 验证安装:
openrouter-pp-cli --version - 确保(或
$GOPATH/bin)已添加到$HOME/go/bin环境变量中。$PATH
如果安装失败(无Node环境、离线等),可改用Go直接安装(要求Go 1.26.3或更高版本):
npxbash
go install github.com/mvanhorn/printing-press-library/library/ai/openrouter/cmd/openrouter-pp-cli@latest如果安装后执行提示“command not found”,说明安装程序未将二进制文件添加到中。在验证成功前,请不要执行Skill命令。
--version$PATH其他OpenRouter CLI多为聊天式REPL工具,而本CLI专为cron任务和调用Bash的AI Agent设计。集成的自省命令(、、、、)支持全局标志(自动设置--json --compact --no-input)。新增的8个命令(、、、、、、、)提供模式,返回不超过200个token的键值对输出。本地SQLite目录支持通过查询400+模型列表,无需将425KB的JSON内容粘贴到上下文环境中。
creditsmodelskeygenerationproviders--agentusage cost-bymodels querykey etaproviders degradedgeneration explainusage anomalyendpoints failoverbudget--llmmodels query "tools=true cost.completion<1"When to Use This CLI
何时使用本CLI
Use this CLI when an AI agent needs OpenRouter introspection data and you're optimizing for token efficiency. Absorbed commands accept for compact JSON; the 8 novel commands ship mode for terse key:value output. Use it when you need cost attribution beyond model+provider (which-cron-fired-the-call). Use it for pre-flight gates in bash compositions and for local-catalog querying that would otherwise blow context. Skip it for chat — use for chat ergonomics.
--agent--llmgrahamking/ort当AI Agent需要OpenRouter自省数据且您希望优化token效率时,使用本CLI。集成的命令支持标志以输出紧凑JSON;8个新增命令提供模式以输出简洁键值对。当您需要超越模型+服务商的成本归因(如确定哪个cron任务触发了调用)时使用它。在bash组合中用于预检查,或用于避免上下文过载的本地目录查询。如果是聊天场景,请使用以获得更优的聊天体验。
--agent--llmgrahamking/ortUnique Capabilities
独特功能
These capabilities aren't available in any other tool for this API.
这些功能是其他同类型API工具所不具备的。
Local state that compounds
可累积的本地状态
-
— Group your OpenRouter spend by which cron/agent fired the call, not just by model. Joins local generations with caller tags from your tool-call logger.
usage cost-byUse this when an agent needs to answer 'which automated job is burning my OpenRouter budget?' before deciding what to throttle.bashopenrouter usage cost-by --group cron --since 7d --llm -
— Query the model catalog with structured filters (tools=true, cost.completion<1, ctx>=64k) — compiled to SQL over a local SQLite cache. Works offline.
models queryUse this when an agent needs to shortlist models for an experiment without hallucinating pricing or pasting 400 model rows into context.bashopenrouter models query "tools=true cost.completion<1 ctx>=64k modality=text" --llm -
— For a generation id, returns the cost, latency, prompt/completion token counts, AND a delta vs the cheapest provider for the same model+token-count.
generation explainUse this when an agent needs to decide whether a generation was expensive because of the model choice, the prompt size, or the provider markup.bashopenrouter generation explain gen-abc123 --llm
-
— 按触发调用的cron/Agent分组统计OpenRouter支出,而非仅按模型分组。将本地生成记录与工具调用日志中的调用者标签关联。
usage cost-by当Agent需要回答“哪个自动化任务消耗了我的OpenRouter预算?”并决定限流策略时使用此命令。bashopenrouter usage cost-by --group cron --since 7d --llm -
— 使用结构化过滤器(tools=true, cost.completion<1, ctx>=64k)查询模型目录——基于本地SQLite缓存编译为SQL查询。支持离线使用。
models query当Agent需要为实验筛选模型,且避免生成定价幻觉或在上下文粘贴400条模型记录时使用此命令。bashopenrouter models query "tools=true cost.completion<1 ctx>=64k modality=text" --llm -
— 针对指定生成ID,返回成本、延迟、提示/完成token数,以及与相同模型+token数下最便宜服务商的差异对比。
generation explain当Agent需要判断生成成本过高是由于模型选择、提示长度还是服务商加价导致时使用此命令。bashopenrouter generation explain gen-abc123 --llm
Agent-native plumbing
原生适配Agent的基础功能
-
— Returns the set of currently-degraded provider/model pairs by polling /providers and per-model /endpoints. Pipe into your router to preempt 429s.
providers degradedUse this in a router or fallback chain when an agent needs to skip degraded provider/model pairs before dispatch instead of after a failed call.bashopenrouter providers degraded --json | jq -r '.[].model_id' -
— Flags days where per-model cost exceeds 2σ of the trailing 7-day mean. Deterministic z-score, no LLM in the loop. Designed for cron.
usage anomalyUse this in a daily cron when an agent needs to detect cost regressions before a credit-low alarm fires.bashopenrouter usage anomaly --since 24h --baseline 7d --llm -
— Projects when your weekly OpenRouter cap will trip, based on /key.limit_reset, current usage, and your trailing 7-day burn rate.
key etaUse this in a daily cron when an agent needs to know whether scheduled work will fit in the remaining weekly cap.bashopenrouter key eta --llm -
— Set a weekly USD cap per cron job (budget set scan-pipeline 2usd). Pre-flight check returns exit 0 (under cap) or 8 (over) from tagged generations.
budgetUse this when an agent needs structural budget enforcement per sub-agent or per cron, not aspirational env-var quotas.bashopenrouter budget check scan-pipeline && ./scan-pipeline.mjs -
— For a model id, lists all providers serving it ranked by current status, pricing, and observed p50 latency from local cache. Pipe-feeds routers.
endpoints failoverUse this when an agent needs to choose a provider for a given model based on current availability, not the static config order.bashopenrouter endpoints failover anthropic/claude-opus-4-7 --json
-
— 通过轮询/providers和各模型的/endpoints接口,返回当前故障的服务商/模型组合。可将结果导入路由工具以提前避免429错误。
providers degraded在路由或 fallback 链中使用,让Agent在调度前跳过故障的服务商/模型组合,而非在调用失败后再处理。bashopenrouter providers degraded --json | jq -r '.[].model_id' -
— 标记单模型成本超过过去7天均值2σ的日期。采用确定性z-score算法,无需LLM参与。专为cron任务设计。
usage anomaly在每日cron任务中使用,让Agent在余额不足警报触发前检测成本异常。bashopenrouter usage anomaly --since 24h --baseline 7d --llm -
— 根据/key.limit_reset、当前使用情况和过去7天的消耗速率,预测每周OpenRouter额度耗尽的时间。
key eta在每日cron任务中使用,让Agent了解剩余每周额度是否能支撑计划任务。bashopenrouter key eta --llm -
— 为每个cron任务设置每周USD额度上限(如budget set scan-pipeline 2usd)。预检查返回退出码0(未超额度)或8(已超额度),基于标记的生成记录判断。
budget当Agent需要为子Agent或cron任务设置结构化预算限制,而非依赖环境变量的软性配额时使用此命令。bashopenrouter budget check scan-pipeline && ./scan-pipeline.mjs -
— 针对指定模型ID,列出所有提供该模型的服务商,并按当前状态、定价和本地缓存的p50延迟排序。可直接为路由工具提供数据。
endpoints failover当Agent需要根据当前可用性选择模型服务商,而非依赖静态配置顺序时使用此命令。bashopenrouter endpoints failover anthropic/claude-opus-4-7 --json
Command Reference
命令参考
activity — Manage activity
- — Returns user activity data grouped by endpoint for the last 30 (completed) UTC days. [Management...
openrouter-pp-cli activity
credits — Credit management endpoints
- — Get total credits purchased and used for the authenticated user. [Management...
openrouter-pp-cli credits
endpoints — Endpoint information
- — Preview the impact of ZDR on the available endpoints
openrouter-pp-cli endpoints
generation — Generation history endpoints
- — Get request & usage metadata for a generation
openrouter-pp-cli generation get - — Get stored prompt and completion content for a generation
openrouter-pp-cli generation list-content
key — Manage key
- — Get information on the API key associated with the current authentication session
openrouter-pp-cli key
keys — Manage keys
- — Create a new API key for the authenticated user. Management key...
openrouter-pp-cli keys create - — Delete an existing API key. Management key required.
openrouter-pp-cli keys delete - — Get a single API key by hash. Management key required.
openrouter-pp-cli keys get - — List all API keys for the authenticated user. Management key required.
openrouter-pp-cli keys list - — Update an existing API key. Management key required.
openrouter-pp-cli keys update
models — Model information endpoints
- — List all models and their properties
openrouter-pp-cli models get - — Get total count of available models
openrouter-pp-cli models list-count - — List models filtered by user provider preferences, [privacy settings](https://openrouter.ai/docs/guides/privacy/provi...
openrouter-pp-cli models list-user
openrouter-auth — Manage openrouter auth
- — Create an authorization code for the PKCE flow to generate a user-controlled API key
openrouter-pp-cli openrouter-auth create-keys-code - — Exchange an authorization code from the PKCE flow for a user-controlled API key
openrouter-pp-cli openrouter-auth exchange-code-for-apikey
providers — Provider information endpoints
- — List all providers
openrouter-pp-cli providers
activity — 管理活动记录
- — 返回最近30个已完成UTC日的用户活动数据,按端点分组。[管理...
openrouter-pp-cli activity
credits — 额度管理端点
- — 获取已认证用户的总购买额度和已使用额度。[管理...
openrouter-pp-cli credits
endpoints — 端点信息
- — 预览ZDR对可用端点的影响
openrouter-pp-cli endpoints
generation — 生成历史端点
- — 获取指定生成记录的请求和使用元数据
openrouter-pp-cli generation get - — 获取指定生成记录的存储提示和完成内容
openrouter-pp-cli generation list-content
key — 管理API密钥
- — 获取与当前认证会话关联的API密钥信息
openrouter-pp-cli key
keys — 管理多API密钥
- — 为已认证用户创建新的API密钥。管理密钥...
openrouter-pp-cli keys create - — 删除现有API密钥。需要管理密钥。
openrouter-pp-cli keys delete - — 通过哈希值获取单个API密钥。需要管理密钥。
openrouter-pp-cli keys get - — 列出已认证用户的所有API密钥。需要管理密钥。
openrouter-pp-cli keys list - — 更新现有API密钥。需要管理密钥。
openrouter-pp-cli keys update
models — 模型信息端点
- — 列出所有模型及其属性
openrouter-pp-cli models get - — 获取可用模型总数
openrouter-pp-cli models list-count - — 根据用户服务商偏好、[隐私设置](https://openrouter.ai/docs/guides/privacy/provi...筛选模型
openrouter-pp-cli models list-user
openrouter-auth — 管理OpenRouter认证
- — 创建PKCE流程的授权码,用于生成用户可控的API密钥
openrouter-pp-cli openrouter-auth create-keys-code - — 将PKCE流程的授权码兑换为用户可控的API密钥
openrouter-pp-cli openrouter-auth exchange-code-for-apikey
providers — 服务商信息端点
- — 列出所有服务商
openrouter-pp-cli providers
Finding the right command
查找合适的命令
When you know what you want to do but not which command does it, ask the CLI directly:
bash
openrouter-pp-cli which "<capability in your own words>"which02--help当您知道要执行的操作但不确定对应命令时,可直接询问CLI:
bash
openrouter-pp-cli which "<用您自己的语言描述功能>"which02--helpRecipes
使用示例
Pre-flight gate before expensive cron
执行高成本cron任务前的预检查
bash
openrouter budget check scan-pipeline --jsonReturns exit 0 if under cap or 8 if over. Compose with && in bash to gate expensive jobs without half-execution.
bash
openrouter budget check scan-pipeline --json未超额度时返回退出码0,已超额度时返回退出码8。在bash中配合&&使用,可避免任务部分执行。
Cost attribution for the week
本周成本归因分析
bash
openrouter usage cost-by --group cron --since 7d --llmReturns one row per cron name with total cost — answers 'which automated job is burning my OpenRouter budget'.
bash
openrouter usage cost-by --group cron --since 7d --llm返回每个cron任务的总成本——回答“哪个自动化任务消耗了我的OpenRouter预算”。
Shortlist tool-capable cheap deep-context models (with --select narrowing)
筛选支持工具、低成本且大上下文的模型(使用--select缩小范围)
bash
openrouter models query "tools=true cost.completion<1 ctx>=64k" --agent --select id,context_length,pricing.completionLocal SQLite + dotted --select narrows ~400 models to a handful of fields. Agent context cost: ~150 tokens vs ~425KB raw.
bash
openrouter models query "tools=true cost.completion<1 ctx>=64k" --agent --select id,context_length,pricing.completion本地SQLite配合--select参数将约400个模型筛选为少量字段。Agent上下文成本:约150个token,而非约425KB的原始数据。
Detect cost regression before credit-low alarm fires
在余额不足警报触发前检测成本异常
bash
openrouter usage anomaly --since 24h --baseline 7d --llmFlags per-model days exceeding 2σ over trailing 7-day mean. Daily cron catches runaway loops 1-3 days before /credits hits zero.
bash
openrouter usage anomaly --since 24h --baseline 7d --llm标记单模型成本超过过去7天均值2σ的日期。每日cron任务可在/credits归零前1-3天发现失控循环。
Pre-empt 429s by skipping degraded providers
通过跳过故障服务商提前避免429错误
bash
openrouter providers degraded --jsonReturns {added, degraded, removed} arrays from set-diff vs prior snapshot. Pipe-feeds your router/suspension logic. Replaces reactive 429-and-learn with leading-indicator polling.
bash
openrouter providers degraded --json返回与上次快照对比的{added, degraded, removed}数组。可将结果导入路由/暂停逻辑,替代“触发429后再处理”的被动方式,转为基于前置指标的主动轮询。
Auth Setup
认证设置
Set for per-call operations (creds, models, usage, generation lookup). For sub-key management (), set separately — OpenRouter's API splits these intentionally and this CLI honors the split. Both variables are read fresh per command; nothing is persisted to disk by default.
OPENROUTER_API_KEYkeys list/create/deleteOPENROUTER_MANAGEMENT_KEYRun to verify setup.
openrouter-pp-cli doctor为单次调用操作(creds、models、usage、generation查询)设置。对于子密钥管理(),需单独设置——OpenRouter API有意拆分这两类密钥,本CLI遵循此设计。两个变量均在每次命令执行时读取,默认不会持久化到磁盘。
OPENROUTER_API_KEYkeys list/create/deleteOPENROUTER_MANAGEMENT_KEY执行验证设置是否正确。
openrouter-pp-cli doctorAgent Mode
Agent模式
Add to any command. Expands to: .
--agent--json --compact --no-input --no-color --yes-
Pipeable — JSON on stdout, errors on stderr
-
Filterable —keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
--selectbashopenrouter-pp-cli credits --agent --select id,name,status -
Previewable —shows the request without sending
--dry-run -
Offline-friendly — sync/search commands can use the local SQLite store when available
-
Non-interactive — never prompts, every input is a flag
-
Explicit retries — useonly when an already-existing create should count as success, and
--idempotentonly when a missing delete target should count as success--ignore-missing
在任何命令后添加标志,等效于设置:。
--agent--json --compact --no-input --no-color --yes-
可管道传输 — 标准输出为JSON,错误信息输出到标准错误
-
可筛选 —参数保留指定字段。点路径可深入嵌套结构;数组可遍历元素。对于输出冗长的API,这是缩小上下文的关键:
--selectbashopenrouter-pp-cli credits --agent --select id,name,status -
可预览 —参数显示请求内容但不发送
--dry-run -
离线友好 — 同步/搜索命令可在本地SQLite存储可用时使用该存储
-
非交互式 — 从不弹出提示,所有输入均通过标志传递
-
显式重试 — 仅当已存在的创建操作应视为成功时使用;仅当删除目标不存在应视为成功时使用
--idempotent--ignore-missing
Response envelope
响应包
Commands that read from the local store or the API wrap output in a provenance envelope:
json
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <data>
}Parse for data and to know whether it's live or local. A human-readable summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
.results.meta.sourceN results (live)从本地存储或API读取数据的命令会将输出包装在来源信息包中:
json
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <data>
}解析获取数据,表示数据来自实时API还是本地存储。仅当标准输出为终端时,才会在标准错误输出打印人类可读的摘要;管道/Agent消费者仅会在标准输出获取纯JSON。
.results.meta.sourceN results (live)Agent Feedback
Agent反馈
When you (or the agent) notice something off about this CLI, record it:
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 10Entries are stored locally at . They are never POSTed unless is set AND either is passed or . Default behavior is local-only.
~/.openrouter-pp-cli/feedback.jsonlOPENROUTER_FEEDBACK_ENDPOINT--sendOPENROUTER_FEEDBACK_AUTO_SEND=trueWrite what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
当您(或Agent)发现本CLI存在问题时,可记录反馈:
openrouter-pp-cli feedback "--since标志是包含性的,但文档说是排他性的"
openrouter-pp-cli feedback --stdin < notes.txt
openrouter-pp-cli feedback list --json --limit 10反馈条目存储在本地文件中。除非设置了且传递了参数或设置,否则反馈不会被POST提交。默认仅存储在本地。
~/.openrouter-pp-cli/feedback.jsonlOPENROUTER_FEEDBACK_ENDPOINT--sendOPENROUTER_FEEDBACK_AUTO_SEND=true请记录让您感到意外的内容,而非正式的bug报告。简短、具体、单行描述:这类反馈的价值会不断累积。
Output Delivery
输出交付
Every command accepts . The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
--deliver <sink>| Sink | Effect |
|---|---|
| Default; write to stdout only |
| Atomically write output to |
| POST the output body to the URL ( |
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
每个命令均支持参数。输出会发送到指定目标,同时(或替代)输出到标准输出,以便Agent无需手动管道即可路由命令结果。支持三种目标:
--deliver <sink>| 目标 | 效果 |
|---|---|
| 默认值;仅输出到标准输出 |
| 原子性地将输出写入 |
| 将输出体POST到指定URL(当使用 |
不支持的协议会返回结构化错误,并列出支持的目标类型。Webhook失败时返回非零退出码,并在标准错误输出记录URL和HTTP状态码。
Named Profiles
命名配置文件
A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
openrouter-pp-cli profile save briefing --json
openrouter-pp-cli --profile briefing credits
openrouter-pp-cli profile list --json
openrouter-pp-cli profile show briefing
openrouter-pp-cli profile delete briefing --yesExplicit flags always win over profile values; profile values win over defaults. lists all available profiles under so introspecting agents discover them at runtime.
agent-contextavailable_profiles配置文件是一组保存的标志值,可在多次调用中复用。当定时Agent每次运行都使用相同配置调用同一命令时使用此功能——即HeyGen的“Beacon”模式。
openrouter-pp-cli profile save briefing --json
openrouter-pp-cli --profile briefing credits
openrouter-pp-cli profile list --json
openrouter-pp-cli profile show briefing
openrouter-pp-cli profile delete briefing --yes显式标志始终优先于配置文件值;配置文件值优先于默认值。会在下列出所有可用配置文件,以便自省Agent在运行时发现它们。
agent-contextavailable_profilesExit Codes
退出码
| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | Usage error (wrong arguments) |
| 3 | Resource not found |
| 4 | Authentication required |
| 5 | API error (upstream issue) |
| 7 | Rate limited (wait and retry) |
| 10 | Config error |
| 代码 | 含义 |
|---|---|
| 0 | 成功 |
| 2 | 使用错误(参数错误) |
| 3 | 资源未找到 |
| 4 | 需要认证 |
| 5 | API错误(上游问题) |
| 7 | 速率限制(请等待后重试) |
| 10 | 配置错误 |
Argument Parsing
参数解析
Parse :
$ARGUMENTS- Empty, , or
help→ show--helpoutputopenrouter-pp-cli --help - Starts with → ends with
install→ MCP installation; otherwise → see Prerequisites abovemcp - Anything else → Direct Use (execute as CLI command with )
--agent
解析的逻辑:
$ARGUMENTS- 为空、或
help→ 显示--help输出openrouter-pp-cli --help - 以开头 → 若结尾为
install→ 安装MCP;否则 → 参考顶部的前提条件部分mcp - 其他情况 → 直接使用(添加标志执行CLI命令)
--agent
MCP Server Installation
MCP服务器安装
Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:
bash
claude mcp add openrouter-pp-mcp -- openrouter-pp-mcpVerify:
claude mcp list从本CLI的公开库条目或预构建版本安装MCP二进制文件,然后注册:
bash
claude mcp add openrouter-pp-mcp -- openrouter-pp-mcp验证安装:
claude mcp listDirect Use
直接使用
- Check if installed: If not found, offer to install (see Prerequisites at the top of this skill).
which openrouter-pp-cli - Match the user query to the best command from the Unique Capabilities and Command Reference above.
- Execute with the flag:
--agentbashopenrouter-pp-cli <command> [subcommand] [args] --agent - If ambiguous, drill into subcommand help: .
openrouter-pp-cli <command> --help
- 检查是否已安装:若未找到,提供安装选项(参考顶部前提条件部分)。
which openrouter-pp-cli - 将用户查询与上述独特功能和命令参考中的最佳命令匹配。
- 添加标志执行命令:
--agentbashopenrouter-pp-cli <command> [subcommand] [args] --agent - 若存在歧义,查看子命令帮助:。
openrouter-pp-cli <command> --help