@aaronjmars/openroutercli 0.2.2 → 0.4.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
@@ -18,7 +18,7 @@
18
18
 
19
19
  <p align="center">
20
20
  <strong>Every OpenRouter endpoint, on the command line - for humans and LLM agents</strong><br>
21
- Browser-based OAuth login, full access to chat / messages / responses / embeddings / rerank / audio / video / models / providers / generations / credits / activity / keys / guardrails / workspaces, and a raw <code>request</code> escape hatch. <code>--json</code> on every command. Zero npm dependencies.
21
+ Browser-based OAuth login, inference, discovery, analytics, benchmarks, public datasets, Decisions, container files, account management, and a raw <code>request</code> escape hatch. <code>--json</code> on every command. Zero npm dependencies.
22
22
  </p>
23
23
 
24
24
  ---
@@ -71,15 +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. |
82
+ | **Benchmarks + rankings** | `benchmarks`, `classifications`, and `datasets {apps,daily,session-cost}` expose OpenRouter's current public benchmark and usage datasets. |
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. |
85
+ | **Server tools catalog** | `tools list` / `tools get <name>` - every OpenRouter-run tool (web search, fetch, datetime, ...) with params, engines and pricing. |
86
+ | **Hosted shell files** | `containers {list,get,download,promote}` retrieves and promotes files produced by OpenRouter's hosted shell tools. |
81
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. |
82
- | **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. |
83
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. |
84
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. |
85
91
  | **Zero npm dependencies** | Pure Node 20+ - built-in `fetch`, `parseArgs`, `crypto`. Cold install in seconds. Easy to audit. |
@@ -121,6 +127,14 @@ openrouter chat "List 3 fruits" -m openai/gpt-4o-mini \
121
127
  openrouter chat "What is 2+2?" -m openai/gpt-4o-mini \
122
128
  --tool @calc.json --tool-choice required --raw
123
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
136
+ openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
137
+
124
138
  # Discovery
125
139
  openrouter models --filter claude --sort prompt
126
140
  openrouter models show anthropic/claude-sonnet-4.5
@@ -137,6 +151,8 @@ openrouter activity --date 2026-04-28 --api-key-hash <hash>
137
151
  openrouter keys create "agent-key" --limit 25 --limit-reset monthly
138
152
  openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-zdr
139
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
140
156
 
141
157
  # Raw escape hatch - call any endpoint
142
158
  openrouter request POST /chat/completions --body @body.json
@@ -163,7 +179,12 @@ Endpoint coverage map:
163
179
  | `GET /key` | `openrouter whoami` |
164
180
  | `GET /credits` | `openrouter credits` |
165
181
  | `GET /activity` | `openrouter activity` |
182
+ | `GET /analytics/meta` / `POST /analytics/query` | `openrouter analytics {meta,query}` |
183
+ | `GET /benchmarks` | `openrouter benchmarks` |
184
+ | `GET /classifications/task` | `openrouter classifications` |
185
+ | `GET /datasets/app-rankings` / `GET /datasets/rankings-daily` / `GET /datasets/session-cost` | `openrouter datasets {apps,daily,session-cost}` |
166
186
  | `GET /models` | `openrouter models list` |
187
+ | `GET /model/{author}/{slug}` | `openrouter models show` |
167
188
  | `GET /models/count` | `openrouter models count` |
168
189
  | `GET /models/user` | `openrouter models user` |
169
190
  | `GET /models/{author}/{slug}/endpoints` | `openrouter models endpoints` |
@@ -176,11 +197,21 @@ Endpoint coverage map:
176
197
  | `POST /rerank` | `openrouter rerank` |
177
198
  | `POST /audio/speech` | `openrouter speech`, `openrouter tts` |
178
199
  | `POST /videos`, `GET /videos/{id}`, `GET /videos/{id}/content`, `GET /videos/models` | `openrouter video {create,get,wait,download,models}` |
179
- | `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]` |
180
205
  | `GET/POST/PATCH/DELETE /keys[/{hash}]` | `openrouter keys {list,get,create,update,delete}` |
181
206
  | `GET/POST/PATCH/DELETE /guardrails[/{id}]` + assignments | `openrouter guardrails ...` |
