@aaronjmars/openroutercli 0.2.2 → 0.4.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.
@@ -5,8 +5,63 @@ import {
5
5
  PAGINATION_OPTIONS,
6
6
  paginationQuery,
7
7
  } from "../args.js";
8
- import { api } from "../api.js";
9
- import { printResult, table } from "../output.js";
8
+ import { api, APIError } from "../api.js";
9
+ import { outln, printResult, table } from "../output.js";
10
+
11
+ // Org-only endpoints answer a personal account with an error (404 or a
12
+ // message naming organization accounts). Add a plain hint to it.
13
+ async function orgOnly(promise) {
14
+ try {
15
+ return await promise;
16
+ } catch (err) {
17
+ if (
18
+ err instanceof APIError &&
19
+ (err.status === 404 || /organi[sz]ation/i.test(err.message || ""))
20
+ ) {
21
+ err.message +=
22
+ "\nHint: your management key belongs to a personal account. Switch to an" +
23
+ " organization in the OpenRouter dashboard and create the management key there.";
24
+ }
25
+ throw err;
26
+ }
27
+ }
28
+
29
+ async function orgSettingsCommand(argv) {
30
+ const { values } = parseArgs(argv, {
31
+ "filtered-catalog": { type: "string" },
32
+ });
33
+ if (values.help) {
34
+ process.stdout.write(
35
+ "Usage: openrouter org settings [--filtered-catalog true|false]\n\n" +
36
+ "Show organization settings, or change them. Organization accounts only;\n" +
37
+ "requires a management key.\n\n" +
38
+ "Options:\n" +
39
+ " --filtered-catalog <bool> When true, GET /models with an org API key returns\n" +
40
+ " only the models that key can use (the models user\n" +
41
+ " catalog), and the dashboard shows the same list.\n",
42
+ );
43
+ return 0;
44
+ }
45
+ const opts = { auth: authFromValues(values), requiresManagement: true };
46
+ let data;
47
+ if (values["filtered-catalog"] !== undefined) {
48
+ const v = values["filtered-catalog"].toLowerCase();
49
+ if (v !== "true" && v !== "false") throw new Error("--filtered-catalog must be true or false");
50
+ data = await orgOnly(
51
+ api("PATCH", "/organization/settings", {
52
+ ...opts,
53
+ body: { is_filtered_model_catalog_enabled: v === "true" },
54
+ }),
55
+ );
56
+ } else {
57
+ data = await orgOnly(api("GET", "/organization/settings", opts));
58
+ }
59
+ printResult(data, () => {
60
+ const d = data.data || data;
61
+ for (const [k, v] of Object.entries(d)) outln(`${k}: ${v}`);
62
+ });
63
+ return 0;
64
+ }
10
65
 
