@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 +21 -0
- package/README.md +212 -0
- package/SKILL.md +345 -0
- package/bin/openrouter.js +11 -0
- package/keys.png +0 -0
- package/openrouter-logo.jpeg +0 -0
- package/package.json +55 -0
- package/src/api.js +121 -0
- package/src/args.js +30 -0
- package/src/cli.js +187 -0
- package/src/commands/account.js +139 -0
- package/src/commands/chat.js +316 -0
- package/src/commands/embed.js +95 -0
- package/src/commands/generation.js +30 -0
- package/src/commands/guardrails.js +226 -0
- package/src/commands/keys.js +147 -0
- package/src/commands/login.js +307 -0
- package/src/commands/messages.js +172 -0
- package/src/commands/misc.js +104 -0
- package/src/commands/models.js +373 -0
- package/src/commands/request.js +100 -0
- package/src/commands/rerank.js +74 -0
- package/src/commands/speech.js +68 -0
- package/src/commands/video.js +128 -0
- package/src/commands/workspaces.js +147 -0
- package/src/config.js +80 -0
- package/src/output.js +84 -0
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
|
+
[](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
|
+
}
|