@aaronjmars/openroutercli 0.12.0 → 0.13.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
@@ -71,12 +71,12 @@ and run `openrouter login --management`.
71
71
  | Feature | What it does |
72
72
  |---|---|
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
- | **Two-slot key management** | User key + management/provisioning key live in separate slots. `keys`, `byok`, `guardrails`, `workspaces`, `observability`, `activity` and `presets create` auto-pick the management key; everything else uses the user key. `--key` always wins. |
74
+ | **Two-slot key management** | User key + management/provisioning key live in separate slots. `keys`, `byok`, `guardrails`, `workspaces`, `observability`, `activity` and `presets create/delete/restore` 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
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
- | **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. |
79
+ | **Batches** | `batches {create,list,get,wait,results,cancel,delete}` - send a JSONL file of chat / responses / messages / embeddings requests as one async job at about half price. |
80
80
  | **Embeddings + rerank + speech + video** | `embed` (text or images), `rerank`, `speech` (tone instructions, multi-speaker turns, voice references), `transcribe` (URL input, speaker labels, key terms, word timestamps), `video {create,wait,download}` (resolution, first/last frame, references, audio, extend) - async video jobs poll-until-done with `video wait <jobId>`. |
81
81
  | **Model discovery with detail** | `models list` (filter, sort by price/context, `--endpoints` by API path served), `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. |
@@ -138,6 +138,7 @@ openrouter image "put a hat here" -m openai/gpt-image-2.6-flare --image ./cat.pn
138
138
  # Batches at about half price
139
139
  openrouter batches create --endpoint chat -m openai/gpt-4o-mini --file reqs.jsonl --callback-url https://example.com/webhook
140
140
  openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
141
+ openrouter batches cancel <id> # stop a running batch (cancellation is enabled per org)
141
142
 
142
143
  # Discovery
143
144
  openrouter models --filter claude --sort prompt
@@ -210,7 +211,7 @@ Endpoint coverage map:
210
211
  | `POST /audio/speech` | `openrouter speech`, `openrouter tts` |
211
212
  | `POST /videos`, `GET /videos/{id}`, `GET /videos/{id}/content`, `GET /videos/models` | `openrouter video {create,get,wait,download,models}` |
212
213
  | `GET /generation`, `GET /generation/content`, `POST /generation/feedback` | `openrouter generation [--content]`, `openrouter generation feedback` |
213
- | `GET/POST/DELETE /batches[/{id}]` | `openrouter batches {list,create,get,wait,results,delete}` |
214
+ | `GET/POST/DELETE /batches[/{id}]`, `POST /batches/{id}/cancel` | `openrouter batches {list,create,get,wait,results,cancel,delete}` |
214
215
  | `GET /tools`, `GET /tools/{name}` | `openrouter tools {list,get}` |
215
216
  | `POST /audio/transcriptions` | `openrouter transcribe`, `openrouter stt` |
216
217
  | `POST /images`, `GET /images/models` | `openrouter image [models]` |
@@ -220,7 +221,7 @@ Endpoint coverage map:
220
221
  | `GET/POST/PATCH/DELETE /workspaces[/{id}]` + members + budgets | `openrouter workspaces ...` |
221
222
  | `GET/POST/PATCH/DELETE /observability/destinations[/{id}]` | `openrouter observability ...` |
222
223
  | `GET/POST/PATCH/DELETE /byok[/{id}]` | `openrouter byok ...` |
223
- | `GET /presets[/{slug}]` + versions, `POST /presets/{slug}/{chat/completions,messages,responses}` | `openrouter presets {list,get,versions,create}` |
224
+ | `GET/DELETE /presets[/{slug}]` + versions, `POST /presets/{slug}/{chat/completions,messages,responses,restore}` | `openrouter presets {list,get,versions,version,create,delete,restore}` |
224
225
  | `POST /systemone` (and `POST /api/alpha/decisions` with `--alpha`) | `openrouter systemone` / `openrouter decisions` |
225
226
  | `POST /api/alpha/extractions` | `openrouter extract` / `openrouter extractions` |
226
227
  | `GET /containers/{id}/files[/{file}]` + content/promote | `openrouter containers ...` |
package/SKILL.md CHANGED
@@ -83,7 +83,7 @@ command automatically.
83
83
  | Slot | Used by | How to obtain |
84
84
  | --- | --- | --- |
85
85
  | **User key** | `chat`, `messages`, `responses`, `embed`, `rerank`, `speech`, `transcribe`, `image`, `video`, `files`, `presets` (read), `generation`, `credits`, `whoami`, `benchmarks`, `classifications`, `datasets`, `decisions`, `extract`, `containers`, `batches`, `tools` | OAuth (`openrouter login`) or paste from dashboard |
86
- | **Management key** | `keys`, `byok`, `guardrails`, `workspaces`, `activity`, `analytics`, `observability`, `org members`, `org settings`, `auth-code`, `presets create` | Dashboard only - <https://openrouter.ai/settings/provisioning-keys>. Cannot be obtained via OAuth. Save with `openrouter login --management`. |
86
+ | **Management key** | `keys`, `byok`, `guardrails`, `workspaces`, `activity`, `analytics`, `observability`, `org members`, `org settings`, `auth-code`, `presets create/delete/restore` | Dashboard only - <https://openrouter.ai/settings/provisioning-keys>. Cannot be obtained via OAuth. Save with `openrouter login --management`. |
87
87
 
88
88
  You can store both - they live side by side in the config file. `--key sk-or-...`
89
89
  always wins over both. Inference commands prefer the user key; management
@@ -202,6 +202,7 @@ openrouter responses "..." -m openai/gpt-5-mini --verbosity low --truncation aut
202
202
  # Batches: async jobs at ~half price (chat, responses, messages, embeddings)
203
203
  openrouter batches create --endpoint chat -m openai/gpt-4o-mini --file reqs.jsonl --callback-url https://example.com/webhook # {custom_id, body} per line
204
204
  openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
205
+ openrouter batches cancel <id> # stop a running batch; 403 = cancel not enabled for the org, 409 = already ended
205
206
 
206
207
  # Embeddings (text or images), rerank
207
208
  openrouter embed -m openai/text-embedding-3-small "hello" "world"
@@ -266,6 +267,7 @@ openrouter decisions --model typesafe/jev-1.13 --state '...' --questions @questi
266
267
  openrouter decisions --model <vision-decider> --state '...' --image ./chart.png --questions @q.json
267
268
  openrouter decisions --model typesafe/jev-1.14 --state '... image: logo' --assets '{"logo":"./logo.png"}' --questions @q.json
268
269
  openrouter extract -m scaledown/extract --state '...' --fields '{"invoice":{"type":"text"}}' # alpha; alias: extractions
270
+ # models: cloudflare/clairic (all field types, up to 4 images, no PDF), scaledown/extract and inception/mercury-decide (text + list only)
269
271
  openrouter extract -m scaledown/extract --assets '{"doc":"./invoice.pdf"}' --fields @fields.json # file-only (state = asset key)
270
272
  openrouter containers list <container-id>
271
273
 
@@ -327,6 +329,7 @@ openrouter guardrails update <id> --regions europe --builtin-filters email:redac
327
329
  openrouter guardrails update <id> --allow-safety-retention-google --no-allow-safety-retention-other
328
330
  openrouter guardrails update <id> --harness-models # codex/claude harnesses only see their vendor's models
329
331
  openrouter guardrails assign-key <id> <key-hash> # up to 500 hashes per call
332
+ openrouter guardrails assignments --members --workspace <uuid> # org keys list every workspace otherwise
330
333
 
331
334
  # Typed policies (budget | model-availability | moderation); --workspace is required,
332
335
  # --account works on workspace-wide policies instead
@@ -376,7 +379,7 @@ openrouter byok delete <id>
376
379
 
377
380
  The `--api-key` flag is the upstream provider secret (never echoed back).
378
381
 
379
- ### Files, presets (user key; presets create needs a management key)
382
+ ### Files, presets (user key; presets create/delete/restore need a management key)
380
383
 
381
384
  ```bash
