@aaronjmars/openroutercli 0.5.0 → 0.6.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`), 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`) and OpenAI explicit caching (`--cache-ttl 30m|12h`), 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. |
package/SKILL.md CHANGED
@@ -163,6 +163,9 @@ openrouter chat "summarize this" -m google/gemini-2.5-flash --file ./report.pdf
163
163
  # Prompt caching: automatic (top-level cache_control, optional 1h TTL) or explicit breakpoints
164
164
  openrouter chat "answer from the doc" -m anthropic/claude-sonnet-4.5 -s "$(cat big-context.txt)" --cache --cache-ttl 1h
165
165
  openrouter chat "answer from the doc" -m anthropic/claude-sonnet-4.5 -s "$(cat big-context.txt)" --cache-system
166
+ # OpenAI explicit caching (GPT-5.6+): 30m or 12h TTL, marks the system prompt (else the prompt);
167
+ # works on chat and responses, 12h writes bill at a higher rate
168
+ openrouter chat "answer from the doc" -m openai/gpt-5.6 -s "$(cat big-context.txt)" --cache-ttl 12h
166
169
 
167
170
  # Tracing, sessions, priority: works on chat / messages / responses
168
171
  openrouter chat "..." -m openai/gpt-4o-mini --session-id run-42 --user u_123 \
@@ -203,7 +206,7 @@ openrouter embed -m openai/text-embedding-3-small "hello" "world"
203
206
  openrouter embed -m <multimodal-embed-model> "a cat" --image ./cat.png
204
207
  openrouter rerank -m cohere/rerank-v3.5 --query "italian food" -d pizza -d sushi -d pasta
205
208
 
206
- # Text to speech (mp3 by default; pcm also allowed): tone, multi-speaker, voice cloning
209
+ # Text to speech (mp3 by default, pcm for HeyGen Voice + Gemini TTS which only return pcm): tone, multi-speaker, voice cloning
207
210
  openrouter speech "Hello there" -m elevenlabs/eleven-v4 --voice <voice> -o out.mp3
208
211
  openrouter speech "Welcome back" -m openai/gpt-4o-mini-tts --voice alloy --instructions "warm, slow"
209
212
  openrouter speech -m google/gemini-2.5-flash-preview-tts --turns @dialogue.json # [{text, voice}]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aaronjmars/openroutercli",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Command-line interface for the OpenRouter API. Built for humans and LLM agents.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -42,7 +42,9 @@ export const SERVER_TOOL_HELP = ` --server-tool <name>[=<json|@file>] Open
42
42
  `;
43
43
 
44
44
  export const CACHE_HELP = ` --cache Automatic prompt caching (top-level cache_control)
45
- --cache-ttl <ttl> 5m | 1h (implies --cache)
45
+ --cache-ttl <ttl> 5m | 1h (implies --cache). chat/responses also take
46
+ 30m | 12h: OpenAI explicit prompt_cache_options
47
+ (GPT-5.6+; 12h writes bill higher)
46
48
  `;
47
49
 
48
50
  export const ALIGNMENT_HELP = ` --rule <text> Alignment plugin rule (repeatable, max 128, <=200 chars,
@@ -80,11 +82,25 @@ export async function applyToolExtras(body, values) {
80
82
  }
81
83
  }
82
84
 
