@aaronjmars/openroutercli 0.3.0 → 0.5.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,19 +71,21 @@ 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`, `guardrails`, `workspaces`, `activity` 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` 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`), structured output (`--schema schema.json`), JSON mode, multimodal images (`--image url\|path`), reasoning effort, provider routing, fallback models, seed, stop sequences, 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`), 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
- | **Embeddings + rerank + TTS + video** | `embed`, `rerank`, `speech`, `video {create,wait,download}` - async video jobs poll-until-done with `video wait <jobId>`. |
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. |
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>`. |
80
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. |
81
82
  | **Benchmarks + rankings** | `benchmarks`, `classifications`, and `datasets {apps,daily,session-cost}` expose OpenRouter's current public benchmark and usage datasets. |
82
83
  | **Management analytics** | `analytics meta` discovers fields; `analytics query` runs metrics/dimensions/time-range queries with a management key. |
83
- | **Structured decisions** | `decisions` calls the alpha Decisions API for typed choice, score, and yes/no outputs. |
84
+ | **Structured decisions** | `decisions` (alias `systemone`) calls System One for typed choice, score, and yes/no outputs, with optional image inputs. |
85
+ | **Server tools catalog** | `tools list` / `tools get <name>` - every OpenRouter-run tool (web search, fetch, datetime, ...) with params, engines and pricing. |
84
86
  | **Hosted shell files** | `containers {list,get,download,promote}` retrieves and promotes files produced by OpenRouter's hosted shell tools. |
85
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. |
86
- | **Account + governance** | `keys`, `guardrails` (allow/deny lists, USD limits, ZDR), `workspaces` (defaults + members), `org members`, `auth-code` to mint claim links. All require a management key. |
88
+ | **Account + governance** | `keys`, `guardrails` (allow/deny lists, USD limits, ZDR, data regions, content filters), `workspaces` (defaults, members, budgets, disabled tools), `observability` destinations (Langfuse, Datadog, ...), `org members` / `org settings`, `auth-code` to mint claim links. All require a management key. |
87
89
  | **Raw escape hatch** | `openrouter request <METHOD> <path> --body @file.json --query k=v --header k:v` - talk to any current or future endpoint without waiting for a CLI release. |
88
90
  | **Agent-friendly errors** | Stable exit codes (1 usage, 2 API, 3 no key, 4 job failed). API error messages surfaced verbatim. `OPENROUTER_DEBUG=1` for stack traces. |
89
91
  | **Zero npm dependencies** | Pure Node 20+ - built-in `fetch`, `parseArgs`, `crypto`. Cold install in seconds. Easy to audit. |
@@ -125,12 +127,20 @@ openrouter chat "List 3 fruits" -m openai/gpt-4o-mini \
125
127
  openrouter chat "What is 2+2?" -m openai/gpt-4o-mini \
126
128
  --tool @calc.json --tool-choice required --raw
127
129
 
130
+ # Server tools (run by OpenRouter)
131
+ openrouter tools list
132
+ openrouter chat "What's new today?" -m openai/gpt-4o-mini --server-tool web_search
133
+
134
+ # Batches at about half price
135
+ openrouter batches create --endpoint chat -m openai/gpt-4o-mini --file reqs.jsonl --callback-url https://example.com/webhook
136
+ openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
137
+
128
138
  # Discovery
129
139
  openrouter models --filter claude --sort prompt
140
+ openrouter models user --order newest
130
141
  openrouter models show anthropic/claude-sonnet-4.5
131
142
  openrouter models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best
132
143
  openrouter providers
133
-
134
144
  # Spend / runs
135
145
  openrouter credits
136
146
  openrouter whoami
@@ -141,6 +151,8 @@ openrouter activity --date 2026-04-28 --api-key-hash <hash>
141
151
  openrouter keys create "agent-key" --limit 25 --limit-reset monthly
142
152
  openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-zdr
143
153
  openrouter workspaces create "staging" --slug staging --default-text-model openai/gpt-4o-mini
154
+ openrouter workspaces budgets set staging monthly --limit 100
155
+ openrouter observability create "langfuse" --type langfuse --config @langfuse.json
144
156
 
145
157
  # Raw escape hatch - call any endpoint
146
158
  openrouter request POST /chat/completions --body @body.json
@@ -172,6 +184,7 @@ Endpoint coverage map:
172
184
  | `GET /classifications/task` | `openrouter classifications` |
173
185
  | `GET /datasets/app-rankings` / `GET /datasets/rankings-daily` / `GET /datasets/session-cost` | `openrouter datasets {apps,daily,session-cost}` |
174
186
  | `GET /models` | `openrouter models list` |
187
+ | `GET /model/{author}/{slug}` | `openrouter models show` |
175
188
  | `GET /models/count` | `openrouter models count` |
176
189
  | `GET /models/user` | `openrouter models user` |
177
190
  | `GET /models/{author}/{slug}/endpoints` | `openrouter models endpoints` |
@@ -184,13 +197,21 @@ Endpoint coverage map:
184
197
  | `POST /rerank` | `openrouter rerank` |
185
198
  | `POST /audio/speech` | `openrouter speech`, `openrouter tts` |
186
199
  | `POST /videos`, `GET /videos/{id}`, `GET /videos/{id}/content`, `GET /videos/models` | `openrouter video {create,get,wait,download,models}` |
187
- | `GET /generation`, `GET /generation/content` | `openrouter generation [--content]` |
200
+ | `GET /generation`, `GET /generation/content`, `POST /generation/feedback` | `openrouter generation [--content]`, `openrouter generation feedback` |
201
+ | `GET/POST/DELETE /batches[/{id}]` | `openrouter batches {list,create,get,wait,results,delete}` |
202
+ | `GET /tools`, `GET /tools/{name}` | `openrouter tools {list,get}` |
203
+ | `POST /audio/transcriptions` | `openrouter transcribe`, `openrouter stt` |
204
+ | `POST /images`, `GET /images/models` | `openrouter image [models]` |
188
205
  | `GET/POST/PATCH/DELETE /keys[/{hash}]` | `openrouter keys {list,get,create,update,delete}` |
189
206
  | `GET/POST/PATCH/DELETE /guardrails[/{id}]` + assignments | `openrouter guardrails ...` |
190
- | `GET/POST/PATCH/DELETE /workspaces[/{id}]` + members | `openrouter workspaces ...` |
191
- | `POST /api/alpha/decisions` | `openrouter decisions` |
207
+ | `GET/POST/PATCH/DELETE /workspaces[/{id}]` + members + budgets | `openrouter workspaces ...` |
208
+ | `GET/POST/PATCH/DELETE /observability/destinations[/{id}]` | `openrouter observability ...` |
209
+ | `GET/POST/PATCH/DELETE /byok[/{id}]` | `openrouter byok ...` |
210
+ | `GET /presets[/{slug}]` + versions, `POST /presets/{slug}/{chat/completions,messages,responses}` | `openrouter presets {list,get,versions,create}` |
211
+ | `POST /systemone` (and `POST /api/alpha/decisions` with `--alpha`) | `openrouter systemone` / `openrouter decisions` |
192
212
  | `GET /containers/{id}/files[/{file}]` + content/promote | `openrouter containers ...` |
193
213
  | `GET /organization/members` | `openrouter org members` |
214
+ | `GET/PATCH /organization/settings` | `openrouter org settings` |
194
215
  | anything else | `openrouter request <METHOD> <path>` |
195
216
 
196
217
  ## Configuration
package/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: openrouter-cli
3
- description: Use the `openrouter` CLI to call any OpenRouter API endpoint from the shell - chat / messages / responses (with web search, PDF input, prompt caching, reasoning budgets, tools), embeddings, rerank, text-to-speech, speech-to-text, image + video generation, model + provider discovery, generation lookup, credits, activity, and full key / BYOK / guardrail / workspace / files / presets management. Pass `--json` on every command for machine-parseable output.
3
+ description: Use the `openrouter` CLI to call any OpenRouter API endpoint from the shell - chat / messages / responses (with server tools, web search, PDF input, prompt caching, reasoning budgets, tools, alignment rules), batches, embeddings, rerank, text-to-speech, speech-to-text, image + video generation, model + provider discovery, generation lookup, credits, activity, and full key / BYOK / guardrail / workspace (budgets) / observability / files / presets management. Pass `--json` on every command for machine-parseable output.
4
4
  ---
5
5
 
6
6
  # openrouter-cli skill
@@ -25,6 +25,9 @@ TRIGGER when the user asks to:
25
25
  - manage BYOK provider integrations, guardrails, workspaces, files, presets, or
26
26
  organization members
27
27
  - inspect benchmarks, task classifications, and public usage datasets
28
+ - run large jobs as async batches at about half price
29
+ - browse server tools (web search, fetch, datetime, ...) and use them in chat
30
+ - set workspace budgets or send traces to an observability destination
28
31
  - query management analytics
29
32
  - submit structured Decisions requests or retrieve hosted-container files
30
33
  - log in to OpenRouter from a fresh machine (OAuth PKCE in the browser)
@@ -79,8 +82,8 @@ command automatically.
79
82
 
80
83
  | Slot | Used by | How to obtain |
81
84
  | --- | --- | --- |
82
- | **User key** | `chat`, `messages`, `responses`, `embed`, `rerank`, `speech`, `transcribe`, `image`, `video`, `files`, `presets`, `generation`, `credits`, `whoami`, `benchmarks`, `classifications`, `datasets`, `decisions`, `containers` | OAuth (`openrouter login`) or paste from dashboard |
83
- | **Management key** | `keys`, `byok`, `guardrails`, `workspaces`, `activity`, `analytics`, `org members`, `auth-code` | Dashboard only - <https://openrouter.ai/settings/provisioning-keys>. Cannot be obtained via OAuth. Save with `openrouter login --management`. |
85
+ | **User key** | `chat`, `messages`, `responses`, `embed`, `rerank`, `speech`, `transcribe`, `image`, `video`, `files`, `presets`, `generation`, `credits`, `whoami`, `benchmarks`, `classifications`, `datasets`, `decisions`, `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` | Dashboard only - <https://openrouter.ai/settings/provisioning-keys>. Cannot be obtained via OAuth. Save with `openrouter login --management`. |
84
87
 
85
88
  You can store both - they live side by side in the config file. `--key sk-or-...`
86
89
  always wins over both. Inference commands prefer the user key; management
@@ -141,15 +144,34 @@ openrouter chat "tricky question" -m anthropic/claude-sonnet-4.5 --reasoning hig
141
144
  openrouter chat "prove it" -m openai/gpt-5-mini --reasoning-max-tokens 2000
142
145
  openrouter chat "quick" -m openai/gpt-5-mini --reasoning-exclude
143
146
 
144
- # Web search plugin (also works via the :online model suffix)
145
- openrouter chat "what shipped in the news today?" -m openai/gpt-4o-mini --web --web-max-results 3
147
+ # Server tools (run by OpenRouter): web search, fetch, datetime, ... (`openrouter tools list`)
148
+ openrouter chat "what shipped in the news today?" -m openai/gpt-4o-mini --server-tool web_search
149
+ openrouter chat "what day is it?" -m openai/gpt-4o-mini --server-tool 'datetime={"timezone":"UTC"}'
150
+ # Load big tool sets lazily: mark tools deferred, let the router search them
151
+ openrouter chat "..." -m openai/gpt-4o-mini --tool @tools.json --defer-loading \
152
+ --deferred-tools '{"protocol":"v1","search":{"type":"bm25","max_results":5}}'
153
+
154
+ # Legacy web plugin (deprecated upstream, still works); engine + domain filters
155
+ openrouter chat "latest on X" -m openai/gpt-4o-mini --web --web-engine exa --web-domains reuters.com,apnews.com
156
+
157
+ # Alignment plugin: enforce (block) or audit rules on the reply
158
+ openrouter chat "..." -m openai/gpt-4o-mini --rule "Never offer a discount." --alignment-mode enforce
146
159
 
147
160
  # Attach a PDF / file and parse it
148
161
  openrouter chat "summarize this" -m google/gemini-2.5-flash --file ./report.pdf --pdf-engine mistral-ocr
149
162
 
150
- # Prompt caching: mark the system (or user) prompt as a cache breakpoint
163
+ # Prompt caching: automatic (top-level cache_control, optional 1h TTL) or explicit breakpoints
164
+ openrouter chat "answer from the doc" -m anthropic/claude-sonnet-4.5 -s "$(cat big-context.txt)" --cache --cache-ttl 1h
151
165
  openrouter chat "answer from the doc" -m anthropic/claude-sonnet-4.5 -s "$(cat big-context.txt)" --cache-system
152
166
 
167
+ # Tracing, sessions, priority: works on chat / messages / responses
168
+ openrouter chat "..." -m openai/gpt-4o-mini --session-id run-42 --user u_123 \
169
+ --trace '{"trace_id":"t1","span_name":"plan"}' --service-tier priority
170
+
171
+ # Image output from a chat model; predicted output for faster edits
172
+ openrouter chat "draw a fox" -m google/gemini-2.5-flash-image --modalities text,image --json
173
+ openrouter chat "fix the typo" -m openai/gpt-4o-mini --prediction @draft.md
174
+
153
175
  # Sampling / output controls
154
176
  openrouter chat "..." -m openai/gpt-4o-mini --top-a 0.2 --logprobs --top-logprobs 5
155
177
 
@@ -167,20 +189,40 @@ openrouter chat -i -m openrouter/auto
167
189
 
168
190
  # Anthropic-format and OpenAI Responses API are also available
169
191
  openrouter messages "..." -m anthropic/claude-sonnet-4.5 --thinking-budget 2000
170
- openrouter responses "..." -m openai/gpt-4o-mini --store --include reasoning.encrypted_content
192
+ openrouter messages "..." -m anthropic/claude-sonnet-4.5 --thinking adaptive --effort high --speed fast
193
+ openrouter messages "..." -m anthropic/claude-sonnet-4.5 --provider '{"order":["Anthropic"]}' --plugins @plugins.json
194
+ openrouter responses "..." -m openai/gpt-4o-mini --stop "END,STOP" --store --include reasoning.encrypted_content
195
+ openrouter responses "..." -m openai/gpt-5-mini --verbosity low --truncation auto
196
+
197
+ # Batches: async jobs at ~half price (chat, responses, messages, embeddings)
198
+ openrouter batches create --endpoint chat -m openai/gpt-4o-mini --file reqs.jsonl --callback-url https://example.com/webhook # {custom_id, body} per line
199
+ openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
171
200
 
172
- # Embeddings, rerank
201
+ # Embeddings (text or images), rerank
173
202
  openrouter embed -m openai/text-embedding-3-small "hello" "world"
203
+ openrouter embed -m <multimodal-embed-model> "a cat" --image ./cat.png
174
204
  openrouter rerank -m cohere/rerank-v3.5 --query "italian food" -d pizza -d sushi -d pasta
175
205
 
176
- # Text to speech (audio out) and speech to text (audio in)
177
- openrouter speech "Hello there" -m elevenlabs/eleven-turbo-v2 --voice alloy -o out.mp3
206
+ # Text to speech (mp3 by default; pcm also allowed): tone, multi-speaker, voice cloning
207
+ openrouter speech "Hello there" -m elevenlabs/eleven-v4 --voice <voice> -o out.mp3
208
+ openrouter speech "Welcome back" -m openai/gpt-4o-mini-tts --voice alloy --instructions "warm, slow"
209
+ openrouter speech -m google/gemini-2.5-flash-preview-tts --turns @dialogue.json # [{text, voice}]
210
+ openrouter speech "Hi" -m <cloning-model> --ref ./sample.wav --ref-text "words in the sample"
211
+
212
+ # Speech to text: file or URL, speaker labels, key terms, word timestamps
178
213
  openrouter transcribe ./clip.wav -m openai/gpt-4o-transcribe # alias: stt
214
+ openrouter transcribe --url https://example.com/call.mp3 -m elevenlabs/scribe-v2 --diarize
215
+ openrouter transcribe ./talk.mp3 -m elevenlabs/scribe-v2 --keyterms OpenRouter,BYOK --timestamps word
179
216
 
180
- # Image generation (writes image-0.png, ...); and video jobs
217
+ # Image generation (writes image-0.png, ...): tier or exact size, reference images
181
218
  openrouter image "a red bike on a beach" -m google/gemini-2.5-flash-image -o bike.png
182
- openrouter video create "a sunset over mountains" -m google/veo-3
219
+ openrouter image "same bike, at night" -m google/gemini-2.5-flash-image --image ./bike.png --resolution 2K
220
+
221
+ # Video jobs: frames, references, audio, extend
222
+ openrouter video create "a sunset over mountains" -m google/veo-3 --resolution 1080p --audio
223
+ openrouter video create "she turns and smiles" -m <video-model> --first-frame ./start.png --ref ./style.png
183
224
  openrouter video wait <jobId> && openrouter video download <jobId> -o out.mp4
225
+ openrouter video create "keep going" -m <video-model> --extend <jobId>
184
226
  ```