382
385
  # Files - backing store for file/PDF inputs
@@ -386,11 +389,13 @@ openrouter files download <file_id> -o report.pdf
386
389
  openrouter files delete <file_id>
387
390
 
388
391
  # Presets - saved config profiles. Invoke via @preset/<slug> as a model.
389
- openrouter presets list [--offset N] [--limit N]
392
+ openrouter presets list [--offset N] [--limit N] [--workspace <uuid>] # --workspace works on every presets subcommand
390
393
  openrouter presets get <slug>
391
394
  openrouter presets versions <slug> [--offset N] [--limit N]
392
395
  openrouter presets create <slug> --api chat --body @preset.json # existing slug = new version
393
396
  openrouter presets create <slug> --body @preset.json --workspace <uuid> # into another workspace
397
+ openrouter presets delete <slug> # archive: stops resolving, hidden from list; slug stays taken
398
+ openrouter presets restore <slug> # re-activate an archived preset (same designated version)
394
399
  ```
395
400
 
396
401
  ### Raw escape hatch
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aaronjmars/openroutercli",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "description": "Command-line interface for the OpenRouter API. Built for humans and LLM agents.",
5
5
  "type": "module",
6
6
  "bin": {
package/src/cli.js CHANGED
@@ -112,7 +112,7 @@ Inference:
112
112
  video <sub> Video generation jobs (create / get / wait / download / models)
113
113
  image <sub> Image generation (create / models / endpoints). Alias: images
114
114
  batches <sub> Async batch jobs at ~half price (list / create / get / wait /
115
- results / delete). Alias: batch
115
+ results / cancel / delete). Alias: batch
116
116
 
117
117
  Discovery:
118
118
  models [list|show|endpoints|parameters|count|user] List models, full model
@@ -122,7 +122,8 @@ Discovery:
122
122
  video models List video generation models
123
123
  image models List image generation models
124
124
  providers List providers (with HQ + datacenters)
125
- presets <sub> list / get / versions / create (saved config profiles)
125
+ presets <sub> list / get / versions / create / delete /
126
+ restore (saved config profiles)
126
127
  generation <id> [--content] Generation metadata or content
127
128
  generation feedback <id> --category <c> Report a problem with a generation
128
129
  tools [list|get] Server tools (web_search, web_fetch, datetime...) + engines
@@ -13,6 +13,7 @@ Subcommands:
13
13
  get <id> Status, request counts and usage
14
14
  wait <id> [options] Poll until the batch reaches a final status
15
15
  results <id> [-o out.jsonl] Write the per-request results as JSONL
16
+ cancel <id> Ask the provider to stop a running batch
16
17
  delete <id> Delete a finished batch and its stored data
17
18
 
18
19
  list options:
@@ -44,7 +45,14 @@ results options:
44
45
 
45
46
  Statuses: validating, in_progress, finalizing, completed, failed, expired,
46
47
  cancelling, cancelled. Final ones: completed, failed, expired, cancelled.
47
- There is no cancel endpoint. Results are kept for 30 days.
48
+ Results are kept for 30 days.
49
+
50
+ cancel: cancellation is enabled per organization (others get 403). The batch
51
+ stays in_progress until the provider confirms, then turns cancelled (or
52
+ completed if it finished first); run \`batches wait <id>\` after. Repeating the
53
+ call is safe. On OpenAI, requests done before the cancel are kept in results
54
+ and billed at the batch price; on most other providers a cancelled batch has
55
+ no results.
48
56
 
49
57
  Examples:
50
58
  openrouter batches create -m openai/gpt-5-nano --file reqs.jsonl
@@ -331,6 +339,37 @@ export async function batchesCommand(argv) {
331
339
  return 0;
332
340
  }
333
341
 
342
+ if (sub === "cancel") {
343
+ const { values, positionals } = parseArgs(rest, {});
344
+ if (!positionals[0]) throw new Error("id required");
345
+ const id = positionals[0];
346
+ let data;
347
+ try {
348
+ data = await api("POST", `/batches/${encodeURIComponent(id)}/cancel`, {
349
+ auth: authFromValues(values),
350
+ });
351
+ } catch (err) {
352
+ if (err instanceof APIError && err.status === 403) {
353
+ throw new APIError(
354
+ `${err.message}\nBatch cancellation is enabled per organization; ask OpenRouter to turn it on.`,
355
+ err,
356
+ );
357
+ }
358
+ if (err instanceof APIError && err.status === 409) {
359
+ throw new APIError(
360
+ `${err.message}\nThe batch already ended, has not reached the provider yet, or runs on a provider without a cancel call. Check it: openrouter batches get ${id}`,
361
+ err,
362
+ );
363
+ }
364
+ throw err;
365
+ }
366
+ printBatch(data);
367
+ if (!TERMINAL_STATUSES.includes(data.status)) {
368
+ info(`Cancel requested. Next: openrouter batches wait ${id}`);
369
+ }
370
+ return 0;
371
+ }
372
+
334
373
  if (sub === "delete") {
335
374
  const { values, positionals } = parseArgs(rest, {});
336
375
  if (!positionals[0]) throw new Error("id required");
@@ -12,8 +12,13 @@ by an extraction-style System One model such as scaledown/extract. The
12
12
  request shape is alpha and may change.
13
13
 
14
14
  Field types: text, number, date, time, datetime, duration, list, estimate,
15
- forecast. Which types a model answers is model-specific (400 otherwise):
16
- scaledown/extract returns text spans only and takes no --reference-date.
15
+ forecast. Which types a model answers is model-specific (400 otherwise).
16
+ Launch models:
17
+ cloudflare/clairic all field types; text plus up to 4 png/jpeg images
18
+ (no PDFs); the only one returning p_null
19
+ scaledown/extract text and list fields; text, or one PDF or image
20
+ inception/mercury-decide text and list fields; text only
21
+ scaledown/extract and inception/mercury-decide take no --reference-date.
17
22
  With one asset and no --state, the request is file-only (state = its key).
18
23
 
19
24
  Options:
@@ -22,7 +22,10 @@ Subcommands:
22
22
  create <name> [options] Create
23
23
  update <id> [options] Update
24
24
  delete <id> Delete
25
- assignments [--keys|--members] List all assignments (--offset/--limit)
25
+ assignments [--keys|--members] [--workspace <uuid>]
26
+ List all assignments (--offset/--limit).
27
+ An org key lists every workspace unless
28
+ --workspace is given
26
29
  assign-key <id> <hash>... Assign API keys to a guardrail
27
30
  unassign-key <id> <hash>... Unassign API keys
28
31
  assign-member <id> <user>... Assign org members
@@ -315,6 +318,7 @@ export async function guardrailsCommand(argv) {
315
318
  ...PAGINATION_OPTIONS,
316
319
  keys: { type: "boolean" },
317
320
  members: { type: "boolean" },
321
+ workspace: { type: "string" },
318
322
  });
319
323
  if (values.keys && values.members) {
320
324
  throw new Error("Pass only one of --keys or --members.");
@@ -322,10 +326,12 @@ export async function guardrailsCommand(argv) {
322
326
  const path = values.members
323
327
  ? "/guardrails/assignments/members"
324
328
  : "/guardrails/assignments/keys";
329
+ const query = paginationQuery(values);
330
+ if (values.workspace) query.workspace_id = values.workspace;
325
331
  const data = await api("GET", path, {
326
332
  auth: authFromValues(values),
327
333
  requiresManagement: true,
328
- query: paginationQuery(values),
334
+ query,
329
335
  });
330
336
  printResult(data);
331
337
  return 0;
@@ -10,7 +10,7 @@ import { outln, printResult, table } from "../output.js";
10
10
 
11
11
  const HELP = `Usage: openrouter presets <subcommand> [options]