83
- export function applyCache(body, values) {
84
- if (!values.cache && !values["cache-ttl"]) return;
85
+ const EXPLICIT_CACHE_TTLS = ["30m", "12h"];
86
+
87
+ // 5m | 1h: top-level cache_control (Anthropic style). 30m | 12h: OpenAI
88
+ // explicit prompt_cache_options, which only caches blocks marked with
89
+ // prompt_cache_breakpoint, so the caller must mark one. Returns true for the
90
+ // explicit form. `explicit` = the endpoint accepts it (chat, responses).
91
+ export function applyCache(body, values, { explicit = false } = {}) {
92
+ if (!values.cache && !values["cache-ttl"]) return false;
85
93
  const ttl = values["cache-ttl"];
86
- if (ttl && ttl !== "5m" && ttl !== "1h") throw new Error(`--cache-ttl must be 5m or 1h`);
94
+ if (EXPLICIT_CACHE_TTLS.includes(ttl)) {
95
+ if (!explicit) throw new Error("--cache-ttl 30m|12h works with chat and responses only");
96
+ body.prompt_cache_options = { mode: "explicit", ttl };
97
+ return true;
98
+ }
99
+ if (ttl && ttl !== "5m" && ttl !== "1h") {
100
+ throw new Error(`--cache-ttl must be ${explicit ? "5m, 1h, 30m or 12h" : "5m or 1h"}`);
101
+ }
87
102
  body.cache_control = { type: "ephemeral", ...(ttl ? { ttl } : {}) };
103
+ return false;
88
104
  }
89
105
 
90
106
  // Adds the alignment plugin from --rule/--alignment-*. An alignment entry
@@ -355,15 +371,18 @@ async function buildPlugins(values) {
355
371
  return addAlignmentPlugin(list, values);
356
372
  }
357
373
 
358
- // Wrap a string into a single text content part so a cache_control breakpoint
359
- // can be attached; content already in part form is returned untouched.
360
- function markCache(content) {
361
- if (typeof content === "string") {
362
- return [{ type: "text", text: content, cache_control: { type: "ephemeral" } }];
363
- }
374
+ // Wrap a string into a single text content part so a cache breakpoint can be
375
+ // attached; content already in part form gets it on its last part. Explicit
376
+ // mode uses prompt_cache_breakpoint, which only text parts accept.
377
+ function markCache(content, explicit) {
378
+ const mark = explicit
379
+ ? { prompt_cache_breakpoint: { mode: "explicit" } }
380
+ : { cache_control: { type: "ephemeral" } };
381
+ if (typeof content === "string") return [{ type: "text", text: content, ...mark }];
364
382
  if (Array.isArray(content) && content.length) {
365
383
  const parts = content.map((p) => ({ ...p }));
366
- parts[parts.length - 1].cache_control = { type: "ephemeral" };
384
+ const i = explicit ? parts.findLastIndex((p) => p.type === "text") : parts.length - 1;
385
+ if (i !== -1) Object.assign(parts[i], mark);
367
386
  return parts;
368
387
  }
369
388
  return content;
@@ -427,22 +446,23 @@ async function applyRequestOptions(body, values) {
427
446
  }
428
447
  if (values["prompt-cache-key"]) body.prompt_cache_key = values["prompt-cache-key"];
429
448
  if (values.metadata) body.metadata = await loadJsonOrFile(values.metadata, "--metadata");
430
- applyCache(body, values);
449
+ const explicit = applyCache(body, values, { explicit: true });
431
450
  await applyRequestFields(body, values);
432
451
 
433
452
  const plugins = await buildPlugins(values);
434
453
  if (plugins.length) body.plugins = plugins;
435
454
 
436
- // cache_control breakpoints are attached to message content, so this must
437
- // run after the messages are assembled.
438
- if (values["cache-system"]) {
439
- const sys = body.messages.find((m) => m.role === "system");
440
- if (sys) sys.content = markCache(sys.content);
441
- }
442
- if (values["cache-user"]) {
455
+ // Cache breakpoints are attached to message content, so this must run after
456
+ // the messages are assembled. Explicit mode caches nothing unmarked, so with
457
+ // no --cache-system/--cache-user it marks the system prompt, else the prompt.
458
+ const sys = body.messages.find((m) => m.role === "system");
459
+ const markSystem = values["cache-system"] || (explicit && !values["cache-user"] && sys);
460
+ const markUser = values["cache-user"] || (explicit && !values["cache-system"] && !sys);
461
+ if (markSystem && sys) sys.content = markCache(sys.content, explicit);
462
+ if (markUser) {
443
463
  for (let i = body.messages.length - 1; i >= 0; i--) {
444
464
  if (body.messages[i].role === "user") {
445
- body.messages[i].content = markCache(body.messages[i].content);
465
+ body.messages[i].content = markCache(body.messages[i].content, explicit);
446
466
  break;
447
467
  }
448
468
  }
@@ -64,7 +64,7 @@ create / update options:
64
64
 
65
65
  const ZDR_PROVIDERS = ["anthropic", "openai", "google", "xai", "other"];
66
66
  const REGIONS = ["global", "europe", "us"];
67
- const MAX_KEY_HASHES = 500;
67
+ const MAX_BULK_IDS = 500;
68
68
 
69
69
  function toggle(values, on, off) {
70
70
  if (values[on] && values[off]) throw new Error(`Pass only one of --${on} or --${off}.`);
@@ -339,9 +339,9 @@ export async function guardrailsCommand(argv) {
339
339
  if (positionals.length < 2) throw new Error("Usage: <id> <hash>...");
340
340
  const id = positionals[0];
341
341
  const hashes = positionals.slice(1);
342
- if (hashes.length > MAX_KEY_HASHES) {
342
+ if (hashes.length > MAX_BULK_IDS) {
343
343
  throw new Error(
344
- `Too many key hashes (${hashes.length}); the API takes at most ${MAX_KEY_HASHES} per call. Split into batches.`,
344
+ `Too many key hashes (${hashes.length}); the API takes at most ${MAX_BULK_IDS} per call. Split into batches.`,
345
345
  );
346
346
  }
347
347
  const path =
@@ -362,6 +362,11 @@ export async function guardrailsCommand(argv) {
362
362
  if (positionals.length < 2) throw new Error("Usage: <id> <user_id>...");
363
363
  const id = positionals[0];
364
364
  const userIds = positionals.slice(1);
365
+ if (userIds.length > MAX_BULK_IDS) {
366
+ throw new Error(
367
+ `Too many user ids (${userIds.length}); the API takes at most ${MAX_BULK_IDS} per call. Split into batches.`,
368
+ );
369
+ }
365
370
  const path =
366
371
  sub === "assign-member"
367
372
  ? `/guardrails/${encodeURIComponent(id)}/assignments/members`
@@ -374,7 +374,22 @@ export async function responsesCommand(argv) {
374
374
  if (values.background) body.background = true;
375
375
  if (values["prompt-cache-key"]) body.prompt_cache_key = values["prompt-cache-key"];
376
376
  if (values["safety-identifier"]) body.safety_identifier = values["safety-identifier"];
377
- applyCache(body, values);
377
+ // Explicit mode caches only marked blocks: mark the prompt, which caches
378
+ // the instructions before it too.
379
+ if (applyCache(body, values, { explicit: true }) && typeof body.input === "string") {
380
+ body.input = [
381
+ {
382
+ role: "user",
383
+ content: [
384
+ {
385
+ type: "input_text",
386
+ text: body.input,
387
+ prompt_cache_breakpoint: { mode: "explicit" },
388
+ },
389
+ ],
390
+ },
391
+ ];
392
+ }
378
393
  await applyRequestFields(body, values);
379
394
  if (values.extra) Object.assign(body, await loadJson(values.extra, "--extra"));
380
395
  }
@@ -26,7 +26,8 @@ Options:
26
26
  or one image (.png/.jpg/.webp) for voice design.
27
27
  Local files are sent as data URLs.
28
28
  --ref-text <t> Transcript of a --ref clip (repeatable, in --ref order)
29
- --format <fmt> mp3 | pcm (default: mp3; pcm is raw 16-bit audio)
29
+ --format <fmt> mp3 | pcm (default: mp3, or pcm for HeyGen Voice and
30
+ Gemini TTS, which only return pcm; pcm is raw 16-bit audio)
30
31
  --speed <n> Speech speed (e.g. 1.0)
31
32
  -o, --out <file> Output audio file (default: out.mp3 / out.pcm, or stdout if -)
32
33
  --provider <json|@file> Routing and provider options, e.g.
@@ -86,8 +87,10 @@ export async function speechCommand(argv) {
86
87
  input = text;
87
88
  }
88
89
 
89
- // The API defaults to raw PCM; ask for mp3 so the default out.mp3 plays.
90
- const format = values.format || "mp3";
90
+ // The API defaults to raw PCM; ask for mp3 so the default out.mp3 plays,
91
+ // except on HeyGen Voice and Gemini TTS, which return only pcm (400 on mp3).
92
+ const pcmOnly = /^heygen\//.test(values.model) || /^google\/.*-tts\b/.test(values.model);
93
+ const format = values.format || (pcmOnly ? "pcm" : "mp3");
91
94
  const body = { model: values.model, input, response_format: format };
92
95
  if (values.voice) body.voice = values.voice;
93
96
  if (values.instructions) body.instructions = values.instructions;