@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 +1 -1
- package/SKILL.md +4 -1
- package/package.json +1 -1
- package/src/commands/chat.js +40 -20
- package/src/commands/guardrails.js +8 -3
- package/src/commands/messages.js +16 -1
- package/src/commands/speech.js +6 -3
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
|
|
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
package/src/commands/chat.js
CHANGED
|
@@ -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
|
-
|
|
84
|
-
|
|
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
|
|
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
|
|
359
|
-
//
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
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
|
|
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
|
-
//
|
|
437
|
-
//
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
if (
|
|
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
|
|
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 >
|
|
342
|
+
if (hashes.length > MAX_BULK_IDS) {
|
|
343
343
|
throw new Error(
|
|
344
|
-
`Too many key hashes (${hashes.length}); the API takes at most ${
|
|
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`
|
package/src/commands/messages.js
CHANGED
|
@@ -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
|
-
|
|
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
|
}
|
package/src/commands/speech.js
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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;
|