@aaronjmars/openroutercli 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -73,7 +73,7 @@ and run `openrouter login --management`.
73
73
  | **OAuth PKCE login** | `openrouter login` opens the browser, catches the callback locally, exchanges the code, and stores the key - `0600` perms in `~/.config/openrouter/`. No paste-an-API-key dance. |
74
74
  | **Two-slot key management** | User key + management/provisioning key live in separate slots. `keys`, `byok`, `guardrails`, `workspaces`, `observability`, `activity` auto-pick the management key; everything else uses the user key. `--key` always wins. |
75
75
  | **Streaming + JSON modes** | Streams in a TTY, switches to JSON when piped or `--json` is set. No global flag plumbing - works on every command. |
76
- | **Chat with everything** | Tool calls (`--tool @file.json --tool-choice required`), server tools (`--server-tool web_search`), deferred tool loading, structured output (`--schema schema.json`), JSON mode, multimodal images (`--image url\|path`), image output (`--modalities text,image`), reasoning effort, automatic prompt caching (`--cache --cache-ttl 1h`) and OpenAI explicit caching (`--cache-ttl 30m|12h`), alignment rules (`--rule`), provider routing, fallback models, service tiers, sessions and traces, full sampling controls. |
76
+ | **Chat with everything** | Tool calls (`--tool @file.json --tool-choice required`), server tools (`--server-tool web_search`), deferred tool loading, structured output (`--schema schema.json`), JSON mode, multimodal images (`--image url\|path`), image output (`--modalities text,image`), reasoning effort, automatic prompt caching (`--cache --cache-ttl 1h`), OpenAI explicit caching (`--cache-ttl 30m|12h`) and free repeat responses (`--response-cache`), alignment rules (`--rule`), provider routing, fallback models, service tiers, sessions and traces, full sampling controls. |
77
77
  | **Interactive REPL** | `openrouter chat -i` - slash commands `/model <id>`, `/reset`, `/exit`. History preserved per session. |
78
78
  | **Multi-format inference** | `chat` (OpenAI), `messages` (Anthropic), `responses` (OpenAI Responses) - same auth, same flags, same JSON contract. |
79
79
  | **Batches** | `batches {create,list,get,wait,results,delete}` - send a JSONL file of chat / responses / messages / embeddings requests as one async job at about half price. |
@@ -81,7 +81,7 @@ and run `openrouter login --management`.
81
81
  | **Model discovery with detail** | `models list` (filter, sort by price/context), `models show <id>` (full pricing breakdown - prompt, completion, cache r/w, reasoning, image, web search), `models endpoints <id> --sort throughput\|latency\|prompt\|completion\|uptime --best` for choosing the right provider variant. |
82
82
  | **Benchmarks + rankings** | `benchmarks`, `classifications`, and `datasets {apps,daily,session-cost}` expose OpenRouter's current public benchmark and usage datasets. |
83
83
  | **Management analytics** | `analytics meta` discovers fields; `analytics query` runs metrics/dimensions/time-range queries with a management key. |
84
- | **Structured decisions** | `decisions` (alias `systemone`) calls System One for typed choice, score, and yes/no outputs, with optional image inputs. |
84
+ | **Structured decisions** | `decisions` (alias `systemone`) calls System One for typed choice, score, and yes/no outputs, with optional image inputs (`--image`) and named image assets (`--assets`). |
85
85
  | **Server tools catalog** | `tools list` / `tools get <name>` - every OpenRouter-run tool (web search, fetch, datetime, ...) with params, engines and pricing. |
86
86
  | **Hosted shell files** | `containers {list,get,download,promote}` retrieves and promotes files produced by OpenRouter's hosted shell tools. |
87
87
  | **Spend + activity + generations** | `credits` for balance, `whoami` for daily/weekly/monthly usage + rate limit, `keys get <hash>` for per-key spend, `activity --api-key-hash <hash>` for daily aggregates, `generation <id> [--content]` for full per-request metadata + input/output. |
@@ -138,6 +138,7 @@ openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
138
138
  # Discovery
139
139
  openrouter models --filter claude --sort prompt
140
140
  openrouter models user --order newest
141
+ openrouter models user --client codex # only models a coding harness offers
141
142
  openrouter models show anthropic/claude-sonnet-4.5
142
143
  openrouter models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best
143
144
  openrouter providers
@@ -150,6 +151,7 @@ openrouter activity --date 2026-04-28 --api-key-hash <hash>
150
151
  # Management (provisioning key required)