185
227
 
186
228
  ### Discovery & pricing
@@ -193,13 +235,13 @@ openrouter models --order intelligence-high-to-low # server-side ranking
193
235
  openrouter models --free # only :free models
194
236
  openrouter models --input-modalities image # image-INPUT (vision) models
195
237
  openrouter models --output-modalities image # image-OUTPUT models
238
+ openrouter models user --order newest # account-filtered models, server-side sort
196
239
  openrouter models --supported tools # filter by capability
197
-
198
240
  # Full detail for one model: pricing breakdown, architecture, supported params,
199
241
  # reasoning config, supported voices
200
242
  openrouter models show anthropic/claude-sonnet-4.5
201
243
 
202
- # Supported params + popularity analytics (p10/p50/p90 per parameter)
244
+ # Supported request parameters (undocumented endpoint, may change)
203
245
  openrouter models parameters openai/gpt-4o --provider openai
204
246
 
205
247
  # Compare provider variants for one model - find the best one (status column too)
@@ -210,7 +252,8 @@ openrouter benchmarks --task-type coding --max-results 20
210
252
  openrouter classifications --window 7d
211
253
  openrouter datasets daily --period week --category programming
212
254
  openrouter analytics meta
213
- openrouter decisions --model typesafe/jev-1.13 --state '...' --questions @questions.json
255
+ openrouter decisions --model typesafe/jev-1.13 --state '...' --questions @questions.json # alias: systemone
256
+ openrouter decisions --model <vision-decider> --state '...' --image ./chart.png --questions @q.json
214
257
  openrouter containers list <container-id>
