@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 +6 -2
- package/SKILL.md +6 -2
- package/package.json +1 -1
- package/src/cli.js +4 -0
- package/src/commands/extractions.js +129 -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
|
---
|
|
@@ -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
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
|
+
}
|