11
66
  async function orgMembersCommand(argv) {
12
67
  const { values } = parseArgs(argv, PAGINATION_OPTIONS);
@@ -17,11 +72,13 @@ async function orgMembersCommand(argv) {
17
72
  return 0;
18
73
  }
19
74
  const query = paginationQuery(values);
20
- const data = await api("GET", "/organization/members", {
21
- auth: authFromValues(values),
22
- requiresManagement: true,
23
- query,
24
- });
75
+ const data = await orgOnly(
76
+ api("GET", "/organization/members", {
77
+ auth: authFromValues(values),
78
+ requiresManagement: true,
79
+ query,
80
+ }),
81
+ );
25
82
  printResult(data, () => {
26
83
  const rows = data.data || [];
27
84
  table(rows, [
@@ -38,9 +95,14 @@ export async function orgCommand(argv) {
38
95
  const sub = argv[0];
39
96
  const rest = argv.slice(1);
40
97
  if (sub === "members") return orgMembersCommand(rest);
98
+ if (sub === "settings") return orgSettingsCommand(rest);
41
99
  if (!sub || sub === "-h" || sub === "--help" || sub === "help") {
42
100
  process.stdout.write(
43
- "Usage: openrouter org <subcommand>\n\nSubcommands:\n members List organization members (management key)\n",
101
+ "Usage: openrouter org <subcommand>\n\n" +
102
+ "Organization accounts only; requires a management key.\n\n" +
103
+ "Subcommands:\n" +
104
+ " members [--offset N] [--limit N] List organization members\n" +
105
+ " settings [--filtered-catalog true|false] Show or change organization settings\n",
44
106
  );
45
107
  return sub ? 0 : 1;
46
108
  }
@@ -71,6 +133,7 @@ export async function authCodeCommand(argv) {
71
133
  "key-label": { type: "string" },
72
134
  limit: { type: "string" },
73
135
  "usage-limit-type": { type: "string" },
136
+ workspace: { type: "string" },
74
137
  });
75
138
  if (values.help || !values["callback-url"]) {
76
139
  process.stdout.write(
@@ -78,13 +141,14 @@ export async function authCodeCommand(argv) {
78
141
  "Mint a PKCE authorization code so a user can claim a key for your app.\n" +
79
142
  "Requires a management key.\n\n" +
80
143
  "Options:\n" +
81
- " --callback-url <url> HTTPS URL on port 443 or 3000 (required)\n" +
144
+ " --callback-url <url> https URL, or localhost/127.0.0.1 on any port (required)\n" +
82
145
  " --code-challenge <s> PKCE challenge\n" +
83
146
  " --code-challenge-method <m> S256 | plain\n" +
84
- " --expires-at <iso> Optional ISO 8601 UTC expiry\n" +
147
+ " --expires-at <iso> ISO 8601 UTC expiry with seconds (2027-12-31T23:59:59Z)\n" +
85
148
  " --key-label <text> Custom label for the resulting key\n" +
86
149
  " --limit <usd> Credit limit\n" +
87
- " --usage-limit-type <p> daily | weekly | monthly\n",
150
+ " --usage-limit-type <p> daily | weekly | monthly\n" +
151
+ " --workspace <uuid> Workspace the resulting key belongs to\n",
88
152
  );
89
153
  return values.help ? 0 : 1;
90
154
  }
@@ -95,6 +159,7 @@ export async function authCodeCommand(argv) {
95
159
  if (values["key-label"]) body.key_label = values["key-label"];
96
160
  if (values.limit) body.limit = numberOption(values.limit, "--limit");
97
161
  if (values["usage-limit-type"]) body.usage_limit_type = values["usage-limit-type"];
162
+ if (values.workspace) body.workspace_id = values.workspace;
98
163
  const data = await api("POST", "/auth/keys/code", {
99
164
  auth: authFromValues(values),
100
165
  requiresManagement: true,
@@ -1,5 +1,11 @@
1
- import { parseArgs, authFromValues } from "../args.js";
2
- import { api } from "../api.js";
1
+ import {
2
+ parseArgs,
3
+ authFromValues,
4
+ numberOption,
5
+ PAGINATION_OPTIONS,
6
+ paginationQuery,
7
+ } from "../args.js";
8
+ import { api, APIError } from "../api.js";
3
9
  import { c, isJsonMode, outln, pricePerMillion, printResult, table } from "../output.js";
4
10
 
5
11
  const ENDPOINT_SORT_FIELDS = ["throughput", "latency", "prompt", "completion", "uptime", "context"];
@@ -21,17 +27,30 @@ Subcommands:
21
27
  architecture, supported params, top provider).
22
28
  Aliases: info, detail
23
29
  endpoints <author>/<slug> List endpoints (provider variants) for a model
24
- parameters <author>/<slug> Supported params + popularity analytics (p10/p50/p90)
25
- user Models filtered by your workspace preferences
30
+ parameters <author>/<slug> Supported request parameters for a model
31
+ (undocumented endpoint, may change)
32
+ user Models filtered by your provider preferences,
33
+ privacy settings and guardrails (API key)
26
34
  count Get the total model count
27
35
 
28
36
  Options for list:
29
37
  --category <name> programming|roleplay|marketing|marketing/seo|
30
38
  technology|science|translation|legal|finance|
31
39
  health|trivia|academia
40
+ --q <text> Server-side search by model name or slug
32
41
  --supported <param> Filter by supported parameter (e.g. tools)
33
42
  --input-modalities <csv> text,image,audio,file (or "all")
34
- --output-modalities <csv> text,image,audio,embeddings (or "all")
43
+ --output-modalities <csv> text,image,embeddings,audio,video,rerank,
44
+ decisions,speech,transcription (or "all")
45
+ --context <tokens> Minimum context length
46
+ --min-price <$/M> Minimum prompt price
47
+ --max-price <$/M> Maximum prompt price
48
+ --arch <family> Model architecture/family
49
+ --model-authors <csv> Model author slugs
50
+ --providers <csv> Hosting provider names
51
+ --distillable <true|false> Filter by distillation capability
52
+ --zdr Only models with ZDR endpoints
53
+ --region <region> Only models with endpoints in a data region: eu | us
35
54
  --order <sort> Server-side sort: most-popular|newest|top-weekly|
36
55
  pricing-low-to-high|pricing-high-to-low|
37
56
  context-high-to-low|throughput-high-to-low|
@@ -45,14 +64,71 @@ Options for list:
45
64
  // Server-side filters shared by `list` and `user`.
46
65
  function listQuery(values) {
47
66
  const query = {};
67
+ if (values.q) query.q = values.q;
48
68
  if (values.category) query.category = values.category;
49
69
  if (values.supported) query.supported_parameters = values.supported;
50
70
  if (values["input-modalities"]) query.input_modalities = values["input-modalities"];
51
71
  if (values["output-modalities"]) query.output_modalities = values["output-modalities"];
52
72
  if (values.order) query.sort = values.order;
73
+ const numeric = [
74
+ ["context", "context"],
75
+ ["min-price", "min_price"],
76
+ ["max-price", "max_price"],
77
+ ["min-output-price", "min_output_price"],
78
+ ["max-output-price", "max_output_price"],
79
+ ["min-age-days", "min_age_days"],
80
+ ["max-age-days", "max_age_days"],
81
+ ["min-intelligence-index", "min_intelligence_index"],
82
+ ["max-intelligence-index", "max_intelligence_index"],
83
+ ["min-coding-index", "min_coding_index"],
84
+ ["max-coding-index", "max_coding_index"],
85
+ ["min-agentic-index", "min_agentic_index"],
86
+ ["max-agentic-index", "max_agentic_index"],
87
+ ["min-tool-success-rate", "min_tool_success_rate"],
88
+ ["max-tool-success-rate", "max_tool_success_rate"],
89
+ ];
90
+ for (const [flag, key] of numeric) {
91
+ if (values[flag] !== undefined) query[key] = numberOption(values[flag], `--${flag}`);
92
+ }
93
+ if (values.arch) query.arch = values.arch;
94
+ if (values["model-authors"]) query.model_authors = values["model-authors"];
95
+ if (values.providers) query.providers = values.providers;
96
+ if (values.distillable !== undefined) query.distillable = values.distillable;
97
+ if (values.zdr) query.zdr = "true";
98
+ if (values.region) query.region = values.region;
53
99
  return query;
54
100
  }
55
101
 
102
+ const LIST_OPTIONS = {
103
+ q: { type: "string" },
104
+ category: { type: "string" },
105
+ supported: { type: "string" },
106
+ "input-modalities": { type: "string" },
107
+ "output-modalities": { type: "string" },
108
+ order: { type: "string" },
109
+ context: { type: "string" },
110
+ "min-price": { type: "string" },
111
+ "max-price": { type: "string" },
112
+ "min-output-price": { type: "string" },
113
+ "max-output-price": { type: "string" },
114
+ arch: { type: "string" },
115
+ "model-authors": { type: "string" },
116
+ providers: { type: "string" },
117
+ distillable: { type: "string" },
118
+ zdr: { type: "boolean" },
119
+ region: { type: "string" },
120
+ "min-age-days": { type: "string" },
121
+ "max-age-days": { type: "string" },
122
+ "min-intelligence-index": { type: "string" },
123
+ "max-intelligence-index": { type: "string" },
124
+ "min-coding-index": { type: "string" },
125
+ "max-coding-index": { type: "string" },
126
+ "min-agentic-index": { type: "string" },
127
+ "max-agentic-index": { type: "string" },
128
+ "min-tool-success-rate": { type: "string" },
129
+ "max-tool-success-rate": { type: "string" },
130
+ };
131
+
56
132
  function listFormatter(data) {
57
133
  const rows = data.data || [];
58
134
  table(rows.slice(0, 200), [
@@ -161,6 +237,26 @@ function renderModelDetail(m) {
161
237
  outln(c.dim(`per_request_limits: ${JSON.stringify(m.per_request_limits)}`));
162
238
  }
163
239
 
240
+ // GET /model/{author}/{slug}: one model by id, no key needed. Returns null
241
+ // when the id is unknown so the caller can fall back to a fuzzy match.
242
+ async function fetchModel(id, auth) {
243
+ const slash = id.indexOf("/");
244
+ const author = encodeURIComponent(id.slice(0, slash));
245
+ const slug = encodeURIComponent(id.slice(slash + 1)).replace(/%3A/gi, ":");
246
+ try {
247
+ const res = await api("GET", `/model/${author}/${slug}`, { auth, requireAuth: false });
248
+ return (res && res.data) || null;
249
+ } catch (err) {
250
+ if (err instanceof APIError && (err.status === 404 || err.status === 400)) return null;
251
+ throw err;
252
+ }
253
+ }
254
+
255
+ function nativeTools(e) {
256
+ const keys = Object.keys(e.native_tools || {});
257
+ return keys.map((k) => k.replace(/^openrouter:/, "")).join(",");
258
+ }
259
+
164
260
  export async function modelsCommand(argv) {
165
261
  // A leading non-flag token is the subcommand; otherwise default to list
166
262
  // and keep argv intact so the list branch still sees its flags.
@@ -171,13 +267,30 @@ export async function modelsCommand(argv) {
171
267
  const { values, positionals } = parseArgs(rest, {});
172
268
  if (values.help || positionals.length === 0) {
173
269
  process.stdout.write(
174
- "Usage: openrouter models show <model-id>\n\nShow full details (pricing, architecture, capabilities) for one model.\n",
270
+ "Usage: openrouter models show <model-id>\n\n" +
271
+ "Show full details (pricing, architecture, capabilities) for one model.\n" +
272
+ "An <author>/<slug> id (variants like :free too) is looked up directly, which\n" +
273
+ "also finds image/video models the default list hides. Anything else is\n" +
274
+ "matched against model ids and names. No API key needed.\n",
175
275
  );
176
276
  return values.help ? 0 : 1;
177
277
  }
278
+ // An <author>/<slug> id resolves directly (aliases, :variants, and image
279
+ // or video models the default list hides). A miss falls back to the
280
+ // fuzzy match over the full list below.
281
+ const direct = positionals[0].includes("/")
282
+ ? await fetchModel(positionals[0], authFromValues(values))
283
+ : null;
284
+ if (direct) {
285
+ if (isJsonMode()) printResult(direct);
286
+ else renderModelDetail(direct);
287
+ return 0;
288
+ }
178
289
  const target = positionals[0].toLowerCase();
290
+ // output_modalities=all so image/video/audio models are matchable too.
179
291
  const data = await api("GET", "/models", {
180
292
  auth: authFromValues(values),
293
+ query: { output_modalities: "all" },
181
294
  requireAuth: false,
182
295
  });
183
296
  const rows = data.data || [];
@@ -299,28 +412,46 @@ export async function modelsCommand(argv) {
299
412
  e.uptime_last_30m != null ? Number(e.uptime_last_30m).toFixed(1) + "%" : "",
300
413
  },
301
414
  { label: "quant", value: (e) => e.quantization || "" },
415
+ { label: "native tools", value: nativeTools },
302
416
  ]);
303
417
  });
304
418
  return 0;
305
419
  }
306
420
 
307
421
  if (sub === "user") {
308
- const { values } = parseArgs(rest, {
309
- workspace: { type: "string" },
310
- category: { type: "string" },
311
- supported: { type: "string" },
312
- "input-modalities": { type: "string" },
313
- "output-modalities": { type: "string" },
314
- order: { type: "string" },
315
- });
422
+ let parsed;
423
+ try {
424
+ parsed = parseArgs(rest, {
425
+ ...PAGINATION_OPTIONS,
426
+ "output-modalities": { type: "string" },
427
+ });
428
+ } catch (err) {
429
+ // `models user` used to forward every list filter; the endpoint only
430
+ // takes these three, so say so instead of a bare "Unknown option".
431
+ if (err.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
432
+ throw new Error(
433
+ `${err.message.split(".")[0]}. models user only supports --output-modalities, --limit and --offset; use \`openrouter models list\` for search filters.`,
434
+ );
435
+ }
436
+ throw err;
437
+ }
438
+ const { values } = parsed;
316
439
  if (values.help) {
317
440
  process.stdout.write(
318
- "Usage: openrouter models user [--workspace <id|slug>] [--category <c>] [--supported <p>] [--input-modalities <csv>] [--output-modalities <csv>] [--order <sort>]\n\nList models filtered by your workspace provider preferences, privacy, and guardrails.\n",
441
+ "Usage: openrouter models user [--output-modalities <csv>] [--limit <n>] [--offset <n>]\n\n" +
442
+ "List models filtered by your provider preferences, privacy settings, and\n" +
443
+ "guardrails. Uses your API key; on a regional host (eu/us) only models that\n" +
444
+ "can route in-region are returned.\n\n" +
445
+ "Options:\n" +
446
+ " --output-modalities <csv> text,image,embeddings,audio,video,rerank,decisions,\n" +
447
+ ' speech,transcription (or "all"). Default: text\n' +
448
+ " --limit <n> Max rows (1-1000). Omit limit and offset for all\n" +
449
+ " --offset <n> Rows to skip\n",
319
450
  );
320
451
  return 0;
321
452
  }
322
- const query = listQuery(values);
323
- if (values.workspace) query.workspace_id = values.workspace;
453
+ const query = paginationQuery(values);
454
+ if (values["output-modalities"]) query.output_modalities = values["output-modalities"];
324
455
  const data = await api("GET", "/models/user", {
325
456
  auth: authFromValues(values),
326
457
  query,
@@ -336,8 +467,9 @@ export async function modelsCommand(argv) {
336
467
  if (values.help || positionals.length === 0) {
337
468
  process.stdout.write(
338
469
  "Usage: openrouter models parameters <author>/<slug> [--provider <slug>]\n\n" +
339
- "Show a model's supported parameters plus popularity analytics\n" +
340
- "(p10/p50/p90 per parameter). Optionally scope to one provider.\n",
470
+ "Show the request parameters a model supports. Optionally scope to one provider.\n" +
471
+ "Note: /parameters is not in the public API spec; it works today but may change.\n" +
472
+ "For the documented list see `openrouter models show <id>` (supported_parameters).\n",
341
473
  );
342
474
  return values.help ? 0 : 1;
343
475
  }
@@ -352,14 +484,23 @@ export async function modelsCommand(argv) {
352
484
  auth: authFromValues(values),
353
485
  query,
354
486
  });
355
- printResult(data);
487
+ printResult(data, () => {
488
+ const d = data.data || data;
489
+ outln(d.model || target);
490
+ for (const p of d.supported_parameters || []) outln(` ${p}`);
491
+ });
356
492
  return 0;
357
493
  }
358
494
 
359
495
  if (sub === "count") {
360
- const { values } = parseArgs(rest, {});
496
+ const { values } = parseArgs(rest, {
497
+ "output-modalities": { type: "string" },
498
+ });
499
+ const query = {};
500
+ if (values["output-modalities"]) query.output_modalities = values["output-modalities"];
361
501
  const data = await api("GET", "/models/count", {
362
502
  auth: authFromValues(values),
503
+ query,
363
504
  requireAuth: false,
364
505
  });
365
506
  printResult(data, () => outln(JSON.stringify(data)));
@@ -367,11 +508,7 @@ export async function modelsCommand(argv) {
367
508
  }
368
509
 
369
510
  const { values } = parseArgs(rest, {
370
- category: { type: "string" },
371
- supported: { type: "string" },
372
- "input-modalities": { type: "string" },
373
- "output-modalities": { type: "string" },
374
- order: { type: "string" },
511
+ ...LIST_OPTIONS,
375
512
  filter: { type: "string" },
376
513
  free: { type: "boolean" },
377
514
  sort: { type: "string" },
@@ -438,6 +575,7 @@ export async function modelsCommand(argv) {
438
575
  }
439
576
 
440
577
  const filtered = { ...data, data: rows };
578
+ if (values.filter || values.free) filtered.total_count = rows.length;
441
579
  printResult(filtered, () => listFormatter(filtered));
442
580
  return 0;
443
581
  }