215
258
 
216
259
  # Supporting metadata
@@ -219,19 +262,23 @@ openrouter embed models # embedding models
219
262
  openrouter image models # image gen models
220
263
  openrouter video models # video gen models
221
264
  openrouter zdr # ZDR-eligible endpoints
265
+ openrouter tools list # server tools catalog (openrouter:*)
266
+ openrouter tools get web_search # params, engines, pricing
222
267
  ```
223
268
 
224
269
  ### Account / spend / runs
225
270
 
226
271
  ```bash
227
272
  openrouter credits # total balance + total usage
228
- openrouter whoami # label, daily/weekly/monthly usage, rate limit
273
+ openrouter whoami # label, usage, rate limit, budgets, data regions
229
274
  openrouter generation gen-1234567890 # full per-request metadata + cost
230
275
  openrouter generation gen-1234567890 --content # + the input/output content
276
+ openrouter generation feedback gen-1234567890 --category incorrect_response --comment "..."
231
277
 
232
278
  # Activity (management key required) - daily aggregates per endpoint
233
279
  openrouter activity --date 2026-04-28
234
280
  openrouter activity --api-key-hash <hash>
281
+ openrouter activity --group-by workspace
235
282
  ```
236
283
 
237
284
  NOTE: `activity` only covers **completed UTC days** in the last 30 days.
@@ -239,17 +286,18 @@ Today's data isn't queryable until tomorrow. There's no per-request log
239
286
  endpoint - the only way to inspect a specific in-flight request is by
240
287
  `generation <id>` if you saved the id at call time.
241
288
 
242
- `generation` lookups have a ~30-second propagation delay after the request
243
- completes.
289
+ `generation` lookups have a short propagation delay after the request
290
+ completes (the CLI retries a 404 once). Ids must look like `gen-...`.
244
291
 
245
292
  ### Key management (management key required)
246
293
 
247
294
  ```bash