182
- | `GET/POST/PATCH/DELETE /workspaces[/{id}]` + members | `openrouter workspaces ...` |
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` |
212
+ | `GET /containers/{id}/files[/{file}]` + content/promote | `openrouter containers ...` |
183
213
  | `GET /organization/members` | `openrouter org members` |
214
+ | `GET/PATCH /organization/settings` | `openrouter org settings` |
184
215
  | anything else | `openrouter request <METHOD> <path>` |
185
216
 
186
217
  ## Configuration
@@ -191,6 +222,7 @@ Endpoint coverage map:
191
222
  | `--base-url <url>` | `OPENROUTER_BASE_URL` | API base (default `https://openrouter.ai/api/v1`) |
192
223
  | `--referer <url>` | `OPENROUTER_REFERER` | `HTTP-Referer` header (your app URL) |
193
224
  | `--title <name>` | `OPENROUTER_TITLE` | `X-Title` header (your app name; appears on openrouter.ai) |
225
+ | `--categories <csv>` | `OPENROUTER_CATEGORIES` | `X-OpenRouter-Categories` attribution header |
194
226
  | `--json` | - | JSON output, no streaming, no color |
195
227
  | `-q, --quiet` | - | Suppress informational stderr |
196
228
  | `-V, --version` | - | Print the version |
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
@@ -24,6 +24,12 @@ TRIGGER when the user asks to:
24
24
  - create / list / disable / delete OpenRouter API keys programmatically
25
25
  - manage BYOK provider integrations, guardrails, workspaces, files, presets, or
26
26
  organization members
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
31
+ - query management analytics
32
+ - submit structured Decisions requests or retrieve hosted-container files
27
33
  - log in to OpenRouter from a fresh machine (OAuth PKCE in the browser)
28
34
 
29
35
  SKIP when the user is already using the OpenAI / Anthropic / Cohere SDKs
@@ -76,8 +82,8 @@ command automatically.
76
82
 
77
83
  | Slot | Used by | How to obtain |
78
84
  | --- | --- | --- |
79
- | **User key** | `chat`, `messages`, `responses`, `embed`, `rerank`, `speech`, `transcribe`, `image`, `video`, `files`, `presets`, `generation`, `credits`, `whoami` | OAuth (`openrouter login`) or paste from dashboard |
80
- | **Management key** | `keys`, `byok`, `guardrails`, `workspaces`, `activity`, `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`. |
81
87
 
82
88
  You can store both - they live side by side in the config file. `--key sk-or-...`
83
89
  always wins over both. Inference commands prefer the user key; management
@@ -138,15 +144,34 @@ openrouter chat "tricky question" -m anthropic/claude-sonnet-4.5 --reasoning hig
138
144
  openrouter chat "prove it" -m openai/gpt-5-mini --reasoning-max-tokens 2000
139
145
  openrouter chat "quick" -m openai/gpt-5-mini --reasoning-exclude
140
146
 
141
- # Web search plugin (also works via the :online model suffix)
142
- 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
143
159
 
144
160
  # Attach a PDF / file and parse it
145
161
  openrouter chat "summarize this" -m google/gemini-2.5-flash --file ./report.pdf --pdf-engine mistral-ocr
146
162
 
147
- # 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
148
165
  openrouter chat "answer from the doc" -m anthropic/claude-sonnet-4.5 -s "$(cat big-context.txt)" --cache-system
149
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
+
150
175
  # Sampling / output controls
151
176
  openrouter chat "..." -m openai/gpt-4o-mini --top-a 0.2 --logprobs --top-logprobs 5
152
177
 
@@ -164,20 +189,40 @@ openrouter chat -i -m openrouter/auto
164
189
 
165
190
  # Anthropic-format and OpenAI Responses API are also available
166
191
  openrouter messages "..." -m anthropic/claude-sonnet-4.5 --thinking-budget 2000
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
167
194
  openrouter responses "..." -m openai/gpt-4o-mini --store --include reasoning.encrypted_content
195
+ openrouter responses "..." -m openai/gpt-5-mini --verbosity low --truncation auto
168
196
 
169
- # Embeddings, rerank
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 # {custom_id, body} per line
199
+ openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
200
+
201
+ # Embeddings (text or images), rerank
170
202
  openrouter embed -m openai/text-embedding-3-small "hello" "world"
