@aaronjmars/openroutercli 0.9.0 → 0.11.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
@@ -85,7 +85,7 @@ and run `openrouter login --management`.
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. |
88
- | **Account + governance** | `keys`, `guardrails` (allow/deny lists, USD limits, ZDR, data regions, content filters), `workspaces` (defaults, members, budgets, disabled tools), `observability` destinations (Langfuse, Datadog, ...), `org members` / `org settings`, `auth-code` to mint claim links. All require a management key. |
88
+ | **Account + governance** | `keys`, `guardrails` (allow/deny lists, USD limits, ZDR, data regions, content filters, typed budget / model-availability / moderation policies), `workspaces` (defaults, members, budgets, disabled tools), `observability` destinations (Langfuse, Datadog, ...), `org members` / `org settings`, `auth-code` to mint claim links. All require a management key. |
89
89
  | **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. |
90
90
  | **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. |
91
91
  | **Zero npm dependencies** | Pure Node 20+ - built-in `fetch`, `parseArgs`, `crypto`. Cold install in seconds. Easy to audit. |
@@ -131,6 +131,10 @@ openrouter chat "What is 2+2?" -m openai/gpt-4o-mini \
131
131
  openrouter tools list
132
132
  openrouter chat "What's new today?" -m openai/gpt-4o-mini --server-tool web_search
133
133
 
134
+ # Images: animated GIF output and markup-guided edits (gpt-image-2.6)
135
+ openrouter image "a spinning coin" -m openai/gpt-image-2.6-flare --format gif --frames 8 --frame-ms 100 -o coin.gif
136
+ openrouter image "put a hat here" -m openai/gpt-image-2.6-flare --image ./cat.png --markup ./circle.png
137
+
134
138
  # Batches at about half price
135
139
  openrouter batches create --endpoint chat -m openai/gpt-4o-mini --file reqs.jsonl --callback-url https://example.com/webhook
136
140
  openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
@@ -156,6 +160,8 @@ openrouter activity --date 2026-04-28 --api-key-hash <hash>
156
160
  openrouter keys create "agent-key" --limit 25 --limit-reset monthly
157
161
  openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-zdr
158
162
  openrouter guardrails update <id> --harness-models # harness clients see only first-party models
163
+ openrouter guardrails policies create "daily-10" --type budget --workspace <uuid> \
164
+ --config '{"limit_usd":10,"reset_interval":"daily","include_byok_in_budgets":false}'
159
165
  openrouter workspaces create "staging" --slug staging --default-text-model openai/gpt-4o-mini
160
166
  openrouter workspaces budgets set staging monthly --limit 100
161
167
  openrouter observability create "langfuse" --type langfuse --config @langfuse.json
@@ -210,6 +216,7 @@ Endpoint coverage map:
210
216
  | `POST /images`, `GET /images/models` | `openrouter image [models]` |
211
217
  | `GET/POST/PATCH/DELETE /keys[/{hash}]` | `openrouter keys {list,get,create,update,delete}` |
212
218
  | `GET/POST/PATCH/DELETE /guardrails[/{id}]` + assignments | `openrouter guardrails ...` |
219
+ | `GET/POST/PUT/DELETE /guardrails/policies/{budget,model-availability,moderation,account}[/{id}]` + `assignments/{api-keys,members}` | `openrouter guardrails policies ...` |
213
220
  | `GET/POST/PATCH/DELETE /workspaces[/{id}]` + members + budgets | `openrouter workspaces ...` |
214
221
  | `GET/POST/PATCH/DELETE /observability/destinations[/{id}]` | `openrouter observability ...` |
215
222
  | `GET/POST/PATCH/DELETE /byok[/{id}]` | `openrouter byok ...` |
package/SKILL.md CHANGED
@@ -222,6 +222,9 @@ openrouter transcribe ./talk.mp3 -m elevenlabs/scribe-v2 --keyterms OpenRouter,B
222
222
  # Image generation (writes image-0.png, ...): tier or exact size, reference images
223
223
  openrouter image "a red bike on a beach" -m google/gemini-2.5-flash-image -o bike.png
224
224
  openrouter image "same bike, at night" -m google/gemini-2.5-flash-image --image ./bike.png --resolution 2K
225
+ # Animated GIF (2-64 frames, 20-2000 ms each) and a markup overlay guiding an edit (openai/gpt-image-2.6-*)
226
+ openrouter image "a spinning coin" -m openai/gpt-image-2.6-flare --format gif --frames 8 --frame-ms 100 -o coin.gif
227
+ openrouter image "put a hat here" -m openai/gpt-image-2.6-flare --image ./cat.png --markup ./circle.png
225
228
 