248
- openrouter keys list
249
- openrouter keys create "agent key" --limit 25 --limit-reset monthly
295
+ openrouter keys list # expired keys hidden; --include-expired shows them
296
+ openrouter keys create "agent key" --limit 25 --limit-reset monthly --expires-at 2026-12-31T00:00:00Z
250
297
  openrouter keys get <hash>
251
298
  openrouter keys update <hash> --name "renamed" --limit 50
252
299
  openrouter keys update <hash> --disabled
300
+ openrouter keys update <hash> --workspace <uuid> # move the key to another workspace
253
301
  openrouter keys delete <hash>
254
302
  ```
255
303
 
@@ -262,15 +310,26 @@ response - capture it then.
262
310
  openrouter guardrails list
263
311
  openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-zdr
264
312
  openrouter guardrails update <id> --limit-usd 10 --reset-interval daily --include-byok
265
- openrouter guardrails assign-key <id> <key-hash>
266
- openrouter guardrails delete <id>
313
+ openrouter guardrails update <id> --regions europe --builtin-filters email:redact,secrets:block --no-paid-training
314
+ openrouter guardrails update <id> --allow-safety-retention-google --no-allow-safety-retention-other
315
+ openrouter guardrails assign-key <id> <key-hash> # up to 500 hashes per call
267
316
 
268
317
  openrouter workspaces list
269
318
  openrouter workspaces create "staging" --slug staging --default-text-model openai/gpt-4o-mini
319
+ openrouter workspaces update staging --disable-tools web_search --broadcast --io-logging-rate 0.1
270
320
  openrouter workspaces add-members <id|slug> <user_id> [<user_id>...]
321
+ openrouter workspaces members <id|slug> # org accounts only
322
+ openrouter workspaces budgets staging # spend caps per interval
323
+ openrouter workspaces budgets set staging monthly --limit 100 # lifetime > monthly > weekly > daily
324
+ openrouter workspaces budgets delete staging monthly
271
325
  openrouter workspaces delete <id|slug>
272
326
 
273
- openrouter org members
327
+ # Observability destinations (Langfuse, Datadog, ...): secrets masked in tables
328
+ openrouter observability list # alias: obs
329
+ openrouter observability create "langfuse" --type langfuse --config @langfuse.json
330
+
331
+ openrouter org members # org accounts only
332
+ openrouter org settings --filtered-catalog true # /models shows only models the key can use
274
333
  ```