203
+ openrouter embed -m <multimodal-embed-model> "a cat" --image ./cat.png
171
204
  openrouter rerank -m cohere/rerank-v3.5 --query "italian food" -d pizza -d sushi -d pasta
172
205
 
173
- # Text to speech (audio out) and speech to text (audio in)
174
- 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
175
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
176
216
 
177
- # Image generation (writes image-0.png, ...); and video jobs
217
+ # Image generation (writes image-0.png, ...): tier or exact size, reference images
178
218
  openrouter image "a red bike on a beach" -m google/gemini-2.5-flash-image -o bike.png
179
- 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
180
224
  openrouter video wait <jobId> && openrouter video download <jobId> -o out.mp4
225
+ openrouter video create "keep going" -m <video-model> --extend <jobId>
181
226
  ```
182
227
 
183
228
  ### Discovery & pricing
@@ -196,13 +241,20 @@ openrouter models --supported tools # filter by capability
196
241
  # reasoning config, supported voices
197
242
  openrouter models show anthropic/claude-sonnet-4.5
198
243
 
199
- # Supported params + popularity analytics (p10/p50/p90 per parameter)
244
+ # Supported request parameters (undocumented endpoint, may change)
200
245
  openrouter models parameters openai/gpt-4o --provider openai
201
246
 
202
247
  # Compare provider variants for one model - find the best one (status column too)
203
248
  openrouter models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best
204
249
  openrouter models endpoints openai/gpt-4o-mini --sort latency
205
250
  openrouter models endpoints openai/gpt-4o-mini --sort prompt
251
+ openrouter benchmarks --task-type coding --max-results 20
252
+ openrouter classifications --window 7d
253
+ openrouter datasets daily --period week --category programming
254
+ openrouter analytics meta
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
257
+ openrouter containers list <container-id>
206
258
 
207
259
  # Supporting metadata
208
260
  openrouter providers # all providers
@@ -210,19 +262,23 @@ openrouter embed models # embedding models
210
262
  openrouter image models # image gen models
211
263
  openrouter video models # video gen models
212
264
  openrouter zdr # ZDR-eligible endpoints
265
+ openrouter tools list # server tools catalog (openrouter:*)
266
+ openrouter tools get web_search # params, engines, pricing
213
267
  ```
214
268
 
215
269
  ### Account / spend / runs
216
270
 
217
271
  ```bash
218
272
  openrouter credits # total balance + total usage
219
- openrouter whoami # label, daily/weekly/monthly usage, rate limit
273
+ openrouter whoami # label, usage, rate limit, budgets, data regions
220
274
  openrouter generation gen-1234567890 # full per-request metadata + cost
221
275
  openrouter generation gen-1234567890 --content # + the input/output content
276
+ openrouter generation feedback gen-1234567890 --category incorrect_response --comment "..."
222
277
 
223
278
  # Activity (management key required) - daily aggregates per endpoint
224
279
  openrouter activity --date 2026-04-28
225
280
  openrouter activity --api-key-hash <hash>
281
+ openrouter activity --group-by workspace
226
282
  ```
227
283
 
228
284
  NOTE: `activity` only covers **completed UTC days** in the last 30 days.
@@ -230,17 +286,18 @@ Today's data isn't queryable until tomorrow. There's no per-request log
230
286
  endpoint - the only way to inspect a specific in-flight request is by
231
287
  `generation <id>` if you saved the id at call time.
232
288
 
233
- `generation` lookups have a ~30-second propagation delay after the request
234
- 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-...`.
235
291
 
236
292
  ### Key management (management key required)
237
293
 
238
294
  ```bash
239
- openrouter keys list
240
- 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
241
297
  openrouter keys get <hash>
242
298
  openrouter keys update <hash> --name "renamed" --limit 50
243
299
  openrouter keys update <hash> --disabled
300
+ openrouter keys update <hash> --workspace <uuid> # move the key to another workspace
244
301
  openrouter keys delete <hash>
245
302
  ```
246
303
 
@@ -253,15 +310,26 @@ response - capture it then.
253
310
  openrouter guardrails list
254
311
  openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-zdr
255
312
  openrouter guardrails update <id> --limit-usd 10 --reset-interval daily --include-byok
256
- openrouter guardrails assign-key <id> <key-hash>
313
+ openrouter guardrails update <id> --regions europe --builtin-filters email:redact,secrets:block --no-paid-training
314
+ openrouter guardrails assign-key <id> <key-hash> # up to 500 hashes per call
257
315
  openrouter guardrails delete <id>
258
316
 
259
317
  openrouter workspaces list
260
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
261
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
262
325
  openrouter workspaces delete <id|slug>
263
326
 
264
- 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
265
333
  ```
