@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 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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aaronjmars/openroutercli",
3
- "version": "0.7.0",
3
+ "version": "0.9.0",
4
4
  "description": "Command-line interface for the OpenRouter API. Built for humans and LLM agents.",
5
5
  "type": "module",
6
6
  "bin": {
package/src/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
+ }
@@ -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)) {