226
229
  # Video jobs: frames, references, audio, extend
227
230
  openrouter video create "a sunset over mountains" -m google/veo-3 --resolution 1080p --audio
@@ -325,6 +328,20 @@ openrouter guardrails update <id> --allow-safety-retention-google --no-allow-saf
325
328
  openrouter guardrails update <id> --harness-models # codex/claude harnesses only see their vendor's models
326
329
  openrouter guardrails assign-key <id> <key-hash> # up to 500 hashes per call
327
330
 
331
+ # Typed policies (budget | model-availability | moderation); --workspace is required,
332
+ # --account works on workspace-wide policies instead
333
+ openrouter guardrails policies list --type budget --workspace <uuid>
334
+ openrouter guardrails policies list --account
335
+ openrouter guardrails policies get <id> --type moderation --workspace <uuid>
336
+ openrouter guardrails policies create "daily-10" --type budget --workspace <uuid> \
337
+ --config '{"limit_usd":10,"reset_interval":"daily","include_byok_in_budgets":false}'
338
+ openrouter guardrails policies update <id> --type model-availability --workspace <uuid> \
339
+ --name "eu-only" --config '{"allowed_data_regions":["europe"]}' # PUT: replaces name + config
340
+ openrouter guardrails policies assignment key <key-hash> --type budget --workspace <uuid>
341
+ openrouter guardrails policies assign member <user-id> <policy-id> --type budget --workspace <uuid> [--unassign]
342
+ # --unassign of the last explicit policy also opts the subject out of the workspace default;
343
+ # assign the default policy id again to undo that
344
+
328
345
  openrouter workspaces list
329
346
  openrouter workspaces create "staging" --slug staging --default-text-model openai/gpt-4o-mini
330
347
  openrouter workspaces update staging --disable-tools web_search --broadcast --io-logging-rate 0.1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aaronjmars/openroutercli",
3
- "version": "0.9.0",
3
+ "version": "0.11.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
@@ -140,7 +140,7 @@ Discovery:
140
140
  Management (require a management key):
141
141
  keys <sub> list / get / create / update / delete
142
142
  byok <sub> list / get / create / update / delete (provider integrations)
143
- guardrails <sub> list / get / create / update / delete / assignments
143
+ guardrails <sub> list / get / create / update / delete / assignments / policies
144
144
  workspaces <sub> list / get / create / update / delete / members / add-members /
145
145
  remove-members / budgets
146
146
  observability <sub> list / get / create / update / delete trace destinations. Alias: obs
@@ -8,6 +8,7 @@ import {
8
8
  } from "../args.js";
9
9
  import { api } from "../api.js";
10
10
  import { outln, printResult, table } from "../output.js";
11
+ import { policiesCommand } from "./policies.js";
11
12
 