266
334
 
267
335
  ### BYOK provider integrations (management key required)
@@ -273,6 +341,7 @@ through your own provider accounts.
273
341
  openrouter byok list
274
342
  openrouter byok create --provider anthropic --api-key sk-ant-... --name "my anthropic" --fallback
275
343
  openrouter byok update <id> --allowed-models "anthropic/claude-sonnet-4.5" --disabled
344
+ openrouter byok update <id> --region europe --zdr true --byok-only
276
345
  openrouter byok get <id>
277
346
  openrouter byok delete <id>
278
347
  ```
@@ -283,15 +352,16 @@ The `--api-key` flag is the upstream provider secret (never echoed back).
283
352
 
284
353
  ```bash
285
354
  # Files - backing store for file/PDF inputs
286
- openrouter files upload ./report.pdf --purpose user_data
355
+ openrouter files upload ./report.pdf [--workspace <uuid>] [--provider openai|anthropic]
287
356
  openrouter files list
288
357
  openrouter files download <file_id> -o report.pdf
289
358
  openrouter files delete <file_id>
290
359
 
291
- # 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.
292
361
  openrouter presets list
293
362
  openrouter presets get <slug>
294
363
  openrouter presets versions <slug>
364
+ openrouter presets create <slug> --api chat --body @preset.json # existing slug = new version
295
365
  ```
296
366
 
297
367
  ### Raw escape hatch
@@ -384,7 +454,8 @@ openrouter --json keys get <hash> | jq '.data | {usage, usage_daily, limit_remai
384
454
  | `-k, --key` | `OPENROUTER_API_KEY` (alias `OPENROUTER_KEY`) / `OPENROUTER_MANAGEMENT_KEY` | from config |
385
455
  | `--base-url` | `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` |
386
456
  | `--referer` | `OPENROUTER_REFERER` | `https://github.com/aaronjmars/openroutercli` |
387
- | `--title` | `OPENROUTER_TITLE` | `openrouter-cli` |
457
+ | `--title` | `OPENROUTER_TITLE` | `X-OpenRouter-Title` app display name |
458
+ | `--categories` | `OPENROUTER_CATEGORIES` | `X-OpenRouter-Categories` attribution |
388
459
  | `--json` | - | off |
389
460
  | `-q, --quiet` | - | off |
390
461
  | `-V, --version` | - | prints version, exits |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aaronjmars/openroutercli",
3
- "version": "0.2.2",
3
+ "version": "0.4.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
@@ -10,12 +10,14 @@ export class APIError extends Error {
10
10
  }
11
11
  }
12
12
 
13
- function buildHeaders({ apiKey, referer, title, extra }) {
13
+ function buildHeaders({ apiKey, referer, title, categories, extra }) {
14
14
  const headers = {
15
15
  Accept: "application/json",
16
16
  "HTTP-Referer": referer,
17
17
  "X-Title": title,
18
+ "X-OpenRouter-Title": title,
18
19
  };
20
+ if (categories) headers["X-OpenRouter-Categories"] = categories;
19
21
  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
20
22
  return { ...headers, ...(extra || {}) };
21
23
  }
@@ -25,6 +27,11 @@ function joinUrl(base, path) {
25
27
  return base.replace(/\/$/, "") + (path.startsWith("/") ? path : "/" + path);
26
28
  }
27
29
 
30
+ function joinOriginPath(base, rootPath, path) {
31
+ const origin = new URL(base).origin;
32
+ return joinUrl(origin + rootPath, path);
33
+ }
34
+
28
35
  async function parseError(res) {
29
36
  const text = await res.text();
30
37
  let body = text;
@@ -40,6 +47,17 @@ async function parseError(res) {
40
47
  });
41
48
  }