12
12
 
13
- View and create server-saved config presets.
13
+ View, create, archive and restore server-saved config presets.
14
14
 
15
15
  Subcommands:
16
16
  list [--offset N] [--limit N] List presets (default)
@@ -21,19 +21,28 @@ Subcommands:
21
21
  create <slug> --body <json|@file> [--api chat|messages|responses]
22
22
  Create a preset from an inference request body.
23
23
  An existing slug gets a new version.
24
- Needs a read-write management key (inference
25
- keys are rejected).
24
+ delete <slug> Archive a preset: it stops resolving for
25
+ inference and is hidden from get and list.
26
+ Versions are kept and the slug stays taken.
27
+ restore <slug> Re-activate an archived preset (no new version;
28
+ the designated version is unchanged)
29
+
30
+ create, delete and restore need a read-write management key (inference keys
31
+ are rejected). A disabled preset returns 409 on delete and restore.
32
+
33
+ Options (every subcommand):
34
+ --workspace <uuid> Workspace to act in (default: the key's workspace
35
+ for a key limited to one, else the account default)
26
36
 
27
37
  create options:
28
38
  --body <json|@file> A normal request body for that API. Only preset fields
29
39
  (model, provider, sampling params, ...) are kept;
30
40
  messages, input and stream are ignored.