275
334
 
276
335
  ### BYOK provider integrations (management key required)
@@ -282,6 +341,7 @@ through your own provider accounts.
282
341
  openrouter byok list
283
342
  openrouter byok create --provider anthropic --api-key sk-ant-... --name "my anthropic" --fallback
284
343
  openrouter byok update <id> --allowed-models "anthropic/claude-sonnet-4.5" --disabled
344
+ openrouter byok update <id> --region europe --zdr true --byok-only
285
345
  openrouter byok get <id>
286
346
  openrouter byok delete <id>
287
347
  ```
@@ -292,15 +352,16 @@ The `--api-key` flag is the upstream provider secret (never echoed back).
292
352
 
293
353
  ```bash
294
354
  # Files - backing store for file/PDF inputs
295
- openrouter files upload ./report.pdf --purpose user_data
355
+ openrouter files upload ./report.pdf [--workspace <uuid>] [--provider openai|anthropic]
296
356
  openrouter files list
297
357
  openrouter files download <file_id> -o report.pdf
298
358
  openrouter files delete <file_id>
299
359
 
300
- # Presets - saved config profiles (read-only). Invoke via @preset/<slug> as a model.
360
+ # Presets - saved config profiles. Invoke via @preset/<slug> as a model.
301
361
  openrouter presets list
