@aaronjmars/openroutercli 0.7.0 → 0.9.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 +8 -3
- package/SKILL.md +8 -3
- package/package.json +1 -1
- package/src/cli.js +4 -0
- package/src/commands/extractions.js +129 -0
- package/src/commands/models.js +11 -0
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
|
|
19
19
|
<p align="center">
|
|
20
20
|
<strong>Every OpenRouter endpoint, on the command line - for humans and LLM agents</strong><br>
|
|
21
|
-
Browser-based OAuth login, inference, discovery, analytics, benchmarks, public datasets, Decisions, container files, account management, and a raw <code>request</code> escape hatch. <code>--json</code> on every command. Zero npm dependencies.
|
|
21
|
+
Browser-based OAuth login, inference, discovery, analytics, benchmarks, public datasets, Decisions, Extractions, container files, account management, and a raw <code>request</code> escape hatch. <code>--json</code> on every command. Zero npm dependencies.
|
|
22
22
|
</p>
|
|
23
23
|
|
|
24
24
|
---
|
|
@@ -78,10 +78,10 @@ and run `openrouter login --management`.
|
|
|
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
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>`. |
|
|
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
|
+
| **Model discovery with detail** | `models list` (filter, sort by price/context, `--endpoints` by API path served), `models show <id>` (full pricing breakdown - prompt, completion, cache r/w, reasoning, image, web search), `models endpoints <id> --sort throughput\|latency\|prompt\|completion\|uptime --best` for choosing the right provider variant. |
|
|
82
82
|
| **Benchmarks + rankings** | `benchmarks`, `classifications`, and `datasets {apps,daily,session-cost}` expose OpenRouter's current public benchmark and usage datasets. |
|
|
83
83
|
| **Management analytics** | `analytics meta` discovers fields; `analytics query` runs metrics/dimensions/time-range queries with a management key. |
|
|
84
|
-
| **Structured decisions** | `decisions` (alias `systemone`) calls System One for typed choice, score, and yes/no outputs, with optional image inputs (`--image`) and named image assets (`--assets`). |
|
|
84
|
+
| **Structured decisions** | `decisions` (alias `systemone`) calls System One for typed choice, score, and yes/no outputs, with optional image inputs (`--image`) and named image assets (`--assets`). `extract` (alias `extractions`, alpha) pulls typed fields (text, number, date, list, estimate, forecast...) out of text or attached image/PDF assets. |
|
|
85
85
|
| **Server tools catalog** | `tools list` / `tools get <name>` - every OpenRouter-run tool (web search, fetch, datetime, ...) with params, engines and pricing. |
|
|
86
86
|
| **Hosted shell files** | `containers {list,get,download,promote}` retrieves and promotes files produced by OpenRouter's hosted shell tools. |
|
|
87
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. |
|
|
@@ -139,8 +139,12 @@ openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
|
|
|
139
139
|
openrouter models --filter claude --sort prompt
|
|
140
140
|
openrouter models user --order newest
|
|
141
141
|
openrouter models user --client codex # only models a coding harness offers
|
|
142
|
+
openrouter models --endpoints /api/alpha/extractions # models served on an API path
|
|
142
143
|
openrouter models show anthropic/claude-sonnet-4.5
|
|
143
144
|
openrouter models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best
|
|
145
|
+
|
|
146
|
+
# Response cache: identical repeats are free (X-OpenRouter-Cache)
|
|
147
|
+
openrouter chat "fixed prompt" -m openrouter/auto --response-cache
|
|
144
148
|
openrouter providers
|
|
145
149
|
# Spend / runs
|
|
146
150
|
openrouter credits
|
|
@@ -211,6 +215,7 @@ Endpoint coverage map:
|
|
|
211
215
|
| `GET/POST/PATCH/DELETE /byok[/{id}]` | `openrouter byok ...` |
|
|
212
216
|
| `GET /presets[/{slug}]` + versions, `POST /presets/{slug}/{chat/completions,messages,responses}` | `openrouter presets {list,get,versions,create}` |
|
|
213
217
|
| `POST /systemone` (and `POST /api/alpha/decisions` with `--alpha`) | `openrouter systemone` / `openrouter decisions` |
|
|
218
|
+
| `POST /api/alpha/extractions` | `openrouter extract` / `openrouter extractions` |
|
|
214
219
|
| `GET /containers/{id}/files[/{file}]` + content/promote | `openrouter containers ...` |
|
|
215
220
|
| `GET /organization/members` | `openrouter org members` |
|
|
216
221
|
| `GET/PATCH /organization/settings` | `openrouter org settings` |
|
package/SKILL.md
CHANGED
|
@@ -29,7 +29,7 @@ TRIGGER when the user asks to:
|
|
|
29
29
|
- browse server tools (web search, fetch, datetime, ...) and use them in chat
|
|
30
30
|
- set workspace budgets or send traces to an observability destination
|
|
31
31
|
- query management analytics
|
|
32
|
-
- submit structured Decisions requests or retrieve hosted-container files
|
|
32
|
+
- submit structured Decisions requests, extract typed fields from text or PDFs, or retrieve hosted-container files
|
|
33
33
|
- log in to OpenRouter from a fresh machine (OAuth PKCE in the browser)
|
|
34
34
|
|
|
35
35
|
SKIP when the user is already using the OpenAI / Anthropic / Cohere SDKs
|
|
@@ -82,7 +82,7 @@ command automatically.
|
|
|
82
82
|
|
|
83
83
|
| Slot | Used by | How to obtain |
|
|
84
84
|
| --- | --- | --- |
|
|
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 |
|
|
85
|
+
| **User key** | `chat`, `messages`, `responses`, `embed`, `rerank`, `speech`, `transcribe`, `image`, `video`, `files`, `presets`, `generation`, `credits`, `whoami`, `benchmarks`, `classifications`, `datasets`, `decisions`, `extract`, `containers`, `batches`, `tools` | OAuth (`openrouter login`) or paste from dashboard |
|
|
86
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`. |
|
|
87
87
|
|
|
88
88
|
You can store both - they live side by side in the config file. `--key sk-or-...`
|
|
@@ -166,6 +166,8 @@ openrouter chat "answer from the doc" -m anthropic/claude-sonnet-4.5 -s "$(cat b
|
|
|
166
166
|
# OpenAI explicit caching (GPT-5.6+): 30m or 12h TTL, marks the system prompt (else the prompt);
|
|
167
167
|
# works on chat and responses, 12h writes bill at a higher rate
|
|
168
168
|
openrouter chat "answer from the doc" -m openai/gpt-5.6 -s "$(cat big-context.txt)" --cache-ttl 12h
|
|
169
|
+
# Response cache (X-OpenRouter-Cache): free repeat responses for identical requests
|
|
170
|
+
openrouter chat "fixed prompt" -m openrouter/auto --response-cache
|
|
169
171
|
|
|
170
172
|
# Tracing, sessions, priority: works on chat / messages / responses
|
|
171
173
|
openrouter chat "..." -m openai/gpt-4o-mini --session-id run-42 --user u_123 \
|
|
@@ -241,8 +243,9 @@ openrouter models --output-modalities image # image-OUTPUT models
|
|
|
241
243
|
openrouter models user --order newest # account-filtered models, server-side sort
|
|
242
244
|
openrouter models user --client codex # models the named harness offers (claude_code|claude_desktop|codex); honors --harness-models guardrails
|
|
243
245
|
openrouter models --supported tools # filter by capability
|
|
246
|
+
openrouter models --endpoints /api/v1/messages # only models served on these API paths (csv, all must match)
|
|
244
247
|
# Full detail for one model: pricing breakdown, architecture, supported params,
|
|
245
|
-
# reasoning config, supported voices
|
|
248
|
+
# API paths it is served on, reasoning config, supported voices
|
|
246
249
|
openrouter models show anthropic/claude-sonnet-4.5
|
|
247
250
|
|
|
248
251
|
# Supported request parameters (undocumented endpoint, may change)
|
|
@@ -259,6 +262,8 @@ openrouter analytics meta
|
|
|
259
262
|
openrouter decisions --model typesafe/jev-1.13 --state '...' --questions @questions.json # alias: systemone
|
|
260
263
|
openrouter decisions --model <vision-decider> --state '...' --image ./chart.png --questions @q.json
|
|
261
264
|
openrouter decisions --model typesafe/jev-1.14 --state '... image: logo' --assets '{"logo":"./logo.png"}' --questions @q.json
|
|
265
|
+
openrouter extract -m scaledown/extract --state '...' --fields '{"invoice":{"type":"text"}}' # alpha; alias: extractions
|
|
266
|
+
openrouter extract -m scaledown/extract --assets '{"doc":"./invoice.pdf"}' --fields @fields.json # file-only (state = asset key)
|
|
262
267
|
openrouter containers list <container-id>
|
|
263
268
|
|
|
264
269
|
# Supporting metadata
|
package/package.json
CHANGED
package/src/cli.js
CHANGED
|
@@ -26,6 +26,7 @@ import {
|
|
|
26
26
|
datasetsCommand,
|
|
27
27
|
} from "./commands/data.js";
|
|
28
28
|
import { decisionsCommand, systemoneCommand } from "./commands/decisions.js";
|
|
29
|
+
import { extractionsCommand } from "./commands/extractions.js";
|
|
29
30
|
import { batchesCommand } from "./commands/batches.js";
|
|
30
31
|
import { toolsCommand } from "./commands/tools.js";
|
|
31
32
|
import { observabilityCommand } from "./commands/observability.js";
|
|
@@ -76,6 +77,8 @@ const COMMANDS = {
|
|
|
76
77
|
decisions: decisionsCommand,
|
|
77
78
|
decision: decisionsCommand,
|
|
78
79
|
systemone: systemoneCommand,
|
|
80
|
+
extract: extractionsCommand,
|
|
81
|
+
extractions: extractionsCommand,
|
|
79
82
|
batches: batchesCommand,
|
|
80
83
|
batch: batchesCommand,
|
|
81
84
|
tools: toolsCommand,
|
|
@@ -129,6 +132,7 @@ Discovery:
|
|
|
129
132
|
classifications [options] Task classification market share
|
|
130
133
|
datasets <sub> Public usage datasets
|
|
131
134
|
systemone System One structured decisions (alias: decisions)
|
|
135
|
+
extract Typed field extraction, alpha (alias: extractions)
|
|
132
136
|
containers <sub> Hosted shell output files
|
|
133
137
|
files <sub> Workspace files
|
|
134
138
|
zdr Preview Zero-Data-Retention impact
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
import { parseArgs, authFromValues, loadJson } from "../args.js";
|
|
2
|
+
import { api } from "../api.js";
|
|
3
|
+
import { mediaUrl } from "../media.js";
|
|
4
|
+
import { printResult } from "../output.js";
|
|
5
|
+
|
|
6
|
+
const HELP = `Usage: openrouter extract [options]
|
|
7
|
+
openrouter extractions [options] (same command)
|
|
8
|
+
|
|
9
|
+
Submit an Extractions request (alpha, POST /api/alpha/extractions): a state
|
|
10
|
+
string plus typed fields to extract, compute, estimate or forecast, answered
|
|
11
|
+
by an extraction-style System One model such as scaledown/extract. The
|
|
12
|
+
request shape is alpha and may change.
|
|
13
|
+
|
|
14
|
+
Field types: text, number, date, time, datetime, duration, list, estimate,
|
|
15
|
+
forecast. Which types a model answers is model-specific (400 otherwise):
|
|
16
|
+
scaledown/extract returns text spans only and takes no --reference-date.
|
|
17
|
+
With one asset and no --state, the request is file-only (state = its key).
|
|
18
|
+
|
|
19
|
+
Options:
|
|
20
|
+
-m, --model <id> Model id (required without --body)
|
|
21
|
+
--state <text|@file> Text to read from (may be empty with --assets)
|
|
22
|
+
--fields <json|@file> Fields object: {"name": {"type": "text", ...}}
|
|
23
|
+
--assets <json|@file> Named files referenced in state or field
|
|
24
|
+
instructions: {"ref-name": "<local path>"}
|
|
25
|
+
(png/jpg/jpeg as image, pdf as document).
|
|
26
|
+
Every name must be referenced.
|
|
27
|
+
--reference-date <YYYY-MM-DD>
|
|
28
|
+
Anchors dates written without a year
|
|
29
|
+
--body <json|@file> Fully-formed request body
|
|
30
|
+
--extra <json> Extra fields merged into the request
|
|
31
|
+
|
|
32
|
+
Example:
|
|
33
|
+
openrouter extract -m scaledown/extract \\
|
|
34
|
+
--state "Invoice INV-2291 issued 2026-09-02, net 30. Total \\$1080." \\
|
|
35
|
+
--fields '{"invoice":{"type":"text"},"total":{"type":"text"}}'
|
|
36
|
+
openrouter extract -m scaledown/extract --assets '{"doc":"./invoice.pdf"}' \\
|
|
37
|
+
--fields '{"invoice":{"type":"text"}}'
|
|
38
|
+
`;
|
|
39
|
+
|
|
40
|
+
const ASSET_TYPES = {
|
|
41
|
+
"image/png": ["image", "png"],
|
|
42
|
+
"image/jpeg": ["image", "jpeg"],
|
|
43
|
+
"application/pdf": ["document", "pdf"],
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
async function loadState(value) {
|
|
47
|
+
if (value == null) return undefined;
|
|
48
|
+
if (!value.startsWith("@")) return value;
|
|
49
|
+
const { readFile } = await import("node:fs/promises");
|
|
50
|
+
return readFile(value.slice(1), "utf8");
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
async function assetFromPath(name, src) {
|
|
54
|
+
const lower = src.toLowerCase().split(/[?#]/)[0];
|
|
55
|
+
if (/^https?:\/\//i.test(src)) {
|
|
56
|
+
throw new Error(
|
|
57
|
+
`--assets "${name}": the Extractions API only accepts uploaded files. Give a local file (png/jpg/jpeg/pdf), not a URL.`,
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
let mime;
|
|
61
|
+
let b64;
|
|
62
|
+
if (lower.endsWith(".pdf")) {
|
|
63
|
+
const { readFile } = await import("node:fs/promises");
|
|
64
|
+
mime = "application/pdf";
|
|
65
|
+
b64 = (await readFile(src)).toString("base64");
|
|
66
|
+
} else {
|
|
67
|
+
const url = await mediaUrl(src);
|
|
68
|
+
[mime, b64] = url.slice(5).split(";base64,");
|
|
69
|
+
}
|
|
70
|
+
const kind = ASSET_TYPES[mime];
|
|
71
|
+
if (!kind) throw new Error(`--assets "${name}": expected png/jpg/jpeg/pdf, got ${mime}`);
|
|
72
|
+
return { type: kind[0], format: kind[1], data_base64: b64 };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export async function extractionsCommand(argv) {
|
|
76
|
+
const { values } = parseArgs(argv, {
|
|
77
|
+
model: { type: "string", short: "m" },
|
|
78
|
+
state: { type: "string" },
|
|
79
|
+
fields: { type: "string" },
|
|
80
|
+
assets: { type: "string" },
|
|
81
|
+
"reference-date": { type: "string" },
|
|
82
|
+
body: { type: "string" },
|
|
83
|
+
extra: { type: "string" },
|
|
84
|
+
});
|
|
85
|
+
if (values.help) {
|
|
86
|
+
process.stdout.write(HELP);
|
|
87
|
+
return 0;
|
|
88
|
+
}
|
|
89
|
+
let body = values.body ? await loadJson(values.body, "--body") : null;
|
|
90
|
+
if (!body) {
|
|
91
|
+
if (!values.model) throw new Error("--model is required");
|
|
92
|
+
if (values.state === undefined && values.assets === undefined) {
|
|
93
|
+
throw new Error("--state is required (or --assets for a file-only request)");
|
|
94
|
+
}
|
|
95
|
+
if (!values.fields) throw new Error("--fields is required");
|
|
96
|
+
body = {
|
|
97
|
+
model: values.model,
|
|
98
|
+
state: (await loadState(values.state)) ?? "",
|
|
99
|
+
fields: await loadJson(values.fields, "--fields"),
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
if (values["reference-date"] !== undefined) {
|
|
103
|
+
if (!/^\d{4}-\d{2}-\d{2}$/.test(values["reference-date"])) {
|
|
104
|
+
throw new Error("--reference-date must be YYYY-MM-DD");
|
|
105
|
+
}
|
|
106
|
+
body.reference_date = values["reference-date"];
|
|
107
|
+
}
|
|
108
|
+
if (values.assets !== undefined) {
|
|
109
|
+
const assets = await loadJson(values.assets, "--assets");
|
|
110
|
+
if (!assets || typeof assets !== "object" || Array.isArray(assets)) {
|
|
111
|
+
throw new Error('--assets must be a JSON object like {"ref": "<path>"}');
|
|
112
|
+
}
|
|
113
|
+
body.assets = {};
|
|
114
|
+
for (const [name, src] of Object.entries(assets)) {
|
|
115
|
+
body.assets[name] = await assetFromPath(name, src);
|
|
116
|
+
}
|
|
117
|
+
// File-only request: a state that is exactly the sole asset's key.
|
|
118
|
+
const names = Object.keys(body.assets);
|
|
119
|
+
if (!values.body && values.state === undefined && names.length === 1) body.state = names[0];
|
|
120
|
+
}
|
|
121
|
+
if (values.extra) Object.assign(body, await loadJson(values.extra, "--extra"));
|
|
122
|
+
const data = await api("POST", "/extractions", {
|
|
123
|
+
rootPath: "/api/alpha",
|
|
124
|
+
auth: authFromValues(values),
|
|
125
|
+
body,
|
|
126
|
+
});
|
|
127
|
+
printResult(data);
|
|
128
|
+
return 0;
|
|
129
|
+
}
|
package/src/commands/models.js
CHANGED
|
@@ -50,6 +50,9 @@ Options for list:
|
|
|
50
50
|
--providers <csv> Hosting provider names
|
|
51
51
|
--distillable <true|false> Filter by distillation capability
|
|
52
52
|
--zdr Only models with ZDR endpoints
|
|
53
|
+
--endpoints <csv> Only models served on every listed API path, e.g.
|
|
54
|
+
/api/v1/messages or /api/alpha/extractions
|
|
55
|
+
(without --output-modalities: every modality)
|
|
53
56
|
--region <region> Only models with endpoints in a data region: eu | us
|
|
54
57
|
--order <sort> Server-side sort: most-popular|newest|top-weekly|
|
|
55
58
|
pricing-low-to-high|pricing-high-to-low|
|
|
@@ -96,6 +99,7 @@ function listQuery(values) {
|
|
|
96
99
|
if (values.distillable !== undefined) query.distillable = values.distillable;
|
|
97
100
|
if (values.zdr) query.zdr = "true";
|
|
98
101
|
if (values.region) query.region = values.region;
|
|
102
|
+
if (values.endpoints) query.endpoints = values.endpoints;
|
|
99
103
|
return query;
|
|
100
104
|
}
|
|
101
105
|
|
|
@@ -117,6 +121,7 @@ const LIST_OPTIONS = {
|
|
|
117
121
|
distillable: { type: "string" },
|
|
118
122
|
zdr: { type: "boolean" },
|
|
119
123
|
region: { type: "string" },
|
|
124
|
+
endpoints: { type: "string" },
|
|
120
125
|
"min-age-days": { type: "string" },
|
|
121
126
|
"max-age-days": { type: "string" },
|
|
122
127
|
"min-intelligence-index": { type: "string" },
|
|
@@ -207,6 +212,12 @@ function renderModelDetail(m) {
|
|
|
207
212
|
outln(" " + ((m.supported_parameters || []).join(", ") || "-"));
|
|
208
213
|
outln("");
|
|
209
214
|
|
|
215
|
+
if (m.endpoints && m.endpoints.length) {
|
|
216
|
+
outln(c.bold("served on"));
|
|
217
|
+
outln(" " + m.endpoints.join(", "));
|
|
218
|
+
outln("");
|
|
219
|
+
}
|
|
220
|
+
|
|
210
221
|
if (m.reasoning && Object.keys(m.reasoning).length) {
|
|
211
222
|
outln(c.bold("reasoning"));
|
|
212
223
|
for (const [k, v] of Object.entries(m.reasoning)) {
|