12
13
  const HELP = `Usage: openrouter guardrails <subcommand> [options]
13
14
 
@@ -29,6 +30,9 @@ Subcommands:
29
30
  key-assignments <id> List key assignments for a guardrail
30
31
  member-assignments <id> List member assignments for a guardrail
31
32
  (both take --offset/--limit)
33
+ policies <sub> Typed policies (budget, model-availability,
34
+ moderation, workspace-wide) and per-key /
35
+ per-member assignments. See: guardrails policies --help
32
36
 
33
37
  create / update options:
34
38
  --name <name> (update only)
@@ -210,6 +214,8 @@ export async function guardrailsCommand(argv) {
210
214
  return sub ? 0 : 1;
211
215
  }
212
216
 
217
+ if (sub === "policies") return policiesCommand(rest);
218
+
213
219
  if (rest.includes("-h") || rest.includes("--help")) {
214
220
  process.stdout.write(HELP);
215
221
  return 0;
@@ -38,7 +38,12 @@ create options:
38
38
  --image <url|path> Reference image for image-to-image (repeatable, max 16);
39
39
  local files are sent as data URLs
40
40
  --quality <q> auto | low | medium | high | xhigh | max
41
- --format <fmt> png | jpeg | webp | svg
41
+ --format <fmt> png | jpeg | webp | svg | gif (gif = animation on models
42
+ that support it, e.g. openai/gpt-image-2.6-*)
43
+ --frames <n> Animation frames, 2-64 (gif only)
44
+ --frame-ms <ms> Display time per frame, 20-2000 ms (gif only)
45
+ --markup <url|path> Transparent PNG overlay (arrows, circles) the size of
46
+ the first --image, guiding where an edit applies
42
47
  --compression <n> 0-100, webp/jpeg only
43
48
  --background <b> auto | transparent | opaque
44
49
  --seed <n>
@@ -120,6 +125,9 @@ export async function imageCommand(argv) {
120
125
  image: { type: "string", multiple: true },
121
126
  quality: { type: "string" },
122
127
  format: { type: "string" },
128
+ frames: { type: "string" },
129
+ "frame-ms": { type: "string" },
130
+ markup: { type: "string" },
123
131
  compression: { type: "string" },
124
132
  background: { type: "string" },
125
133
  seed: { type: "string" },
@@ -146,6 +154,12 @@ export async function imageCommand(argv) {
146
154
  }
147
155
  if (values.quality) body.quality = values.quality;
148
156
  if (values.format) body.output_format = values.format;
157
+ if (values.frames) body.frame_count = numberOption(values.frames, "--frames");
158
+ if (values["frame-ms"]) body.frame_duration_ms = numberOption(values["frame-ms"], "--frame-ms");
159
+ if (values.markup) {
160
+ if (!body.input_references) throw new Error("--markup needs at least one --image to edit");
161
+ body.markup = { type: "image_url", image_url: { url: await mediaUrl(values.markup) } };
162
+ }
149
163
  if (values.compression)
150
164
  body.output_compression = numberOption(values.compression, "--compression");
151
165
  if (values.background) body.background = values.background;
@@ -0,0 +1,265 @@
1
+ import {
2
+ parseArgs,
3
+ authFromValues,
4
+ PAGINATION_OPTIONS,
5
+ paginationQuery,
6
+ loadJson,
7
+ } from "../args.js";
8
+ import { api } from "../api.js";
9
+ import { outln, printResult, table } from "../output.js";
10
+
11
+ export const POLICIES_HELP = `Usage: openrouter guardrails policies <subcommand> [options]
12
+
13
+ Typed guardrail policies (requires a management key). Each policy has one type:
14
+ budget, model-availability or moderation. Workspace policies need --workspace;
15
+ --account works on workspace-wide (account) policies instead. The legacy
16
+ \`guardrails\` commands keep working: default policies map to them.
17
+
18
+ Subcommands:
19
+ list --type <t> --workspace <uuid> List policies of a type (--offset/--limit)
20
+ list --account List workspace-wide policies (all types)
21
+ get <id> --type <t> --workspace <uuid> Get one (no get for --account policies)
22
+ create <name> --type <t> --config <json|@file> (--workspace <uuid> | --account)
23
+ update <id> --type <t> --name <n> --config <json|@file> (--workspace <uuid> | --account)
24
+ PUT: replaces name and config
25
+ delete <id> --type <t> --workspace <uuid>
26
+ delete <id> --account
27
+ assignment key|member <hash|user_id> --type <t> --workspace <uuid>
28
+ Which policies of a type apply to it
29
+ assign key|member <hash|user_id> <policy_id> --type <t> --workspace <uuid> [--unassign]
30
+ Reads the current assignment first and sends
31
+ it as expected_assignment (409 if it changed).
32
+ --unassign of the last explicit policy also opts
33
+ the subject out of the workspace default; assign
34
+ the default policy id again to undo that
35
+
36
+ Types (--type): budget | model-availability | moderation (assignment also takes rate-limit)
37
+
38
+ Config (--config) is the policy's config object, for example:
39
+ budget {"limit_usd":10,"reset_interval":"daily","include_byok_in_budgets":false}
40
+ model-availability {"allowed_providers":["anthropic"],"enforce_zdr":true}
41
+ moderation {"content_filter_builtins":[{"slug":"email","action":"redact"}]}
42
+
43
+ create / update options:
44
+ --default is_workspace_default (with --account: is_default)
45
+ --members <csv> member_ids
46
+ --keys <csv> api_key_hashes
47
+ --opt-out-members <csv> opted_out_member_ids
48
+ --opt-out-keys <csv> opted_out_api_key_hashes
49
+ --workspaces <csv> workspace_ids (--account only)
50
+ --opt-out-workspaces <csv> opted_out_workspace_ids (--account only)
51
+ --extra <json|@file> Extra body fields, merged last (e.g. floor_reassignment)
52
+ `;
53
+
54
+ const TYPES = {
55
+ budget: "budget",
56
+ "model-availability": "model_availability",
57
+ moderation: "moderation",
58
+ };
59
+ const ASSIGNMENT_TYPES = { ...TYPES, "rate-limit": "rate_limit" };
60
+
61
+ const OPTIONS = {
62
+ ...PAGINATION_OPTIONS,
63
+ type: { type: "string" },
64
+ workspace: { type: "string" },
65
+ account: { type: "boolean" },
66
+ name: { type: "string" },
67
+ config: { type: "string" },
68
+ default: { type: "boolean" },
69
+ members: { type: "string" },
70
+ keys: { type: "string" },
71
+ "opt-out-members": { type: "string" },
72
+ "opt-out-keys": { type: "string" },
73
+ workspaces: { type: "string" },
74
+ "opt-out-workspaces": { type: "string" },
75
+ extra: { type: "string" },
76
+ unassign: { type: "boolean" },
77
+ };
78
+
79
+ function csv(v) {
80
+ if (v == null) return undefined;
81
+ return v
82
+ .split(",")
83
+ .map((s) => s.trim())
84
+ .filter(Boolean);
85
+ }
86
+
87
+ function policyType(values, types = TYPES) {
88
+ const t = values.type;
89
+ if (!t) throw new Error(`--type required: ${Object.keys(types).join(" | ")}`);
90
+ const slug = types[t] || (Object.values(types).includes(t) ? t : undefined);
91
+ if (!slug) throw new Error(`Unknown --type "${t}". Expected: ${Object.keys(types).join(", ")}`);
92
+ return slug;
93
+ }
94
+
95
+ // URL segment for a policy type: model_availability -> model-availability
96
+ const segment = (slug) => slug.replace(/_/g, "-");
97
+
98
+ function workspaceId(values) {
99
+ if (!values.workspace) throw new Error("--workspace <uuid> required");
100
+ return values.workspace;
101
+ }
102
+
103
+ async function jsonObject(value, flag) {
104
+ const parsed = await loadJson(value, flag);
105
+ if (parsed === undefined) return undefined;
106
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
107
+ throw new Error(`${flag} must be a JSON object`);
108
+ }
109
+ return parsed;
110
+ }
111
+
112
+ async function buildBody(values, { name, includeType }) {
113
+ const config = await jsonObject(values.config, "--config");
114
+ if (!config) throw new Error("--config <json|@file> required");
115
+ if (!name) throw new Error("name required");
116
+ const body = { name, config };
117
+ if (values.account) {
118
+ body.policy_type = policyType(values);
119
+ if (values.default) body.is_default = true;
120
+ if (values.workspaces !== undefined) body.workspace_ids = csv(values.workspaces);
121
+ if (values["opt-out-workspaces"] !== undefined)
122
+ body.opted_out_workspace_ids = csv(values["opt-out-workspaces"]);
123
+ } else {
124
+ if (includeType) body.policy_type = policyType(values);
125
+ body.workspace_id = workspaceId(values);
126
+ if (values.default) body.is_workspace_default = true;
127
+ }
128
+ const lists = [
129
+ ["member_ids", "members"],
130
+ ["api_key_hashes", "keys"],
131
+ ["opted_out_member_ids", "opt-out-members"],
132
+ ["opted_out_api_key_hashes", "opt-out-keys"],
133
+ ];
134
+ for (const [field, flag] of lists) {
135
+ if (values[flag] === undefined) continue;
136
+ if (values.account) throw new Error(`--${flag} works only on workspace policies`);
137
+ body[field] = csv(values[flag]);
138
+ }
139
+ const extra = await jsonObject(values.extra, "--extra");
140
+ if (extra) Object.assign(body, extra);
141
+ return body;
142
+ }
143
+
144
+ function basePath(values) {
145
+ if (values.account) return "/guardrails/policies/account";
146
+ return `/guardrails/policies/${segment(policyType(values))}`;
147
+ }
148
+
149
+ function assignmentPath(kind, id) {
150
+ if (kind === "key") return `/guardrails/policies/assignments/api-keys/${encodeURIComponent(id)}`;
151
+ if (kind === "member")
152
+ return `/guardrails/policies/assignments/members/${encodeURIComponent(id)}`;
153
+ throw new Error('First argument must be "key" or "member"');
154
+ }
155
+
156
+ export async function policiesCommand(argv) {
157
+ const sub = argv[0];
158
+ const rest = argv.slice(1);
159
+ if (!sub || sub === "help" || sub === "-h" || sub === "--help") {
160
+ process.stdout.write(POLICIES_HELP);
161
+ return sub ? 0 : 1;
162
+ }
163
+ if (rest.includes("-h") || rest.includes("--help")) {
164
+ process.stdout.write(POLICIES_HELP);
165
+ return 0;
166
+ }
167
+
168
+ const { values, positionals } = parseArgs(rest, OPTIONS);
169
+ const opts = { auth: authFromValues(values), requiresManagement: true };
170
+
171
+ if (sub === "list") {
172
+ const query = paginationQuery(values);
173
+ if (!values.account) query.workspace_id = workspaceId(values);
174
+ const data = await api("GET", basePath(values), { ...opts, query });
175
+ printResult(data, () => {
176
+ table(data.data || [], [
177
+ { label: "id", value: (p) => p.id },
178
+ { label: "name", value: (p) => p.name },
179
+ { label: "type", value: (p) => p.policy_type },
180
+ {
181
+ label: "default",
182
+ value: (p) => (p.is_default || p.is_workspace_default ? "yes" : ""),
183
+ },
184
+ {
185
+ label: values.account ? "workspaces" : "members/keys",
186
+ value: (p) =>
187
+ values.account
188
+ ? (p.workspace_count ?? "")
189
+ : `${p.member_count ?? 0}/${p.api_key_count ?? 0}`,
190
+ },
191
+ ]);
192
+ });
193
+ return 0;
194
+ }
195
+
196
+ if (sub === "get") {
197
+ if (values.account) throw new Error("The API has no get for --account policies; use list");
198
+ if (!positionals[0]) throw new Error("id required");
199
+ const data = await api("GET", `${basePath(values)}/${encodeURIComponent(positionals[0])}`, {
200
+ ...opts,
201
+ query: { workspace_id: workspaceId(values) },
202
+ });
203
+ printResult(data);
204
+ return 0;
205
+ }
206
+
207
+ if (sub === "create") {
208
+ const body = await buildBody(values, { name: positionals[0], includeType: true });
209
+ const data = await api("POST", basePath(values), { ...opts, body });
210
+ printResult(data);
211
+ return 0;
212
+ }
213
+
214
+ if (sub === "update") {
215
+ if (!positionals[0]) throw new Error("id required");
216
+ if (!values.name) throw new Error("--name required (PUT replaces name and config)");
217
+ const body = await buildBody(values, { name: values.name, includeType: false });
218
+ const data = await api("PUT", `${basePath(values)}/${encodeURIComponent(positionals[0])}`, {
219
+ ...opts,
220
+ body,
221
+ });
222
+ printResult(data);
223
+ return 0;
224
+ }
225
+
226
+ if (sub === "delete") {
227
+ if (!positionals[0]) throw new Error("id required");
228
+ const query = values.account ? undefined : { workspace_id: workspaceId(values) };
229
+ const data = await api("DELETE", `${basePath(values)}/${encodeURIComponent(positionals[0])}`, {
230
+ ...opts,
231
+ query,
232
+ });
233
+ printResult(data, () => outln("deleted"));
234
+ return 0;
235
+ }
236
+
237
+ if (sub === "assignment" || sub === "assign") {
238
+ const [kind, id, policyId] = positionals;
239
+ if (!kind || !id) throw new Error(`Usage: ${sub} key|member <hash|user_id>`);
240
+ const path = assignmentPath(kind, id);
241
+ const query = {
242
+ workspace_id: workspaceId(values),
243
+ policy_type: policyType(values, ASSIGNMENT_TYPES),
244
+ };
245
+ const current = await api("GET", path, { ...opts, query });
246
+ if (sub === "assignment") {
247
+ printResult(current);
248
+ return 0;
249
+ }
250
+ if (!policyId) throw new Error("Usage: assign key|member <hash|user_id> <policy_id>");
251
+ const data = await api("PUT", path, {
252
+ ...opts,
253
+ body: {
254
+ ...query,
255
+ policy_id: policyId,
256
+ assigned: !values.unassign,
257
+ expected_assignment: current.data,
258
+ },
259
+ });
260
+ printResult(data, () => outln(values.unassign ? "unassigned" : "assigned"));
261
+ return 0;
262
+ }
263
+
264
+ throw new Error(`Unknown guardrails policies subcommand: ${sub}`);
265
+ }