302
362
  openrouter presets get <slug>
303
363
  openrouter presets versions <slug>
364
+ openrouter presets create <slug> --api chat --body @preset.json # existing slug = new version
304
365
  ```
305
366
 
306
367
  ### Raw escape hatch
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aaronjmars/openroutercli",
3
- "version": "0.3.0",
3
+ "version": "0.5.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/api.js CHANGED
@@ -47,6 +47,17 @@ async function parseError(res) {
47
47
  });
48
48
  }
49
49
 
50
+ // Array values repeat the key (`status=a&status=b`), the form list filters expect.
51
+ function buildQuery(query) {
52
+ const params = new URLSearchParams();
53
+ for (const [k, v] of Object.entries(query)) {
54
+ if (v === undefined || v === null) continue;
55
+ if (Array.isArray(v)) for (const item of v) params.append(k, item);
56
+ else params.append(k, v);
57
+ }
58
+ return params.toString();
59
+ }
60
+
50
61
  export async function api(method, path, opts = {}) {
51
62
  const authOpts = { ...(opts.auth || {}) };
52
63
  if (opts.requiresManagement) authOpts.requiresManagement = true;
@@ -63,7 +74,7 @@ export async function api(method, path, opts = {}) {
63
74
  const requestUrl = opts.rootPath
64
75
  ? joinOriginPath(auth.baseUrl, opts.rootPath, path)
65
76
  : joinUrl(auth.baseUrl, path);
66
- const url = requestUrl + (opts.query ? "?" + new URLSearchParams(opts.query).toString() : "");
77
+ const url = requestUrl + (opts.query ? "?" + buildQuery(opts.query) : "");
67
78
  const headers = buildHeaders({
68
79
  apiKey: auth.apiKey,
69
80
  referer: auth.referer,
package/src/args.js CHANGED
@@ -69,3 +69,51 @@ export function shouldStream(values) {
69
69
  values.stream || (!values["no-stream"] && !values.raw && !isJsonMode() && process.stdout.isTTY)
70
70
  );
71
71
  }
72
+
73
+ // JSON from an inline string or `@file`. Errors name the flag.
74
+ export async function loadJson(value, flag) {
75
+ if (value == null) return undefined;
76
+ const text = value.startsWith("@")
77
+ ? await (async () => {
78
+ const { readFile } = await import("node:fs/promises");
79
+ return readFile(value.slice(1), "utf8");
80
+ })()
81
+ : value;
82
+ try {
83
+ return JSON.parse(text);
84
+ } catch (err) {
85
+ throw new Error(`Invalid JSON for ${flag}: ${err.message}`);
86
+ }
87
+ }
88
+
89
+ // Request fields shared by inference endpoints. session_id / user / trace are
90
+ // on every one; service_tier only on chat, messages and responses (media
91
+ // commands use MEDIA_FIELD_OPTIONS below).
92
+ export const REQUEST_FIELD_OPTIONS = {
93
+ "session-id": { type: "string" },
94
+ user: { type: "string" },
95
+ trace: { type: "string" },
96
+ "service-tier": { type: "string" },
97
+ };
98
+
99
+ export const REQUEST_FIELD_HELP = ` --session-id <id> Group related requests into one session (max 256 chars)
100
+ --user <id> Your end-user id (abuse tracking, per-user analytics)
101
+ --trace <json|@file> Observability trace: trace_id, trace_name, span_name,
102
+ generation_name, parent_span_id
103
+ --service-tier <t> auto | default | fast | flex | priority | scale | ultrafast
104
+ `;
105
+
106
+ export async function applyRequestFields(body, values) {
107
+ if (values["session-id"]) body.session_id = values["session-id"];
108
+ if (values.user) body.user = values.user;
109
+ if (values.trace) body.trace = await loadJson(values.trace, "--trace");
110
+ if (values["service-tier"]) body.service_tier = values["service-tier"];
111
+ return body;
112
+ }
113
+
114
+ // service_tier is not part of the media request schemas (images, videos,
115
+ // speech, transcription, embeddings, rerank), so those commands drop it.
116
+ export const MEDIA_FIELD_OPTIONS = Object.fromEntries(
117
+ Object.entries(REQUEST_FIELD_OPTIONS).filter(([name]) => name !== "service-tier"),
118
+ );
119
+ export const MEDIA_FIELD_HELP = REQUEST_FIELD_HELP.replace(/^.*--service-tier.*\n/m, "");
package/src/cli.js CHANGED
@@ -25,7 +25,10 @@ import {
25
25
  classificationsCommand,
26
26
  datasetsCommand,
27
27
  } from "./commands/data.js";
28
- import { decisionsCommand } from "./commands/decisions.js";
28
+ import { decisionsCommand, systemoneCommand } from "./commands/decisions.js";
29
+ import { batchesCommand } from "./commands/batches.js";
30
+ import { toolsCommand } from "./commands/tools.js";
31
+ import { observabilityCommand } from "./commands/observability.js";
29
32
  import { containersCommand } from "./commands/containers.js";
30
33
  import { DEFAULT_BASE_URL } from "./config.js";
31
34
  import { readFileSync } from "node:fs";
@@ -72,6 +75,12 @@ const COMMANDS = {
72
75
  datasets: datasetsCommand,
73
76
  decisions: decisionsCommand,
74
77
  decision: decisionsCommand,
78
+ systemone: systemoneCommand,
79
+ batches: batchesCommand,
80
+ batch: batchesCommand,
81
+ tools: toolsCommand,
82
+ observability: observabilityCommand,
83
+ obs: observabilityCommand,
75
84
  containers: containersCommand,
76
85
  request: requestCommand,
77
86
  };
@@ -99,34 +108,41 @@ Inference:
99
108
  transcribe <file> Speech to text (audio in). Alias: stt
100
109
  video <sub> Video generation jobs (create / get / wait / download / models)
101
110
  image <sub> Image generation (create / models / endpoints). Alias: images
111
+ batches <sub> Async batch jobs at ~half price (list / create / get / wait /
112
+ results / delete). Alias: batch
102
113
 
103
114
  Discovery:
104
115
  models [list|show|endpoints|parameters|count|user] List models, full model
105
- detail, provider variants, param
106
- analytics, count, or your set
116
+ detail, provider variants, supported
117
+ params, count, or your set
107
118
  embed models List embedding models
108
119
  video models List video generation models
109
120
  image models List image generation models
110
121
  providers List providers (with HQ + datacenters)
111
- presets <sub> list / get / versions (saved config profiles)
122
+ presets <sub> list / get / versions / create (saved config profiles)
112
123
  generation <id> [--content] Generation metadata or content
124
+ generation feedback <id> --category <c> Report a problem with a generation
125
+ tools [list|get] Server tools (web_search, web_fetch, datetime...) + engines
113
126
  credits Remaining credits
114
127
  activity Usage activity (management key)
115
128
  benchmarks [options] Unified benchmark rankings
116
129
  classifications [options] Task classification market share
117
130
  datasets <sub> Public usage datasets
118
- decisions Structured Decisions API (alpha)
131
+ systemone System One structured decisions (alias: decisions)
119
132
  containers <sub> Hosted shell output files
120
- files <sub> Workspace files
133
+ files <sub> Workspace files
121
134
  zdr Preview Zero-Data-Retention impact
122
135
 
123
136
  Management (require a management key):
124
137
  keys <sub> list / get / create / update / delete
125
138
  byok <sub> list / get / create / update / delete (provider integrations)
126
139
  guardrails <sub> list / get / create / update / delete / assignments
127
- workspaces <sub> list / get / create / update / delete / add-members / remove-members
140
+ workspaces <sub> list / get / create / update / delete / members / add-members /
141
+ remove-members / budgets
142
+ observability <sub> list / get / create / update / delete trace destinations. Alias: obs
128
143
  analytics <sub> meta / query (management key)
129
- org members List organization members
144
+ org members List organization members (org accounts)
145
+ org settings Show or change organization settings (org accounts)
130
146
  auth-code Mint a PKCE authorization code so a user can claim a key
131
147
  request <METHOD> <path> Raw authenticated request to any endpoint
132
148
 
@@ -40,6 +40,28 @@ function renderKey(label, data) {
40
40
  ` rate_limit: ${d.rate_limit.requests ?? "?"} req / ${d.rate_limit.interval ?? "?"}`,
41
41
  );
42
42
  }
43
+ if (d.allowed_data_regions) {
44
+ outln(` data_regions: ${d.allowed_data_regions.join(", ") || "-"}`);
45
+ }
46
+ if (d.effective_budget) {
47
+ outln(` effective_budget: ${fmtBudget(d.effective_budget)}`);
48
+ }
49
+ if (Array.isArray(d.budgets) && d.budgets.length) {
50
+ outln(
51
+ " budgets: " + c.dim("(checked in this order; any at $0 left blocks requests)"),
52
+ );
53
+ for (const b of d.budgets) outln(` ${fmtBudget(b)}`);
54
+ }
55
+ }
56
+
57
+ // One budget layer on a line: scope, spend/limit, remaining, window.
58
+ function fmtBudget(b) {
59
+ const money = (x) => (x == null ? "?" : `$${Number(x).toFixed(2)}`);
60
+ const window = b.reset_interval
61
+ ? `${b.reset_interval}${b.resets_at ? `, resets ${b.resets_at}` : ""}`
62
+ : "lifetime";
63
+ const byok = b.include_byok ? ", incl. BYOK" : "";
64
+ return `${b.scope ?? "?"}: ${money(b.spend_usd)} of ${money(b.limit_usd)} used, ${money(b.remaining_usd)} left (${window}${byok})`;
43
65
  }
44
66
 
45
67
  export async function whoamiCommand(argv) {
@@ -113,17 +135,32 @@ export async function activityCommand(argv) {
113
135
  date: { type: "string" },
114
136
  "api-key-hash": { type: "string" },
115
137
  "user-id": { type: "string" },
138
+ "group-by": { type: "string" },
139
+ workspace: { type: "string" },
116
140
  });
117
141
  if (values.help) {
118
142
  process.stdout.write(
119
- `Usage: openrouter activity [options]\n\nGet usage activity grouped by endpoint.\n\nOptions:\n --date <YYYY-MM-DD> UTC date in last 30 days\n --api-key-hash <hash> Filter by API key SHA-256 hash\n --user-id <id> Filter by org member user ID\n`,
143
+ "Usage: openrouter activity [options]\n\n" +
144
+ "Get usage activity for the last 30 completed UTC days, grouped by endpoint.\n" +
145
+ "Requires a management key.\n\n" +
146
+ "Options:\n" +
147
+ " --date <YYYY-MM-DD> UTC date in last 30 days\n" +
148
+ " --api-key-hash <hash> Filter by API key SHA-256 hash\n" +
149
+ " --user-id <id> Filter by org member user ID\n" +
150
+ " --workspace <uuid> Only activity attributed to this workspace\n" +
151
+ " --group-by workspace Split each row per workspace (adds workspace_id)\n",
120
152
  );
121
153
  return 0;
122
154
  }
155
+ if (values["group-by"] && values["group-by"] !== "workspace") {
156
+ throw new Error(`Unknown --group-by "${values["group-by"]}". Expected: workspace`);
157
+ }
123
158
  const query = {};
124
159
  if (values.date) query.date = values.date;
125
160
  if (values["api-key-hash"]) query.api_key_hash = values["api-key-hash"];
126
161
  if (values["user-id"]) query.user_id = values["user-id"];
162
+ if (values.workspace) query.workspace_id = values.workspace;
163
+ if (values["group-by"]) query.group_by = values["group-by"];
127
164
  const data = await api("GET", "/activity", {
128
165
  auth: authFromValues(values),
129
166
  requiresManagement: true,
@@ -135,13 +172,20 @@ export async function activityCommand(argv) {
135
172
  outln(c.dim("(no activity)"));
136
173
  return;
137
174
  }
138
- table(rows, [
175
+ const columns = [
139
176
  { label: "date", value: (r) => r.date || r.day || "" },
140
177
  { label: "model", value: (r) => r.model || r.model_permaslug || "" },
178
+ { label: "provider", value: (r) => r.provider_name || "" },
141
179
  { label: "requests", value: (r) => r.requests ?? r.request_count ?? "" },
142
- { label: "tokens", value: (r) => r.tokens ?? r.total_tokens ?? "" },
180
+ { label: "prompt", value: (r) => r.prompt_tokens ?? "" },
181
+ { label: "completion", value: (r) => r.completion_tokens ?? "" },
182
+ { label: "cached", value: (r) => r.cached_tokens ?? "" },
143
183
  { label: "cost", value: (r) => r.usage ?? r.cost ?? "" },
144
- ]);
184
+ ];
185
+ if (rows.some((r) => r.workspace_id)) {
186
+ columns.splice(1, 0, { label: "workspace", value: (r) => r.workspace_id || "" });
187
+ }
188
+ table(rows, columns);
145
189
  });
146
190
  return 0;
147
191
  }