@aaronjmars/openroutercli 0.1.2

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 aaronjmars
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,212 @@
1
+ <p align="center">
2
+ <img src="./openrouter-logo.jpeg" alt="openrouter-cli" width="120" />
3
+ </p>
4
+
5
+ <h1 align="center">openrouter-cli</h1>
6
+
7
+ <p align="center">
8
+ <em>Unofficial — not affiliated with or endorsed by OpenRouter.</em>
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/@aaronjmars/openroutercli"><img src="https://img.shields.io/npm/v/%40aaronjmars%2Fopenroutercli?style=flat-square&logo=npm&color=cb3837" alt="npm version"></a>
13
+ <a href="https://www.npmjs.com/package/@aaronjmars/openroutercli"><img src="https://img.shields.io/npm/dm/%40aaronjmars%2Fopenroutercli?style=flat-square&logo=npm&color=cb3837" alt="npm downloads"></a>
14
+ <a href="https://github.com/aaronjmars/openroutercli/stargazers"><img src="https://img.shields.io/github/stars/aaronjmars/openroutercli?style=flat-square&logo=github" alt="GitHub stars"></a>
15
+ <a href="https://github.com/aaronjmars/openroutercli/network/members"><img src="https://img.shields.io/github/forks/aaronjmars/openroutercli?style=flat-square&logo=github" alt="GitHub forks"></a>
16
+ <a href="https://openrouter.ai/"><img src="https://img.shields.io/badge/Powered%20by-OpenRouter-6E4AFF?style=flat-square&labelColor=1a1a2e" alt="Powered by OpenRouter"></a>
17
+ </p>
18
+
19
+ <p align="center">
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.
22
+ </p>
23
+
24
+ ---
25
+
26
+ ## What it does
27
+
28
+ - One CLI for the entire [OpenRouter API](https://openrouter.ai/docs) — every endpoint in the OpenAPI spec is reachable.
29
+ - Login once with browser-based **OAuth (PKCE)**, paste an existing key, or use env vars. Separate slot for **management/provisioning keys**.
30
+ - Streams chat completions in a TTY; emits clean JSON when piped or with `--json`. Built so an agent can `--json | jq` reliably.
31
+ - Knows the difference between user keys and management keys — picks the right one per command.
32
+
33
+ ## Quick start
34
+
35
+ The recommended path: **install with npm + `openrouter login`.** First request in under 60 seconds.
36
+
37
+ **Prereqs** — Node.js 20+ and an [OpenRouter account](https://openrouter.ai/).
38
+
39
+ Install:
40
+
41
+ - **npm** — `npm install -g @aaronjmars/openroutercli`
42
+ - **npx** *(no install)* — `npx -p @aaronjmars/openroutercli openrouter --help`
43
+ - **From source** — `git clone https://github.com/aaronjmars/openroutercli && cd openroutercli && npm link`
44
+
45
+ Then:
46
+
47
+ ```bash
48
+ openrouter login # OAuth in the browser
49
+ openrouter chat "say hi" -m openai/gpt-4o-mini # streaming chat
50
+ openrouter --json models --filter sonnet | jq '.data[].id' # pipeable JSON
51
+ openrouter credits # what's left in the tank
52
+ ```
53
+
54
+ **Other paths** — drop in an existing key with `openrouter login --key sk-or-...`, pipe one in with `--stdin`, or set `OPENROUTER_API_KEY` for ephemeral use. Management keys (for `keys` / `guardrails` / `workspaces` / `activity`) come from the [dashboard](https://openrouter.ai/settings/provisioning-keys) and are saved with `openrouter login --management`.
55
+
56
+ ### Two key types — user vs management
57
+
58
+ <p align="center">
59
+ <img src="./keys.png" alt="User key vs management key — what each one unlocks" />
60
+ </p>
61
+
62
+ The CLI keeps a separate slot for each key type and auto-routes per command.
63
+ `--key sk-or-...` always wins as an override; otherwise inference reaches for
64
+ the user slot, account-management commands reach for the management slot, and
65
+ either falls back to the other when one slot is empty. Management keys
66
+ **cannot** be obtained via OAuth — mint one in the [dashboard](https://openrouter.ai/settings/provisioning-keys)
67
+ and run `openrouter login --management`.
68
+
69
+ ## Features
70
+
71
+ | Feature | What it does |
72
+ |---|---|
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. |
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. |
77
+ | **Interactive REPL** | `openrouter chat -i` — slash commands `/model <id>`, `/reset`, `/exit`. History preserved per session. |
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>`. |
80
+ | **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
+ | **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. |
83
+ | **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
+ | **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
+ | **Zero npm dependencies** | Pure Node 20+ — built-in `fetch`, `parseArgs`, `crypto`. Cold install in seconds. Easy to audit. |
86
+
87
+ Each command supports `openrouter <command> --help` for full per-command flags.
88
+
89
+ ## Use cases
90
+
91
+ - **Throwaway prompts from the shell** — `echo "summarize this" \| openrouter chat -m openai/gpt-4o-mini` instead of opening a browser tab.
92
+ - **Agent / script integration** — `openrouter --json chat ... \| jq` keeps stdout clean and machine-parseable; meaningful exit codes let scripts branch on errors.
93
+ - **Comparing models head-to-head** — `for m in claude-sonnet-4.5 gpt-4o gemini-2.5-pro; do openrouter chat "$prompt" -m anthropic/$m; done`
94
+ - **Picking the cheapest / fastest provider variant** — `openrouter models endpoints <id> --sort throughput --best` before locking in a model in production.
95
+ - **Cost monitoring** — `openrouter credits` + `openrouter whoami` in cron / a status bar; `openrouter keys get <hash>` per-app.
96
+ - **Provisioning per-customer keys** — wrap `openrouter keys create` in your onboarding flow; rotate / disable / delete via `keys update --disabled` and `keys delete`.
97
+ - **Auditing a specific request** — paste a `gen-...` id into `openrouter generation <id> --content` to see exactly what was sent and returned, with cost.
98
+ - **CI smoke-tests for prompt changes** — fixed seed, JSON-schema response, exit non-zero on regression.
99
+
100
+ ## Examples
101
+
102
+ ```bash
103
+ # Browser OAuth login (recommended)
104
+ openrouter login
105
+
106
+ # Manual key entry (and management/provisioning key)
107
+ openrouter login --key sk-or-v1-...
108
+ openrouter login --management --key sk-or-v1-...
109
+
110
+ # Streaming chat
111
+ openrouter chat "Write a haiku about caching" -m anthropic/claude-sonnet-4.5
112
+
113
+ # Multimodal
114
+ openrouter chat "What's in this picture?" -m google/gemini-2.5-flash --image ./photo.jpg
115
+
116
+ # Strict JSON output
117
+ openrouter chat "List 3 fruits" -m openai/gpt-4o-mini \
118
+ --schema '{"type":"object","properties":{"fruits":{"type":"array","items":{"type":"string"}}},"required":["fruits"]}'
119
+
120
+ # Tool calling
121
+ openrouter chat "What is 2+2?" -m openai/gpt-4o-mini \
122
+ --tool @calc.json --tool-choice required --raw
123
+
124
+ # Discovery
125
+ openrouter models --filter claude --sort prompt
126
+ openrouter models show anthropic/claude-sonnet-4.5
127
+ openrouter models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best
128
+ openrouter providers
129
+
130
+ # Spend / runs
131
+ openrouter credits
132
+ openrouter whoami
133
+ openrouter generation gen-1234567890 --content
134
+ openrouter activity --date 2026-04-28 --api-key-hash <hash>
135
+
136
+ # Management (provisioning key required)
137
+ openrouter keys create "agent-key" --limit 25 --limit-reset monthly
138
+ openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-zdr
139
+ openrouter workspaces create "staging" --slug staging --default-text-model openai/gpt-4o-mini
140
+
141
+ # Raw escape hatch — call any endpoint
142
+ openrouter request POST /chat/completions --body @body.json
143
+ openrouter request GET /endpoints/zdr
144
+ ```
145
+
146
+ ## Documentation
147
+
148
+ | | |
149
+ |---|---|
150
+ | `openrouter --help` | Top-level command index |
151
+ | `openrouter <command> --help` | Per-command flags + examples |
152
+ | [SKILL.md](./SKILL.md) | Drop-in skill description for LLM agents (Claude Code / Cursor / etc.) — what to use, when, how, with patterns and pitfalls |
153
+ | [OpenRouter API docs](https://openrouter.ai/docs) | Upstream API reference |
154
+ | [OpenRouter dashboard](https://openrouter.ai/keys) | Manage keys, billing, workspaces in the browser |
155
+ | [Provisioning keys](https://openrouter.ai/settings/provisioning-keys) | Where management keys are minted |
156
+
157
+ Endpoint coverage map:
158
+
159
+ | OpenRouter endpoint | Command |
160
+ |---|---|
161
+ | `POST /auth/keys` (PKCE exchange) | `openrouter login` |
162
+ | `POST /auth/keys/code` | `openrouter auth-code` |
163
+ | `GET /key` | `openrouter whoami` |
164
+ | `GET /credits` | `openrouter credits` |
165
+ | `GET /activity` | `openrouter activity` |
166
+ | `GET /models` | `openrouter models list` |
167
+ | `GET /models/count` | `openrouter models count` |
168
+ | `GET /models/user` | `openrouter models user` |
169
+ | `GET /models/{author}/{slug}/endpoints` | `openrouter models endpoints` |
170
+ | `GET /providers` | `openrouter providers` |
171
+ | `GET /endpoints/zdr` | `openrouter zdr` |
172
+ | `POST /chat/completions` | `openrouter chat`, `openrouter complete` |
173
+ | `POST /messages` | `openrouter messages` |
174
+ | `POST /responses` | `openrouter responses` |
175
+ | `POST /embeddings` / `GET /embeddings/models` | `openrouter embed [models]` |
176
+ | `POST /rerank` | `openrouter rerank` |
177
+ | `POST /audio/speech` | `openrouter speech`, `openrouter tts` |
178
+ | `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]` |
180
+ | `GET/POST/PATCH/DELETE /keys[/{hash}]` | `openrouter keys {list,get,create,update,delete}` |
181
+ | `GET/POST/PATCH/DELETE /guardrails[/{id}]` + assignments | `openrouter guardrails ...` |
182
+ | `GET/POST/PATCH/DELETE /workspaces[/{id}]` + members | `openrouter workspaces ...` |
183
+ | `GET /organization/members` | `openrouter org members` |
184
+ | anything else | `openrouter request <METHOD> <path>` |
185
+
186
+ ## Configuration
187
+
188
+ | flag | env | description |
189
+ |---|---|---|
190
+ | `-k, --key <key>` | `OPENROUTER_API_KEY` (user) / `OPENROUTER_MANAGEMENT_KEY` (mgmt) | API key to use; flag overrides env / config |
191
+ | `--base-url <url>` | `OPENROUTER_BASE_URL` | API base (default `https://openrouter.ai/api/v1`) |
192
+ | `--referer <url>` | `OPENROUTER_REFERER` | `HTTP-Referer` header (your app URL) |
193
+ | `--title <name>` | `OPENROUTER_TITLE` | `X-Title` header (your app name; appears on openrouter.ai) |
194
+ | `--json` | — | JSON output, no streaming, no color |
195
+ | `-q, --quiet` | — | Suppress informational stderr |
196
+ | — | `NO_COLOR` | Disable ANSI colors |
197
+ | — | `OPENROUTER_DEBUG=1` | Stack traces on error |
198
+
199
+ Config file: `~/.config/openrouter/config.json` (or `$XDG_CONFIG_HOME/openrouter/`), `0600` perms.
200
+
201
+ ## License & disclaimer
202
+
203
+ MIT. See [LICENSE](./LICENSE).
204
+
205
+ This is an **unofficial** community project. It is not affiliated with,
206
+ endorsed by, or sponsored by OpenRouter. "OpenRouter" and the OpenRouter
207
+ logo are trademarks of their respective owners; usage here is for
208
+ identification only.
209
+
210
+ ## Star History
211
+
212
+ [![Star History Chart](https://api.star-history.com/svg?repos=aaronjmars/openroutercli&type=Date)](https://www.star-history.com/#aaronjmars/openroutercli&Date)
package/SKILL.md ADDED
@@ -0,0 +1,345 @@
1
+ ---
2
+ name: openrouter-cli
3
+ description: Use the `openrouter` CLI to call any OpenRouter API endpoint from the shell — chat / messages / responses, embeddings, rerank, audio, video, model + provider discovery, generation lookup, credits, activity, and full key / guardrail / workspace management. Pass `--json` on every command for machine-parseable output.
4
+ ---
5
+
6
+ # openrouter-cli skill
7
+
8
+ `openrouter` is a zero-dependency Node CLI that wraps the OpenRouter API. It's
9
+ designed for both humans and LLM agents — every command supports `--json` for
10
+ clean piping, has stable exit codes, and reads stdin where useful.
11
+
12
+ ## When to use this skill
13
+
14
+ TRIGGER when the user asks to:
15
+ - call OpenRouter from the shell, a script, or an agent loop
16
+ - pick a cheaper / faster / more reliable model or provider variant
17
+ - look up pricing, throughput, latency, or supported parameters for a model
18
+ - check credits, per-key spend, daily/weekly/monthly usage, or rate limits
19
+ - inspect or audit a specific generation (`gen-...` id) — input, output, cost,
20
+ latency, finish reason
21
+ - create / list / disable / delete OpenRouter API keys programmatically
22
+ - manage guardrails, workspaces, or organization members
23
+ - log in to OpenRouter from a fresh machine (OAuth PKCE in the browser)
24
+
25
+ SKIP when the user is already using the OpenAI / Anthropic / Cohere SDKs
26
+ directly without OpenRouter, or when the work is purely about model selection
27
+ strategy without any actual API calls.
28
+
29
+ ## Install
30
+
31
+ ```bash
32
+ # Recommended
33
+ npm install -g @aaronjmars/openroutercli
34
+
35
+ # No install
36
+ npx -p @aaronjmars/openroutercli openrouter --help
37
+
38
+ # From source
39
+ git clone https://github.com/aaronjmars/openroutercli && cd openroutercli && npm link
40
+ ```
41
+
42
+ Requires Node.js 20+. Once installed, two binaries are available: `openrouter`
43
+ and the shorter alias `or`.
44
+
45
+ ## Authenticate
46
+
47
+ Three ways, in priority order. The first match wins:
48
+
49
+ 1. `--key sk-or-...` flag on the command (overrides everything)
50
+ 2. Env var: `OPENROUTER_API_KEY` (user) / `OPENROUTER_MANAGEMENT_KEY` (mgmt)
51
+ 3. Stored key from `openrouter login` at `~/.config/openrouter/config.json`
52
+ (`0600`)
53
+
54
+ ```bash
55
+ # Browser OAuth (PKCE) — recommended for humans
56
+ openrouter login
57
+
58
+ # Save an existing key non-interactively
59
+ openrouter login --key sk-or-v1-...
60
+ echo "sk-or-v1-..." | openrouter login --stdin
61
+ openrouter login --no-browser # SSH / headless — prints URL, you open it
62
+
63
+ # Inspect / forget
64
+ openrouter whoami
65
+ openrouter logout
66
+ ```
67
+
68
+ ### Two key slots: user vs management
69
+
70
+ OpenRouter has two key types. The CLI keeps a slot for each and routes per
71
+ command automatically.
72
+
73
+ | Slot | Used by | How to obtain |
74
+ | --- | --- | --- |
75
+ | **User key** | `chat`, `messages`, `responses`, `embed`, `rerank`, `speech`, `video`, `generation`, `credits`, `whoami` | OAuth (`openrouter login`) or paste from dashboard |
76
+ | **Management key** | `keys`, `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`. |
77
+
78
+ You can store both — they live side by side in the config file. `--key sk-or-...`
79
+ always wins over both. Inference commands prefer the user key; management
80
+ commands prefer the management key; either falls back to the other if the
81
+ preferred slot is empty.
82
+
83
+ ## Output: streaming vs JSON
84
+
85
+ - TTY + interactive command → streams tokens to stdout, status to stderr.
86
+ - `--json` → parsed JSON to stdout, no streaming, no color, no spinners.
87
+ - Piped stdout (no `--json`) → still streams unless the command formats a
88
+ table, in which case it switches to a stable text format.
89
+
90
+ For agents, **always pass `--json` and parse the response.** Stderr stays
91
+ clean for diagnostic messages.
92
+
93
+ ## Exit codes
94
+
95
+ | code | meaning |
96
+ | --- | --- |
97
+ | 0 | success |
98
+ | 1 | usage error / unknown command / missing argument |
99
+ | 2 | API error (4xx / 5xx). Message format: `error: <status> <message>` on stderr. |
100
+ | 3 | no API key configured |
101
+ | 4 | async job ended in failed/cancelled state (e.g. `video wait`) |
102
+
103
+ Set `OPENROUTER_DEBUG=1` to print stack traces.
104
+
105
+ ## Common commands
106
+
107
+ ### Inference
108
+
109
+ ```bash
110
+ # Streaming chat (default in TTY)
111
+ openrouter chat "Write a haiku about caching" -m anthropic/claude-sonnet-4.5
112
+
113
+ # One-shot, JSON for scripts
114
+ openrouter --json chat "Reply: ok" -m openai/gpt-4o-mini --no-stream
115
+
116
+ # From stdin
117
+ echo "summarize this" | openrouter chat -m openai/gpt-4o-mini
118
+
119
+ # Multimodal
120
+ openrouter chat "What's in this picture?" -m google/gemini-2.5-flash --image ./photo.jpg
121
+ openrouter chat "Caption this" -m openai/gpt-4o --image https://example.com/cat.png
122
+
123
+ # Strict structured output (JSON schema, strict mode)
124
+ openrouter chat "Pick 3 fruits" -m openai/gpt-4o-mini \
125
+ --schema '{"type":"object","properties":{"fruits":{"type":"array","items":{"type":"string"}}},"required":["fruits"],"additionalProperties":false}'
126
+
127
+ # Tool calling
128
+ openrouter chat "What is 2+2?" -m openai/gpt-4o-mini \
129
+ --tool '{"name":"add","parameters":{"type":"object","properties":{"a":{"type":"number"},"b":{"type":"number"}},"required":["a","b"]}}' \
130
+ --tool-choice required --raw
131
+
132
+ # Reasoning effort
133
+ openrouter chat "tricky question" -m anthropic/claude-sonnet-4.5 --reasoning high
134
+
135
+ # Provider routing / fallback models
136
+ openrouter chat "..." -m primary/model --models fallback1/m,fallback2/m
137
+ openrouter chat "..." -m anthropic/claude-sonnet-4.5 --provider '{"order":["Google","Anthropic"]}'
138
+
139
+ # Interactive REPL
140
+ openrouter chat -i -m openrouter/auto
141
+ # Inside the REPL: /model <id>, /reset, /exit
142
+
143
+ # Anthropic-format and OpenAI Responses API are also available
144
+ openrouter messages "..." -m anthropic/claude-sonnet-4.5
145
+ openrouter responses "..." -m openai/gpt-4o-mini
146
+
147
+ # Embeddings, rerank, TTS, video
148
+ openrouter embed -m openai/text-embedding-3-small "hello" "world"
149
+ openrouter rerank -m cohere/rerank-v3.5 --query "italian food" -d pizza -d sushi -d pasta
150
+ openrouter speech "Hello there" -m elevenlabs/eleven-turbo-v2 --voice alloy -o out.mp3
151
+ openrouter video create "a sunset over mountains" -m google/veo-3
152
+ openrouter video wait <jobId> && openrouter video download <jobId> -o out.mp4
153
+ ```
154
+
155
+ ### Discovery & pricing
156
+
157
+ ```bash
158
+ # Browse / filter / sort the catalog
159
+ openrouter models # all (~370)
160
+ openrouter models --filter sonnet --sort prompt # cheapest first
161
+ openrouter models --free # only :free models
162
+ openrouter models --output-modalities image # image-output models
163
+ openrouter models --supported tools # filter by capability
164
+
165
+ # Full detail for one model: pricing breakdown, architecture, supported params
166
+ openrouter models show anthropic/claude-sonnet-4.5
167
+
168
+ # Compare provider variants for one model — find the best one
169
+ openrouter models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best
170
+ openrouter models endpoints openai/gpt-4o-mini --sort latency
171
+ openrouter models endpoints openai/gpt-4o-mini --sort prompt
172
+
173
+ # Supporting metadata
174
+ openrouter providers # all providers
175
+ openrouter embed models # embedding models
176
+ openrouter video models # video gen models
177
+ openrouter zdr # ZDR-eligible endpoints
178
+ ```
179
+
180
+ ### Account / spend / runs
181
+
182
+ ```bash
183
+ openrouter credits # total balance + total usage
184
+ openrouter whoami # label, daily/weekly/monthly usage, rate limit
185
+ openrouter generation gen-1234567890 # full per-request metadata + cost
186
+ openrouter generation gen-1234567890 --content # + the input/output content
187
+
188
+ # Activity (management key required) — daily aggregates per endpoint
189
+ openrouter activity --date 2026-04-28
190
+ openrouter activity --api-key-hash <hash>
191
+ ```
192
+
193
+ NOTE: `activity` only covers **completed UTC days** in the last 30 days.
194
+ Today's data isn't queryable until tomorrow. There's no per-request log
195
+ endpoint — the only way to inspect a specific in-flight request is by
196
+ `generation <id>` if you saved the id at call time.
197
+
198
+ `generation` lookups have a ~30-second propagation delay after the request
199
+ completes.
200
+
201
+ ### Key management (management key required)
202
+
203
+ ```bash
204
+ openrouter keys list
205
+ openrouter keys create "agent key" --limit 25 --limit-reset monthly
206
+ openrouter keys get <hash>
207
+ openrouter keys update <hash> --name "renamed" --limit 50
208
+ openrouter keys update <hash> --disabled
209
+ openrouter keys delete <hash>
210
+ ```
211
+
212
+ The full `sk-or-v1-...` secret is returned **only once** in the `create`
213
+ response — capture it then.
214
+
215
+ ### Guardrails / workspaces / org
216
+
217
+ ```bash
218
+ openrouter guardrails list
219
+ openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-zdr
220
+ openrouter guardrails update <id> --limit-usd 10 --reset-interval daily
221
+ openrouter guardrails assign-key <id> <key-hash>
222
+ openrouter guardrails delete <id>
223
+
224
+ openrouter workspaces list
225
+ openrouter workspaces create "staging" --slug staging --default-text-model openai/gpt-4o-mini
226
+ openrouter workspaces add-members <id|slug> <user_id> [<user_id>...]
227
+ openrouter workspaces delete <id|slug>
228
+
229
+ openrouter org members
230
+ ```
231
+
232
+ ### Raw escape hatch
233
+
234
+ For any endpoint that doesn't have a first-class subcommand yet (or new
235
+ endpoints OpenRouter ships):
236
+
237
+ ```bash
238
+ openrouter request GET /credits
239
+ openrouter request POST /chat/completions --body @body.json
240
+ openrouter request POST /chat/completions --body - < body.json # stdin
241
+ openrouter request GET /models --query category=programming --query supported_parameters=tools
242
+ openrouter request POST /audio/speech --body @speech.json --binary out.mp3
243
+ openrouter request GET /key --header "X-Custom: value"
244
+ ```
245
+
246
+ ## Patterns for agents
247
+
248
+ ### Pipe to jq
249
+
250
+ ```bash
251
+ openrouter --json models --filter sonnet | jq -r '.data[].id'
252
+ openrouter --json chat "Say hi" -m openrouter/auto | jq -r '.choices[0].message.content'
253
+ openrouter --json credits | jq '.data.total_credits - .data.total_usage'
254
+ ```
255
+
256
+ ### Fail fast
257
+
258
+ ```bash
259
+ if ! openrouter --json chat "..." -m model > /tmp/r.json; then
260
+ echo "API call failed (exit $?)" >&2
261
+ exit 1
262
+ fi
263
+ ```
264
+
265
+ ### Save the gen id for later audit
266
+
267
+ ```bash
268
+ out=$(openrouter --json chat "..." -m openai/gpt-4o-mini)
269
+ gen_id=$(echo "$out" | jq -r '.id')
270
+ echo "$out" | jq -r '.choices[0].message.content'
271
+ # ...later, after ~30s...
272
+ openrouter generation "$gen_id" --content
273
+ ```
274
+
275
+ ### Pick the best provider variant before locking it in
276
+
277
+ ```bash
278
+ # Cheapest provider for a given model
279
+ openrouter --json models endpoints openai/gpt-4o-mini --sort prompt --best \
280
+ | jq -r '.data.endpoints[0] | "\(.provider_name): $\(.pricing.prompt)/tok"'
281
+
282
+ # Highest throughput provider
283
+ openrouter --json models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best \
284
+ | jq -r '.data.endpoints[0] | "\(.provider_name) @ \(.throughput_last_30m.p50) tok/s"'
285
+ ```
286
+
287
+ ### Check spend on a specific key
288
+
289
+ ```bash
290
+ openrouter --json keys get <hash> | jq '.data | {usage, usage_daily, limit_remaining}'
291
+ ```
292
+
293
+ ## Pitfalls and gotchas
294
+
295
+ - **`--json` must come BEFORE the subcommand** for the global pre-parser to
296
+ pick it up reliably. `openrouter --json chat ...` (correct), `openrouter
297
+ chat ... --json` also works but is slightly less robust with positionals.
298
+ - **Generation lookups have ~30s lag.** Don't poll faster than that — you'll
299
+ just get 404.
300
+ - **Activity is daily-aggregated and only covers completed UTC days.** A
301
+ query for today returns `400 Date must be within the last 30 (completed)
302
+ UTC days`.
303
+ - **Speech (`/audio/speech`) currently has limited model availability** on
304
+ OpenRouter. The CLI sends valid requests; the API may return `Model X
305
+ does not exist` for many model ids.
306
+ - **`auth-code` requires a Clerk session JWT** despite the OpenAPI spec
307
+ suggesting any management key works. Treat that subcommand as best-effort
308
+ until OpenRouter aligns server behavior with the spec.
309
+ - **`rate_limit` field is deprecated** by OpenRouter and may show as
310
+ `-1 req / 10s`. Surfaced verbatim.
311
+ - **Management keys cannot do inference.** If you only have a management key
312
+ saved and run `openrouter chat`, OpenRouter rejects with `401 User not
313
+ found`. Save a user key too.
314
+
315
+ ## Configuration reference
316
+
317
+ | flag | env | default |
318
+ | --- | --- | --- |
319
+ | `-k, --key` | `OPENROUTER_API_KEY` / `OPENROUTER_MANAGEMENT_KEY` | from config |
320
+ | `--base-url` | `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` |
321
+ | `--referer` | `OPENROUTER_REFERER` | `https://github.com/openrouter-cli` |
322
+ | `--title` | `OPENROUTER_TITLE` | `openrouter-cli` |
323
+ | `--json` | — | off |
324
+ | `-q, --quiet` | — | off |
325
+ | — | `NO_COLOR` | colors on in TTY |
326
+ | — | `OPENROUTER_DEBUG=1` | off |
327
+
328
+ Config file location: `$XDG_CONFIG_HOME/openrouter/config.json` (defaults to
329
+ `~/.config/openrouter/config.json`). Created with `0700` dir / `0600` file.
330
+
331
+ ## Help
332
+
333
+ Every command has its own `--help`:
334
+
335
+ ```bash
336
+ openrouter --help
337
+ openrouter chat --help
338
+ openrouter models --help
339
+ openrouter keys --help
340
+ openrouter guardrails --help
341
+ # ...etc
342
+ ```
343
+
344
+ Repository: <https://github.com/aaronjmars/openroutercli>
345
+ OpenRouter docs: <https://openrouter.ai/docs>
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+ import { run } from '../src/cli.js';
3
+
4
+ run(process.argv.slice(2)).catch((err) => {
5
+ const msg = err && err.message ? err.message : String(err);
6
+ process.stderr.write(`error: ${msg}\n`);
7
+ if (process.env.OPENROUTER_DEBUG && err && err.stack) {
8
+ process.stderr.write(err.stack + '\n');
9
+ }
10
+ process.exit(err && typeof err.exitCode === 'number' ? err.exitCode : 1);
11
+ });
package/keys.png ADDED
Binary file
Binary file
package/package.json ADDED
@@ -0,0 +1,55 @@
1
+ {
2
+ "name": "@aaronjmars/openroutercli",
3
+ "version": "0.1.2",
4
+ "description": "Command-line interface for the OpenRouter API. Built for humans and LLM agents.",
5
+ "type": "module",
6
+ "bin": {
7
+ "openrouter": "./bin/openrouter.js",
8
+ "or": "./bin/openrouter.js"
9
+ },
10
+ "engines": {
11
+ "node": ">=20"
12
+ },
13
+ "files": [
14
+ "bin",
15
+ "src",
16
+ "README.md",
17
+ "LICENSE",
18
+ "SKILL.md",
19
+ "openrouter-logo.jpeg",
20
+ "keys.png"
21
+ ],
22
+ "keywords": [
23
+ "openrouter",
24
+ "cli",
25
+ "llm",
26
+ "ai",
27
+ "chat",
28
+ "agent",
29
+ "claude",
30
+ "gpt",
31
+ "openai",
32
+ "anthropic",
33
+ "embeddings",
34
+ "tts",
35
+ "rerank",
36
+ "oauth"
37
+ ],
38
+ "license": "MIT",
39
+ "author": "aaronjmars",
40
+ "homepage": "https://github.com/aaronjmars/openroutercli#readme",
41
+ "repository": {
42
+ "type": "git",
43
+ "url": "git+https://github.com/aaronjmars/openroutercli.git"
44
+ },
45
+ "bugs": {
46
+ "url": "https://github.com/aaronjmars/openroutercli/issues"
47
+ },
48
+ "preferGlobal": true,
49
+ "publishConfig": {
50
+ "access": "public"
51
+ },
52
+ "scripts": {
53
+ "start": "node bin/openrouter.js"
54
+ }
55
+ }