151
152
  openrouter keys create "agent-key" --limit 25 --limit-reset monthly
152
153
  openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-zdr
154
+ openrouter guardrails update <id> --harness-models # harness clients see only first-party models
153
155
  openrouter workspaces create "staging" --slug staging --default-text-model openai/gpt-4o-mini
154
156
  openrouter workspaces budgets set staging monthly --limit 100
155
157
  openrouter observability create "langfuse" --type langfuse --config @langfuse.json
package/SKILL.md CHANGED
@@ -239,6 +239,7 @@ openrouter models --free # only :free models
239
239
  openrouter models --input-modalities image # image-INPUT (vision) models
240
240
  openrouter models --output-modalities image # image-OUTPUT models
241
241
  openrouter models user --order newest # account-filtered models, server-side sort
242
+ openrouter models user --client codex # models the named harness offers (claude_code|claude_desktop|codex); honors --harness-models guardrails
242
243
  openrouter models --supported tools # filter by capability
243
244
  # Full detail for one model: pricing breakdown, architecture, supported params,
244
245
  # reasoning config, supported voices
@@ -257,6 +258,7 @@ openrouter datasets daily --period week --category programming
257
258
  openrouter analytics meta
258
259
  openrouter decisions --model typesafe/jev-1.13 --state '...' --questions @questions.json # alias: systemone
259
260
  openrouter decisions --model <vision-decider> --state '...' --image ./chart.png --questions @q.json
261
+ openrouter decisions --model typesafe/jev-1.14 --state '... image: logo' --assets '{"logo":"./logo.png"}' --questions @q.json
260
262
  openrouter containers list <container-id>
261
263
 
262
264
  # Supporting metadata
@@ -315,6 +317,7 @@ openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-z
315
317
  openrouter guardrails update <id> --limit-usd 10 --reset-interval daily --include-byok
316
318
  openrouter guardrails update <id> --regions europe --builtin-filters email:redact,secrets:block --no-paid-training
317
319
  openrouter guardrails update <id> --allow-safety-retention-google --no-allow-safety-retention-other
320
+ openrouter guardrails update <id> --harness-models # codex/claude harnesses only see their vendor's models
318
321
  openrouter guardrails assign-key <id> <key-hash> # up to 500 hashes per call
319
322
 
320
323
  openrouter workspaces list
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aaronjmars/openroutercli",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Command-line interface for the OpenRouter API. Built for humans and LLM agents.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -209,11 +209,14 @@ ${SERVER_TOOL_HELP} --reasoning <effort> none|minimal|low|medium|high|xhigh
209
209
  --reasoning-max-tokens <n> Reasoning token budget (Anthropic-style)
210
210
  --reasoning-exclude Reason internally but omit reasoning from the output
211
211
  --provider <json|@file> Provider routing (order, only, sort, ...;
212
- options: per-provider passthrough keyed by slug)
212
+ options: per-provider passthrough keyed by slug).
213
+ Default routing weighs quality-per-cost; sort:price or
214
+ a :floor model suffix keeps the cheapest-first order
213
215
  --modalities <csv> Output modalities: text,image,audio
214
216
  --image-config <json|@file> Image output options, e.g. {"aspect_ratio":"16:9"}
215
217
  --prediction <text|@file> Predicted output (prediction.content) to cut latency
216
- --prompt-cache-key <k> Provider prompt-cache key
218
+ --response-cache X-OpenRouter-Cache: free repeat responses for
219
+ identical requests (separate from --cache prompt caching)
217
220
  --metadata <json|@file> String key/value pairs (max 16)
218
221
  ${CACHE_HELP} --cache-system Mark the system prompt as a cache breakpoint
219
222
  --cache-user Mark the user prompt as a cache breakpoint
@@ -495,13 +498,13 @@ function printUsage(model, usage) {
495
498
  );
496
499
  }
497
500
 