42
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
+
43
61
  export async function api(method, path, opts = {}) {
44
62
  const authOpts = { ...(opts.auth || {}) };
45
63
  if (opts.requiresManagement) authOpts.requiresManagement = true;
@@ -53,13 +71,15 @@ export async function api(method, path, opts = {}) {
53
71
  throw e;
54
72
  }
55
73
 
56
- const url =
57
- joinUrl(auth.baseUrl, path) +
58
- (opts.query ? "?" + new URLSearchParams(opts.query).toString() : "");
74
+ const requestUrl = opts.rootPath
75
+ ? joinOriginPath(auth.baseUrl, opts.rootPath, path)
76
+ : joinUrl(auth.baseUrl, path);
77
+ const url = requestUrl + (opts.query ? "?" + buildQuery(opts.query) : "");
59
78
  const headers = buildHeaders({
60
79
  apiKey: auth.apiKey,
61
80
  referer: auth.referer,
62
81
  title: auth.title,
82
+ categories: auth.categories,
63
83
  extra: opts.headers,
64
84
  });
65
85
 
package/src/args.js CHANGED
@@ -7,6 +7,7 @@ const GLOBAL_OPTIONS = {
7
7
  "base-url": { type: "string" },
8
8
  referer: { type: "string" },
9
9
  title: { type: "string" },
10
+ categories: { type: "string" },
10
11
  json: { type: "boolean" },
11
12
  quiet: { type: "boolean", short: "q" },
12
13
  help: { type: "boolean", short: "h" },
@@ -52,6 +53,7 @@ export function authFromValues(values) {
52
53
  if (values["base-url"]) out.baseUrl = values["base-url"];
53
54
  if (values.referer) out.referer = values.referer;
54
55
  if (values.title) out.title = values.title;
56
+ if (values.categories) out.categories = values.categories;
55
57
  return out;
56
58
  }
57
59
 
@@ -67,3 +69,51 @@ export function shouldStream(values) {
67
69
  values.stream || (!values["no-stream"] && !values.raw && !isJsonMode() && process.stdout.isTTY)
68
70
  );
69
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
@@ -19,6 +19,17 @@ import { requestCommand } from "./commands/request.js";
19
19
  import { guardrailsCommand } from "./commands/guardrails.js";
20
20
  import { workspacesCommand } from "./commands/workspaces.js";
21
21
  import { orgCommand, zdrCommand, authCodeCommand } from "./commands/misc.js";
22
+ import {
23
+ analyticsCommand,
24
+ benchmarksCommand,
25
+ classificationsCommand,
26
+ datasetsCommand,
27
+ } from "./commands/data.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";
32
+ import { containersCommand } from "./commands/containers.js";
22
33
  import { DEFAULT_BASE_URL } from "./config.js";
23
34
  import { readFileSync } from "node:fs";
24
35
  import { fileURLToPath } from "node:url";
@@ -58,6 +69,19 @@ const COMMANDS = {
58
69
  org: orgCommand,
59
70
  zdr: zdrCommand,
60
71
  "auth-code": authCodeCommand,
72
+ analytics: analyticsCommand,
73
+ benchmarks: benchmarksCommand,
74
+ classifications: classificationsCommand,
75
+ datasets: datasetsCommand,
76
+ decisions: decisionsCommand,
77
+ decision: decisionsCommand,
78
+ systemone: systemoneCommand,
79
+ batches: batchesCommand,
80
+ batch: batchesCommand,
81
+ tools: toolsCommand,
82
+ observability: observabilityCommand,
83
+ obs: observabilityCommand,
84
+ containers: containersCommand,
61
85
  request: requestCommand,
62
86
  };
63
87
 
@@ -84,28 +108,41 @@ Inference:
84
108
  transcribe <file> Speech to text (audio in). Alias: stt
85
109
  video <sub> Video generation jobs (create / get / wait / download / models)
86
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
87
113
 
88
114
  Discovery:
89
115
  models [list|show|endpoints|parameters|count|user] List models, full model
90
- detail, provider variants, param
91
- analytics, count, or your set
116
+ detail, provider variants, supported
117
+ params, count, or your set
92
118
  embed models List embedding models
93
119
  video models List video generation models
94
120
  image models List image generation models
95
121
  providers List providers (with HQ + datacenters)
96
- presets <sub> list / get / versions (saved config profiles)
122
+ presets <sub> list / get / versions / create (saved config profiles)
97
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
98
126
  credits Remaining credits
99
127
  activity Usage activity (management key)
128
+ benchmarks [options] Unified benchmark rankings
129
+ classifications [options] Task classification market share
130
+ datasets <sub> Public usage datasets
131
+ systemone System One structured decisions (alias: decisions)
132
+ containers <sub> Hosted shell output files
133
+ files <sub> Workspace files
100
134
  zdr Preview Zero-Data-Retention impact
101
135
 
102
136
  Management (require a management key):
103
137
  keys <sub> list / get / create / update / delete
104
138
  byok <sub> list / get / create / update / delete (provider integrations)
105
139
  guardrails <sub> list / get / create / update / delete / assignments
106
- workspaces <sub> list / get / create / update / delete / add-members / remove-members
107
- files <sub> list / get / upload / download / delete
108
- org members List organization 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
143
+ analytics <sub> meta / query (management key)
144
+ org members List organization members (org accounts)
145
+ org settings Show or change organization settings (org accounts)
109
146
  auth-code Mint a PKCE authorization code so a user can claim a key
110
147
  request <METHOD> <path> Raw authenticated request to any endpoint
111
148
 
@@ -114,6 +151,7 @@ Global options (work with all commands):
114
151
  --base-url <url> Override API base URL (default: ${DEFAULT_BASE_URL})
115
152
  --referer <url> HTTP-Referer header (set as your app's URL)
116
153
  --title <name> X-Title header (your app name; appears on openrouter.ai)
154
+ --categories <csv> X-OpenRouter-Categories attribution (e.g. cli-agent)
117
155
  --json Output JSON (also disables streaming, color, and prompts)
118
156
  -q, --quiet Suppress informational stderr messages
119
157
  -V, --version Print the version
@@ -124,7 +162,8 @@ Environment:
124
162
  OPENROUTER_MANAGEMENT_KEY Default management/provisioning key
125
163
  OPENROUTER_BASE_URL Default base URL
126
164
  OPENROUTER_REFERER Default HTTP-Referer
127
- OPENROUTER_TITLE Default X-Title
165
+ OPENROUTER_TITLE Default X-Title / X-OpenRouter-Title
166
+ OPENROUTER_CATEGORIES Default X-OpenRouter-Categories
128
167
  NO_COLOR Disable ANSI colors (alias: OPENROUTER_NO_COLOR)
129
168
  OPENROUTER_DEBUG=1 Print stack traces on error
130
169
 
@@ -140,9 +179,18 @@ Version: ${VERSION}
140
179
  `;
141
180
 
142
181
  function preParseGlobals(argv) {
143
- // --json/--quiet/--version work in any position; the rest are merged
144
- // per-command in args.js.
182
+ // Global flags work in any position. Value-taking globals are moved after
183
+ // the command so `openrouter --key ... chat ...` still dispatches correctly.
145
184
  const out = [];
185
+ const globalTail = [];
186
+ const valueGlobals = new Set([
187
+ "--key",
188
+ "-k",
189
+ "--base-url",
190
+ "--referer",
191
+ "--title",
192
+ "--categories",
193
+ ]);
146
194
  let json = false;
147
195
  let quiet = false;
148
196
  let help = false;
@@ -152,12 +200,21 @@ function preParseGlobals(argv) {
152
200
  if (a === "--json") json = true;
153
201
  else if (a === "-q" || a === "--quiet") quiet = true;
154
202
  else if (a === "-V" || a === "--version") version = true;
155
- else if (a === "-h" || a === "--help") {
203
+ else if (valueGlobals.has(a)) {
204
+ globalTail.push(a);
205
+ if (i + 1 < argv.length) globalTail.push(argv[++i]);
206
+ } else if (
207
+ ["--key", "--base-url", "--referer", "--title", "--categories"].some((flag) =>
208
+ a.startsWith(`${flag}=`),
209
+ )
210
+ ) {
211
+ globalTail.push(a);
212
+ } else if (a === "-h" || a === "--help") {
156
213
  help = true;
157
214
  out.push(a); // forward so subcommand help can also pick it up
158
215
  } else out.push(a);
159
216
  }
160
- return { argv: out, json, quiet, help, version };
217
+ return { argv: [...out, ...globalTail], json, quiet, help, version };
161
218
  }
162
219
 
163
220
  export async function run(argv) {