@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 +30 -9
- package/SKILL.md +86 -25
- package/package.json +1 -1
- package/src/api.js +12 -1
- package/src/args.js +48 -0
- package/src/cli.js +24 -8
- package/src/commands/account.js +48 -4
- package/src/commands/batches.js +360 -0
- package/src/commands/byok.js +114 -40
- package/src/commands/chat.js +277 -43
- package/src/commands/data.js +3 -3
- package/src/commands/decisions.js +46 -24
- package/src/commands/embed.js +35 -10
- package/src/commands/files.js +24 -8
- package/src/commands/generation.js +78 -9
- package/src/commands/guardrails.js +141 -11
- package/src/commands/image.js +43 -12
- package/src/commands/keys.js +59 -11
- package/src/commands/messages.js +217 -61
- package/src/commands/misc.js +76 -11
- package/src/commands/models.js +99 -16
- package/src/commands/observability.js +267 -0
- package/src/commands/presets.js +62 -3
- package/src/commands/rerank.js +28 -6
- package/src/commands/speech.js +80 -15
- package/src/commands/tools.js +102 -0
- package/src/commands/transcribe.js +113 -13
- package/src/commands/video.js +112 -14
- package/src/commands/workspaces.js +201 -6
- package/src/media.js +44 -0
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,
|
|
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
|
-
| **
|
|
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`
|
|
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
|
|
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 /
|
|
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
|
-
#
|
|
145
|
-
openrouter chat "what shipped in the news today?" -m openai/gpt-4o-mini --
|
|
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:
|
|
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
|
|
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 (
|
|
177
|
-
openrouter speech "Hello there" -m elevenlabs/eleven-
|
|
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, ...)
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
266
|
-
openrouter guardrails
|
|
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
|
-
|
|
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 --
|
|
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
|
|
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
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 ? "?" +
|
|
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,
|
|
106
|
-
|
|
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
|
-
|
|
131
|
+
systemone System One structured decisions (alias: decisions)
|
|
119
132
|
containers <sub> Hosted shell output files
|
|
120
|
-
files <sub>
|
|
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 /
|
|
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
|
|
package/src/commands/account.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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: "
|
|
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
|
}
|