@aaronjmars/openroutercli 0.7.0 → 0.8.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
  ---
@@ -81,7 +81,7 @@ and run `openrouter login --management`.
81
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. |
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. |
@@ -141,6 +141,9 @@ openrouter models user --order newest
141
141
  openrouter models user --client codex # only models a coding harness offers
142
142
  openrouter models show anthropic/claude-sonnet-4.5
143
143
  openrouter models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best
144
+
145
+ # Response cache: identical repeats are free (X-OpenRouter-Cache)
146
+ openrouter chat "fixed prompt" -m openrouter/auto --response-cache
144
147
  openrouter providers
145
148
  # Spend / runs
146
149
  openrouter credits
@@ -211,6 +214,7 @@ Endpoint coverage map:
211
214
  | `GET/POST/PATCH/DELETE /byok[/{id}]` | `openrouter byok ...` |
212
215
  | `GET /presets[/{slug}]` + versions, `POST /presets/{slug}/{chat/completions,messages,responses}` | `openrouter presets {list,get,versions,create}` |
213
216
  | `POST /systemone` (and `POST /api/alpha/decisions` with `--alpha`) | `openrouter systemone` / `openrouter decisions` |
217
+ | `POST /api/alpha/extractions` | `openrouter extract` / `openrouter extractions` |
214
218
  | `GET /containers/{id}/files[/{file}]` + content/promote | `openrouter containers ...` |
215
219
  | `GET /organization/members` | `openrouter org members` |
216
220
  | `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 \
@@ -259,6 +261,8 @@ openrouter analytics meta
259
261
  openrouter decisions --model typesafe/jev-1.13 --state '...' --questions @questions.json # alias: systemone
260
262
  openrouter decisions --model <vision-decider> --state '...' --image ./chart.png --questions @q.json
261
263
  openrouter decisions --model typesafe/jev-1.14 --state '... image: logo' --assets '{"logo":"./logo.png"}' --questions @q.json
264
+ openrouter extract -m scaledown/extract --state '...' --fields '{"invoice":{"type":"text"}}' # alpha; alias: extractions
265
+ openrouter extract -m scaledown/extract --assets '{"doc":"./invoice.pdf"}' --fields @fields.json # file-only (state = asset key)
262
266
  openrouter containers list <container-id>
263
267
 
264
268
  # 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.8.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
+ }