31
41
  --api <a> chat (default) | messages | responses
32
- --workspace <uuid> Workspace to create it in (default: the key's workspace
33
- for a key limited to one, else the account default)
34
42
 
35
- Example:
43
+ Examples:
36
44
  openrouter presets create fast-cheap --body '{"model":"openai/gpt-5-nano","temperature":0.2,"provider":{"sort":"price"}}'
45
+ openrouter presets delete fast-cheap && openrouter presets restore fast-cheap
37
46
  `;
38
47
 
39
48
  const PRESET_APIS = {
@@ -56,6 +65,13 @@ export function buildPresetBody(apiName, body) {
56
65
  return out;
57
66
  }
58
67
 
68
+ const WORKSPACE_OPTION = { workspace: { type: "string" } };
69
+
70
+ function workspaceQuery(values, query = {}) {
71
+ if (values.workspace) query.workspace_id = values.workspace;
72
+ return Object.keys(query).length ? query : undefined;
73
+ }
74
+
59
75
  export async function presetsCommand(argv) {
60
76
  const sub = argv[0] && !argv[0].startsWith("-") ? argv[0] : "list";
61
77
  const rest = sub === argv[0] ? argv.slice(1) : argv;
@@ -71,20 +87,41 @@ export async function presetsCommand(argv) {
71
87
  }
72
88
 
73
89
  if (sub === "get") {
74
- const { values, positionals } = parseArgs(rest, {});
90
+ const { values, positionals } = parseArgs(rest, WORKSPACE_OPTION);
75
91
  if (!positionals[0]) throw new Error("slug required");
76
92
  const data = await api("GET", `/presets/${encodeURIComponent(positionals[0])}`, {
77
93
  auth: authFromValues(values),
94
+ query: workspaceQuery(values),
78
95
  });
79
96
  printResult(data);
80
97
  return 0;
81
98
  }
82
99
 
100
+ if (sub === "delete" || sub === "restore") {
101
+ const { values, positionals } = parseArgs(rest, WORKSPACE_OPTION);
102
+ const slug = positionals[0];
103
+ if (!slug) throw new Error("slug required");
104
+ const path =
105
+ sub === "delete"
106
+ ? `/presets/${encodeURIComponent(slug)}`
107
+ : `/presets/${encodeURIComponent(slug)}/restore`;
108
+ const data = await api(sub === "delete" ? "DELETE" : "POST", path, {
109
+ auth: authFromValues(values),
110
+ requiresManagement: true,
111
+ query: workspaceQuery(values),
112
+ });
113
+ printResult(data, () => {
114
+ const p = data && (data.data || data);
115
+ outln(`${sub === "delete" ? "archived" : "restored"} preset ${(p && p.slug) || slug}`);
116
+ });
117
+ return 0;
118
+ }
119
+
83
120
  if (sub === "create") {
84
121
  const { values, positionals } = parseArgs(rest, {
85
122
  body: { type: "string" },
86
123
  api: { type: "string" },
87
- workspace: { type: "string" },
124
+ ...WORKSPACE_OPTION,
88
125
  });
89
126
  const slug = positionals[0];
90
127
  if (!slug) throw new Error("slug required");
@@ -97,7 +134,7 @@ export async function presetsCommand(argv) {
97
134
  auth: authFromValues(values),
98
135
  requiresManagement: true,
99
136
  body,
100
- query: values.workspace ? { workspace_id: values.workspace } : undefined,
137
+ query: workspaceQuery(values),
101
138
  });
102
139
  printResult(data, () => {
103
140
  const p = data && (data.data || data);
@@ -111,12 +148,11 @@ export async function presetsCommand(argv) {
111
148
  }
112
149
 
113
150
  if (sub === "versions") {
114
- const { values, positionals } = parseArgs(rest, PAGINATION_OPTIONS);
151
+ const { values, positionals } = parseArgs(rest, { ...PAGINATION_OPTIONS, ...WORKSPACE_OPTION });
115
152
  if (!positionals[0]) throw new Error("slug required");
116
- const query = paginationQuery(values);
117
153
  const data = await api("GET", `/presets/${encodeURIComponent(positionals[0])}/versions`, {
118
154
  auth: authFromValues(values),
119
- query: Object.keys(query).length ? query : undefined,
155
+ query: workspaceQuery(values, paginationQuery(values)),
120
156
  });
121
157
  printResult(data, () => {
122
158
  const rows = data.data || [];
@@ -129,24 +165,23 @@ export async function presetsCommand(argv) {
129
165
  }
130
166
 
131
167
  if (sub === "version") {
132
- const { values, positionals } = parseArgs(rest, {});
168
+ const { values, positionals } = parseArgs(rest, WORKSPACE_OPTION);
133
169
  if (!positionals[0]) throw new Error("slug required");
134
170
  if (!positionals[1]) throw new Error("version required");
135
171
  const data = await api(
136
172
  "GET",
137
173
  `/presets/${encodeURIComponent(positionals[0])}/versions/${encodeURIComponent(positionals[1])}`,
138
- { auth: authFromValues(values) },
174
+ { auth: authFromValues(values), query: workspaceQuery(values) },
139
175
  );
140
176
  printResult(data);
141
177
  return 0;
142
178
  }
143
179
 
144
180
  if (sub === "list") {
145
- const { values } = parseArgs(rest, PAGINATION_OPTIONS);
146
- const query = paginationQuery(values);
181
+ const { values } = parseArgs(rest, { ...PAGINATION_OPTIONS, ...WORKSPACE_OPTION });
147
182
  const data = await api("GET", "/presets", {
148
183
  auth: authFromValues(values),
149
- query: Object.keys(query).length ? query : undefined,
184
+ query: workspaceQuery(values, paginationQuery(values)),
150
185
  });
151
186
  printResult(data, () => {
152
187
  const rows = data.data || [];