498
- async function streamResponse(body, auth) {
501
+ async function streamResponse(body, auth, extraHeaders) {
499
502
  const res = await withAlignmentErrors(
500
503
  api("POST", "/chat/completions", {
501
504
  auth,
502
505
  body: { ...body, stream: true },
503
506
  raw: true,
504
- headers: { Accept: "text/event-stream" },
507
+ headers: { Accept: "text/event-stream", ...extraHeaders },
505
508
  }),
506
509
  );
507
510
  let usage = null;
@@ -594,6 +597,7 @@ export async function chatCommand(argv) {
594
597
  "image-config": { type: "string" },
595
598
  prediction: { type: "string" },
596
599
  "prompt-cache-key": { type: "string" },
600
+ "response-cache": { type: "boolean" },
597
601
  metadata: { type: "string" },
598
602
  image: { type: "string", multiple: true },
599
603
  file: { type: "string", multiple: true },
@@ -643,7 +647,10 @@ export async function chatCommand(argv) {
643
647
  const body = await buildBody(values, prompt);
644
648
 
645
649
  if (!shouldStream(values)) {
646
- const data = await withAlignmentErrors(api("POST", "/chat/completions", { auth, body }));
650
+ const rcHeaders = values["response-cache"] ? { "X-OpenRouter-Cache": "true" } : undefined;
651
+ const data = await withAlignmentErrors(
652
+ api("POST", "/chat/completions", { auth, body, headers: rcHeaders }),
653
+ );
647
654
  if (isJsonMode() || values.raw) {
648
655
  printJSON(data);
649
656
  } else {
@@ -671,7 +678,11 @@ export async function chatCommand(argv) {
671
678
  return 0;
672
679
  }
673
680
 
674
- const meta = await streamResponse(body, auth);
681
+ const meta = await streamResponse(
682
+ body,
683
+ auth,
684
+ values["response-cache"] ? { "X-OpenRouter-Cache": "true" } : undefined,
685
+ );
675
686
  if (values.usage && meta.usage) printUsage(meta.model, meta.usage);
676
687
  if (ERROR_FINISH_REASONS.includes(meta.finishReason)) {
677
688
  process.stderr.write(`error: generation stopped (${meta.finishReason})\n`);
@@ -16,6 +16,9 @@ Options:
16
16
  --questions <json> Questions object or @questions.json
17
17
  --image <url|path> Add an image to the state (repeatable). Local files
18
18
  are sent as data URLs. For multimodal models.
19
+ --assets <json|@file> Named images referenced from state/instructions/
20
+ criteria: {"ref-name": "<local path>"} (png/jpg/jpeg;
21
+ uploaded as data_base64). Every name must be referenced.
19
22
  --body <json|@file> Fully-formed request body
20
23
  --extra <json> Extra fields merged into the request
21
24
  --alpha Use the older /api/alpha/decisions route
@@ -57,6 +60,7 @@ export async function decisionsCommand(argv) {
57
60
  state: { type: "string" },
58
61
  questions: { type: "string" },
59
62
  image: { type: "string", multiple: true },
63
+ assets: { type: "string" },
60
64
  body: { type: "string" },
61
65
  extra: { type: "string" },
62
66
  alpha: { type: "boolean" },
@@ -81,6 +85,26 @@ export async function decisionsCommand(argv) {
81
85
  const parts = await Promise.all(images.map(imagePart));
82
86
  body.state = withImages(body.state, parts);
83
87
  }
88
+ if (values.assets !== undefined) {
89
+ const assets = await loadJson(values.assets, "--assets");
90
+ if (!assets || typeof assets !== "object" || Array.isArray(assets)) {
91
+ throw new Error('--assets must be a JSON object like {"ref": "<path>"}');
92
+ }
93
+ body.assets = {};
94
+ for (const [name, src] of Object.entries(assets)) {
95
+ const url = await mediaUrl(src);
96
+ if (!url.startsWith("data:")) {
97
+ throw new Error(
98
+ `--assets "${name}": the Decisions API only accepts uploaded images. Give a local file (png/jpg/jpeg), not a URL.`,
99
+ );
100
+ }
101
+ const [mime, b64] = url.slice(5).split(";base64,");
102
+ const format = { "image/png": "png", "image/jpeg": "jpeg" }[mime];
103
+ if (!format)
104
+ throw new Error(`--assets "${name}": expected a png/jpg/jpeg image, got ${mime}`);
105
+ body.assets[name] = { type: "image", format, data_base64: b64 };
106
+ }
107
+ }
84
108
  if (values.extra) Object.assign(body, await loadJson(values.extra, "--extra"));
85
109
  const data = values.alpha
86
110
  ? await api("POST", "/decisions", {
@@ -57,6 +57,10 @@ create / update options:
57
57
  Allow ZDR requests to google/* to use endpoints that retain for safety
58
58
  --allow-safety-retention-other / --no-allow-safety-retention-other
59
59
  Allow ZDR requests to other models to use endpoints that retain for safety
60
+ --harness-models / --no-harness-models
61
+ enforce_first_party_harness_models: when a coding
62
+ harness (claude_code, claude_desktop, codex) lists
63
+ models, show only the harness vendor's own
60
64
  --include-byok / --no-include-byok Count BYOK spend toward the budget
61
65
  --workspace <uuid> (create only)
62
66
  --extra <json|@file> Extra body fields, merged last (e.g. enforce_zdr_xai:false)
@@ -151,6 +155,7 @@ async function buildBody(values) {
151
155
  ["enable_paid_model_training", "paid-training"],
152
156
  ["allow_safety_retention_google", "allow-safety-retention-google"],
153
157
  ["allow_safety_retention_other", "allow-safety-retention-other"],
158
+ ["enforce_first_party_harness_models", "harness-models"],
154
159
  ];
155
160
  for (const [field, flag] of toggles) {
156
161
  const v = toggle(values, flag, `no-${flag}`);
@@ -192,6 +197,8 @@ const COMMON_FIELDS = {
192
197
  "no-allow-safety-retention-google": { type: "boolean" },
193
198
  "allow-safety-retention-other": { type: "boolean" },
194
199
  "no-allow-safety-retention-other": { type: "boolean" },
200
+ "harness-models": { type: "boolean" },
201
+ "no-harness-models": { type: "boolean" },
195
202
  extra: { type: "string" },
196
203
  };
197
204
 
@@ -426,13 +426,14 @@ export async function modelsCommand(argv) {
426
426
  "output-modalities": { type: "string" },
427
427
  order: { type: "string" },
428
428
  sort: { type: "string" },
429
+ client: { type: "string" },
429
430
  });
430
431
  } catch (err) {
431
432
  // `models user` used to forward every list filter; the endpoint only
432
433
  // takes these, so say so instead of a bare "Unknown option".
433
434
  if (err.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
434
435
  throw new Error(
435
- `${err.message.split(".")[0]}. models user only supports --output-modalities, --order/--sort, --limit and --offset; use \`openrouter models list\` for search filters.`,
436
+ `${err.message.split(".")[0]}. models user only supports --output-modalities, --order/--sort, --client, --limit and --offset; use \`openrouter models list\` for search filters.`,
436
437
  );
437
438
  }
438
439
  throw err;
@@ -447,6 +448,10 @@ export async function modelsCommand(argv) {
447
448
  "Options:\n" +
448
449
  " --output-modalities <csv> text,image,embeddings,audio,video,rerank,decisions,\n" +
449
450
  ' speech,transcription (or "all"). Default: text\n' +
451
+ " --client <harness> Only models the named coding harness offers:\n" +
452
+ " claude_code | claude_desktop | codex. When a\n" +
453
+ " guardrail sets enforce_first_party_harness_models,\n" +
454
+ " only the harness vendor's own models.\n" +
450
455
  " --order <sort> Server-side sort: most-popular|newest|top-weekly|\n" +
451
456
  " pricing-low-to-high|pricing-high-to-low|\n" +
452
457
  " context-high-to-low|throughput-high-to-low|\n" +
@@ -462,6 +467,14 @@ export async function modelsCommand(argv) {
462
467
  const query = paginationQuery(values);
463
468
  if (values["output-modalities"]) query.output_modalities = values["output-modalities"];
464
469
  if (values.order || values.sort) query.sort = values.order || values.sort;
470
+ if (values.client) {
471
+ if (!["claude_code", "claude_desktop", "codex"].includes(values.client)) {
472
+ throw new Error(
473
+ `Unknown --client "${values.client}". Expected: claude_code, claude_desktop, codex`,
474
+ );
475
+ }
476
+ query.client = values.client;
477
+ }
465
478
  const data = await api("GET", "/models/user", {
466
479
  auth: authFromValues(values),
467
480
  query,
@@ -35,6 +35,13 @@ create / update options:
35
35
  {"publicKey":"pk-lf-...","secretKey":"sk-lf-...",
36
36
  "baseUrl":"https://cloud.langfuse.com"}. Clickhouse and
37
37
  Snowflake accept "shouldIncludeCacheWriteTokens": true.
38
+ For s3, key auth: {"accessKeyId":"...",
39
+ "secretAccessKey":"...",...} or IAM role auth:
40
+ {"authMode":"iam_role","provider":"aws",
41
+ "roleArn":"arn:aws:iam::<acct>:role/<name>",
42
+ "region":"<region>","externalId":"<id>"} (GovCloud and
43
+ China ARNs rejected; trust policy must require the
44
+ external id).
38
45
  On update, masked values are ignored and unset fields
39
46
  keep their value.
40
47
  --name <name> (update only)