@limitry/cli 1.0.0-rc.13 → 1.0.0-rc.15

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/CHANGELOG.md CHANGED
@@ -2,6 +2,86 @@
2
2
 
3
3
  What changed in the Limitry CLI (`@limitry/cli`). Generated from the source on each release; newest first.
4
4
 
5
+ ## 1.0.0-rc.15 (2026-11-14)
6
+
7
+ ### Added
8
+
9
+ - The workspace's audit log (`GET /v1/workspace/audit-events`) records
10
+ `billing.cancellation_undone` when a plan set to cancel is kept after all.
11
+ - The workspace's audit log (`GET /v1/workspace/audit-events`) records more
12
+ events. It now includes the workspace's creation and deletion, a declined
13
+ invitation, and plan changes: `workspace.created`, `workspace.deleted`,
14
+ `workspace.invitation_rejected` and `billing.subscribed`,
15
+ `billing.plan_changed`, `billing.cancellation_scheduled` and
16
+ `billing.subscription_ended`.
17
+ - `GET /v1/workspace/usage` now says where each count stands. Each count
18
+ gains `label`, `state` and `stopsAt`, and `unit` when the plan names
19
+ one. The response gains a `state` for the whole workspace.
20
+ `client.workspace.usage.get()` and the Python client return them. The
21
+ CLI's `workspace usage` prints each count as a sentence that says where
22
+ it stands. Use `--json` for the response as it is.
23
+
24
+ ### Fixed
25
+
26
+ - `usage.overview()` (`GET /v1/usage/overview`) now totals each limit's whole
27
+ current window on every plan. On Free, a monthly limit's `total` covered
28
+ only the last 7 days; it now covers the whole month, as each subject's
29
+ amounts already did.
30
+
31
+ ## 1.0.0-rc.14 (2026-11-09)
32
+
33
+ ### Added
34
+
35
+ - Members and pending invitations now carry `seat`: the seat type a person
36
+ holds or will hold (`GET /v1/workspace/members`,
37
+ `GET /v1/workspace/invitations`). It is null for a guest, or where the
38
+ product has no seat types.
39
+ - `GET /v1/usage` and `GET /v1/usage/subjects` take a limit by its name, as
40
+ `limitName`, as well as by `limitId`. They also take a `period`, such as
41
+ `last_month` or `this_week`, instead of `from` and `to`.
42
+
43
+ `GET /v1/usage` returns the range's `total` (`used`, `allowed` and
44
+ `refused`) beside its buckets, and the range it covers as `from` and `to`.
45
+
46
+ `GET /v1/usage/subjects` lists who used a limit most in a past period when
47
+ you send `period`, or `from` and `to`. In that list, `remaining` is null.
48
+ Add `sort` as `refused` to list the most refused first. It also says when
49
+ the current window ends, as `resetsAt`.
50
+
51
+ Both responses include the limit's `limitName`, `unit`, `amount` and
52
+ `window`.
53
+
54
+ In the SDKs, `remaining` on `client.usage.subjects()` items is now typed
55
+ as a number or null, so check for null before using it. In the CLI, use
56
+ `--limit-name`, `--period` and `--sort`.
57
+
58
+ `GET /v1/usage/overview` is new: every active limit's usage in one answer,
59
+ with each limit's unit, amount, window, `total` and top subjects. It covers
60
+ each limit's current window, or a `period` or range you send. With `sort`
61
+ as `refused`, each limit lists only the subjects it refused. A balance
62
+ also lists the credits added to it and taken back in the range. In the SDKs
63
+ it's `client.usage.overview()`, and in the CLI `limitry usage overview`.
64
+
65
+ Every call about one limit takes the limit's name in place of its ID:
66
+ `GET`, `PATCH`, archive and restore on `/v1/limits/{limitId}`, and listing
67
+ and adding its credits. So does the `limit.credit` approval. A name
68
+ matches exactly, or else ignoring case. When two limits match ignoring
69
+ case, the call fails with a 400 that names both.
70
+
71
+ ### Changed
72
+
73
+ - A personal access token changes limits, subjects and credits only on its
74
+ person's side. An admin in a Developer seat changes test, and an admin in
75
+ an Operator seat changes live. The owner changes both. A change on the
76
+ other side returns 403 `forbidden`, and the message names who may make it.
77
+ Workspace API keys are not affected.
78
+
79
+ ### Removed
80
+
81
+ - A limit no longer has a `version` field (`GET /v1/limits`,
82
+ `GET /v1/limits/{limitId}` and every response that returns a limit). Use
83
+ `updatedAt` to tell whether a limit has changed.
84
+
5
85
  ## 1.0.0-rc.13 (2026-11-07)
6
86
 
7
87
  ### Added
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  The Limitry CLI sets up your limits and checks them from a terminal, a script or an agent: create a limit, try a check, and see who is using what, in test before live.
4
4
 
5
- Limitry is the limits, credits and budgets layer for the software you build: give each of your users, teams, tenants, API keys or agents an allowance, and before any costly action one call tells your code whether it may happen.
5
+ Limitry is the limits, credits and budgets layer for the software you build: give each of your users, teams, tenants, API keys or agents an allowance, and before any costly request one call tells your code whether it may happen.
6
6
 
7
7
  ## Install
8
8
 
@@ -28,12 +28,12 @@ Commands act in **test** unless you say otherwise, so trying things
28
28
  never touches the limits your customers depend on.
29
29
 
30
30
  ```bash
31
- # 100 AI replies a day for each user ("100 replies per user per day for ai-call")
31
+ # A $2 AI budget a month for each of your users ("200 cents per user per month for ai-call")
32
32
  limitry limits create --subject '{"kind":"user"}' --action ai-call \
33
- --amount 100 --unit replies --window day
33
+ --amount 200 --unit cents --window month
34
34
 
35
- # Check a user, as your code would
36
- limitry check user:usr_123 ai-call
35
+ # Check a user, as your code would, for a reply that costs 5 cents
36
+ limitry check user:usr_123 ai-call --cost 5
37
37
 
38
38
  # Where a user stands, without counting anything
39
39
  limitry usage standing --subject user:usr_123
package/dist/limitry.mjs CHANGED
@@ -17,21 +17,13 @@ var brand_default = {
17
17
  productName: "Limitry",
18
18
  legalName: "Omsome L.L.C-FZ",
19
19
  releaseMirrors: true,
20
- mirrorProfile: {
21
- topics: [
22
- "rate-limiting",
23
- "usage-limits",
24
- "credits",
25
- "budgets",
26
- "api-client",
27
- "sdk"
28
- ]
29
- },
20
+ keywords: ["usage-limits", "rate-limiting", "credits", "budgets", "quotas"],
30
21
  domain: "limitry.com",
31
22
  devDomain: "limitry.dev",
32
23
  labs: ["lab"],
33
24
  discordInvite: "https://discord.gg/Nb6QFd6ER4",
34
- summary: "Limitry is the limits, credits and budgets layer for the software you build: give each of your users, teams, tenants, API keys or agents an allowance, and before any costly action one call tells your code whether it may happen.",
25
+ profiles: { x: "limitryhq", github: "limitry" },
26
+ summary: "Limitry is the limits, credits and budgets layer for the software you build: give each of your users, teams, tenants, API keys or agents an allowance, and before any costly request one call tells your code whether it may happen.",
35
27
  expectedAssets: [
36
28
  "logo.svg",
37
29
  "logo-dark.svg",
@@ -148,6 +140,29 @@ var brand = {
148
140
  * when the product has no Discord.
149
141
  */
150
142
  discord: optional.discordInvite ? `https://${brand_default.domain}/discord` : null,
143
+ /**
144
+ * The product's accounts, for the site footer's icons, the docs
145
+ * header's and the app's help menu (owner, 2026-11-09): GitHub (the
146
+ * organisation, which lists the public SDKs), Discord (the /discord
147
+ * redirect) and X, each only when brand.json has it.
148
+ */
149
+ socialLinks: [
150
+ optional.profiles?.github && {
151
+ network: "github",
152
+ label: "GitHub",
153
+ href: `https://github.com/${optional.profiles.github}`
154
+ },
155
+ optional.discordInvite && {
156
+ network: "discord",
157
+ label: "Discord",
158
+ href: `https://${brand_default.domain}/discord`
159
+ },
160
+ optional.profiles?.x && {
161
+ network: "x",
162
+ label: "X",
163
+ href: `https://x.com/${optional.profiles.x}`
164
+ }
165
+ ].filter(Boolean),
151
166
  /** One sentence: what the product is — llms.txt and the agent skill lead with it. */
152
167
  summary: optional.summary ?? `${brand_default.productName} documentation and API.`,
153
168
  /** Where vulnerability reports go — /.well-known/security.txt and /security publish it. Defaults to security@<domain>. */
@@ -1344,17 +1359,21 @@ function resources(client) {
1344
1359
  )
1345
1360
  },
1346
1361
  usage: {
1362
+ overview: (
1363
+ /** Get every limit's usage at once */
1364
+ (input, options) => call(client, { "method": "get", "path": "/usage/overview", "query": ["period", "from", "to", "sort", "top"], "hasBody": false }, {}, input, options)
1365
+ ),
1347
1366
  query: (
1348
1367
  /** Get a limit's usage over time */
1349
- (input, options) => call(client, { "method": "get", "path": "/usage", "query": ["limitId", "subject", "from", "to", "granularity"], "hasBody": false }, {}, input, options)
1368
+ (input, options) => call(client, { "method": "get", "path": "/usage", "query": ["limitId", "limitName", "subject", "period", "from", "to", "granularity"], "hasBody": false }, {}, input, options)
1350
1369
  ),
1351
1370
  standing: (
1352
1371
  /** Get where a subject stands */
1353
1372
  (input, options) => call(client, { "method": "get", "path": "/usage/standing", "query": ["subject", "shared"], "hasBody": false }, {}, input, options)
1354
1373
  ),
1355
1374
  subjects: (
1356
- /** List who is using a limit now */
1357
- (input, options) => call(client, { "method": "get", "path": "/usage/subjects", "query": ["limitId", "limit"], "hasBody": false }, {}, input, options)
1375
+ /** List who is using a limit */
1376
+ (input, options) => call(client, { "method": "get", "path": "/usage/subjects", "query": ["limitId", "limitName", "period", "from", "to", "sort", "limit"], "hasBody": false }, {}, input, options)
1358
1377
  )
1359
1378
  },
1360
1379
  user: {
@@ -1831,11 +1850,11 @@ var Help = class {
1831
1850
  visibleOptions.push(helpOption);
1832
1851
  } else if (helpOption.long && !removeLong) {
1833
1852
  visibleOptions.push(
1834
- cmd.createOption(helpOption.long, helpOption.description)
1853
+ cmd.createOption(helpOption.long, helpOption.description).helpGroup(helpOption.helpGroupHeading)
1835
1854
  );
1836
1855
  } else if (helpOption.short && !removeShort) {
1837
1856
  visibleOptions.push(
1838
- cmd.createOption(helpOption.short, helpOption.description)
1857
+ cmd.createOption(helpOption.short, helpOption.description).helpGroup(helpOption.helpGroupHeading)
1839
1858
  );
1840
1859
  }
1841
1860
  }
@@ -2367,7 +2386,7 @@ var Option = class {
2367
2386
  this.description = description || "";
2368
2387
  this.required = flags.includes("<");
2369
2388
  this.optional = flags.includes("[");
2370
- this.variadic = /\w\.\.\.[>\]]$/.test(flags);
2389
+ this.variadic = new RegExp("\\p{ID_Continue}\\.\\.\\.[>\\]]$", "u").test(flags);
2371
2390
  this.mandatory = false;
2372
2391
  const optionFlags = splitOptionFlags(flags);
2373
2392
  this.short = optionFlags.shortFlag;
@@ -3550,7 +3569,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
3550
3569
  getOptionValueSourceWithGlobals(key) {
3551
3570
  let source;
3552
3571
  this._getCommandAndAncestors().forEach((cmd) => {
3553
- if (cmd.getOptionValueSource(key) !== void 0) {
3572
+ if (Object.hasOwn(cmd._optionValueSources, key)) {
3554
3573
  source = cmd.getOptionValueSource(key);
3555
3574
  }
3556
3575
  });
@@ -4193,7 +4212,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
4193
4212
  return arg.length > 1 && arg[0] === "-";
4194
4213
  }
4195
4214
  const negativeNumberArg = (arg) => {
4196
- if (!/^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/.test(arg)) return false;
4215
+ if (!/^-(\d+|\d*\.\d+)([eE][+-]?\d+)?$/.test(arg)) return false;
4197
4216
  return !this._getCommandAndAncestors().some(
4198
4217
  (cmd) => cmd.options.map((opt) => opt.short).some((short) => /^-\d$/.test(short))
4199
4218
  );
@@ -4641,7 +4660,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
4641
4660
  * (This does not override a group set directly on the subcommand using .helpGroup().)
4642
4661
  *
4643
4662
  * @example
4644
- * program.commandsGroup('Development Commands:);
4663
+ * program.commandsGroup('Development Commands:');
4645
4664
  * program.command('watch')...
4646
4665
  * program.command('lint')...
4647
4666
  * ...
@@ -4812,7 +4831,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
4812
4831
  * Pass in false to disable the built-in help option.
4813
4832
  *
4814
4833
  * @example
4815
- * program.helpOption('-?, --help' 'show help'); // customise
4834
+ * program.helpOption('-?, --help', 'show help'); // customise
4816
4835
  * program.helpOption(false); // disable
4817
4836
  *
4818
4837
  * @param {(string | boolean)} flags
@@ -4941,16 +4960,20 @@ function incrementNodeInspectorPort(args) {
4941
4960
  let debugHost = "127.0.0.1";
4942
4961
  let debugPort = "9229";
4943
4962
  let match;
4944
- if ((match = arg.match(/^(--inspect(-brk)?)$/)) !== null) {
4963
+ if ((match = arg.match(/^(--inspect(-brk|-wait)?)$/)) !== null) {
4945
4964
  debugOption = match[1];
4946
- } else if ((match = arg.match(/^(--inspect(-brk|-port)?)=([^:]+)$/)) !== null) {
4965
+ } else if ((match = arg.match(
4966
+ /^(--inspect(-brk|-port|-wait)?)=(\[[^\]]+\]|[^:]+)$/
4967
+ )) !== null) {
4947
4968
  debugOption = match[1];
4948
4969
  if (/^\d+$/.test(match[3])) {
4949
4970
  debugPort = match[3];
4950
4971
  } else {
4951
4972
  debugHost = match[3];
4952
4973
  }
4953
- } else if ((match = arg.match(/^(--inspect(-brk|-port)?)=([^:]+):(\d+)$/)) !== null) {
4974
+ } else if ((match = arg.match(
4975
+ /^(--inspect(-brk|-port|-wait)?)=(\[[^\]]+\]|[^:]+):(\d+)$/
4976
+ )) !== null) {
4954
4977
  debugOption = match[1];
4955
4978
  debugHost = match[3];
4956
4979
  debugPort = match[4];
@@ -5240,6 +5263,39 @@ var approvals = (program2, ctx) => {
5240
5263
  );
5241
5264
  };
5242
5265
 
5266
+ // src/usage.ts
5267
+ var usage = (program2, ctx) => {
5268
+ const workspace2 = program2.commands.find((c) => c.name() === "workspace") ?? program2.command("workspace");
5269
+ workspace2.command("usage").description("Show your plan's usage this period").option("--workspace <slug>", "act in this workspace for one call").option("--json", "machine-readable output").action(async (options) => {
5270
+ const result = unwrap(
5271
+ await ctx.client({ workspace: options.workspace }).GET("/workspace/usage")
5272
+ );
5273
+ if (options.json) {
5274
+ ctx.io.stdout(json(result));
5275
+ return;
5276
+ }
5277
+ for (const line of usageLines(result)) ctx.io.stdout(line);
5278
+ });
5279
+ };
5280
+ var number = (n) => n.toLocaleString("en-US");
5281
+ function usageLines(usage2) {
5282
+ const resets = new Date(usage2.periodEnd).toLocaleDateString("en-US", {
5283
+ month: "short",
5284
+ day: "numeric",
5285
+ year: "numeric",
5286
+ timeZone: "UTC"
5287
+ });
5288
+ const lines = [`Usage this period. Counters reset on ${resets}.`];
5289
+ if (usage2.counts.length === 0) lines.push("Your plan counts nothing.");
5290
+ for (const count of usage2.counts) {
5291
+ const figures = count.limit === null ? `${number(count.used)} (no limit)` : `${number(count.used)} of ${number(count.limit)}`;
5292
+ const state = count.state === "grace" ? count.stopsAt === null ? " Over your plan." : ` Over your plan. Past ${number(count.stopsAt)}, ${brand.productName} refuses new use.` : count.state === "stopped" ? ` ${brand.productName} refuses new use until ${resets}.` : count.state === "over" ? " Over your plan." : count.limit === 0 ? " Not in your plan." : "";
5293
+ lines.push(`${count.label}: ${figures}.${state}`);
5294
+ }
5295
+ for (const notice of usage2.notices ?? []) lines.push(notice);
5296
+ return lines;
5297
+ }
5298
+
5243
5299
  // src/commands.ts
5244
5300
  async function me(ctx) {
5245
5301
  return unwrap(await ctx.client({ workspace: false }).GET("/user/me"));
@@ -5463,7 +5519,8 @@ var platformCommands = [
5463
5519
  environment,
5464
5520
  api,
5465
5521
  config,
5466
- approvals
5522
+ approvals,
5523
+ usage
5467
5524
  ];
5468
5525
 
5469
5526
  // src/generated.ts
@@ -5677,11 +5734,11 @@ var OPERATIONS = [
5677
5734
  "in": "path",
5678
5735
  "type": "string",
5679
5736
  "required": true,
5680
- "description": "The limit's ID.",
5737
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case.",
5681
5738
  "example": "lmt_6f1c2a9e-4b7d-4e3a-9c5f-8d2b1a0e7c34",
5682
5739
  "schema": {
5683
5740
  "type": "string",
5684
- "description": "The limit's ID."
5741
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case."
5685
5742
  }
5686
5743
  }
5687
5744
  ],
@@ -5913,18 +5970,18 @@ var OPERATIONS = [
5913
5970
  "exposed": false,
5914
5971
  "reason": "Adding credits gives value away; an agent asks a person (limit.credit approval)"
5915
5972
  },
5916
- "description": "Adds `amount` credits to one subject's balance, on a limit whose window is `total`. A negative `amount` takes credits back, such as after a refund or a chargeback, and needs a `note` saying why. The balance can go below zero, and Limitry then refuses checks until you add more credits. Owners, admins and workspace API keys can add credits. An agent asks a person instead, through the `limit.credit` approval. Limitry keeps a credit's `Idempotency-Key` forever, so never reuse one for a new credit.",
5973
+ "description": "Adds `amount` credits to one subject's balance, on a limit whose window is `total`. A negative `amount` takes credits back, such as after a refund or a chargeback, and needs a `note` saying why. The balance can go below zero, and Limitry then refuses checks until you add more credits. Owners, admins and workspace API keys can add credits. An agent connected through MCP asks a person instead, through the `limit.credit` approval. Limitry keeps a credit's `Idempotency-Key` forever, so never reuse one for a new credit.",
5917
5974
  "fields": [
5918
5975
  {
5919
5976
  "name": "limitId",
5920
5977
  "in": "path",
5921
5978
  "type": "string",
5922
5979
  "required": true,
5923
- "description": "The limit's ID.",
5980
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case.",
5924
5981
  "example": "lmt_6f1c2a9e-4b7d-4e3a-9c5f-8d2b1a0e7c34",
5925
5982
  "schema": {
5926
5983
  "type": "string",
5927
- "description": "The limit's ID."
5984
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case."
5928
5985
  }
5929
5986
  },
5930
5987
  {
@@ -6017,11 +6074,11 @@ var OPERATIONS = [
6017
6074
  "in": "path",
6018
6075
  "type": "string",
6019
6076
  "required": true,
6020
- "description": "The limit's ID.",
6077
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case.",
6021
6078
  "example": "lmt_6f1c2a9e-4b7d-4e3a-9c5f-8d2b1a0e7c34",
6022
6079
  "schema": {
6023
6080
  "type": "string",
6024
- "description": "The limit's ID."
6081
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case."
6025
6082
  }
6026
6083
  },
6027
6084
  {
@@ -6111,11 +6168,11 @@ var OPERATIONS = [
6111
6168
  "in": "path",
6112
6169
  "type": "string",
6113
6170
  "required": true,
6114
- "description": "The limit's ID.",
6171
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case.",
6115
6172
  "example": "lmt_6f1c2a9e-4b7d-4e3a-9c5f-8d2b1a0e7c34",
6116
6173
  "schema": {
6117
6174
  "type": "string",
6118
- "description": "The limit's ID."
6175
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case."
6119
6176
  }
6120
6177
  }
6121
6178
  ],
@@ -6246,11 +6303,11 @@ var OPERATIONS = [
6246
6303
  "in": "path",
6247
6304
  "type": "string",
6248
6305
  "required": true,
6249
- "description": "The limit's ID.",
6306
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case.",
6250
6307
  "example": "lmt_6f1c2a9e-4b7d-4e3a-9c5f-8d2b1a0e7c34",
6251
6308
  "schema": {
6252
6309
  "type": "string",
6253
- "description": "The limit's ID."
6310
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case."
6254
6311
  }
6255
6312
  }
6256
6313
  ],
@@ -6383,11 +6440,11 @@ var OPERATIONS = [
6383
6440
  "in": "path",
6384
6441
  "type": "string",
6385
6442
  "required": true,
6386
- "description": "The limit's ID.",
6443
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case.",
6387
6444
  "example": "lmt_6f1c2a9e-4b7d-4e3a-9c5f-8d2b1a0e7c34",
6388
6445
  "schema": {
6389
6446
  "type": "string",
6390
- "description": "The limit's ID."
6447
+ "description": "The limit's ID, or its name, such as `AI budget` (URL-encoded). A name matches an active limit in this environment, exactly or else ignoring case."
6391
6448
  }
6392
6449
  },
6393
6450
  {
@@ -6914,6 +6971,111 @@ var OPERATIONS = [
6914
6971
  "acceptsApiKey": true,
6915
6972
  "scope": "limits:write"
6916
6973
  },
6974
+ {
6975
+ "operationId": "usage.overview",
6976
+ "method": "get",
6977
+ "path": "/usage/overview",
6978
+ "summary": "Get every limit's usage at once",
6979
+ "cli": {
6980
+ "command": "usage overview",
6981
+ "args": [],
6982
+ "confirm": false
6983
+ },
6984
+ "mcp": {
6985
+ "exposed": true,
6986
+ "name": "usage_overview",
6987
+ "hints": {
6988
+ "readOnlyHint": true,
6989
+ "destructiveHint": false,
6990
+ "idempotentHint": true
6991
+ }
6992
+ },
6993
+ "description": "Returns every active limit's usage in one answer, for a question that names no limit. Each limit comes with its name, unit, amount and window, its `total` (units used, checks allowed and refused) and its top subjects. By default, it covers each limit's current window, with exact amounts. For a past range, send `period`, such as `last_month`, or `from` and `to`. The totals and subjects then come from history, and each subject's `remaining` is null. Set `sort` to `refused` to list only the subjects each limit refused, the most refused first. A balance also lists the credits added to it in the range. The current window is whole on every plan. A past range reaches no further back than your plan's history.",
6994
+ "fields": [
6995
+ {
6996
+ "name": "period",
6997
+ "in": "query",
6998
+ "type": "string",
6999
+ "required": false,
7000
+ "description": "A named range instead of `from` and `to`, in UTC: `today`, `this_week` or `last_week` (weeks start on Monday), `this_month` or `last_month`. A current one ends now.",
7001
+ "example": "last_month",
7002
+ "schema": {
7003
+ "type": "string",
7004
+ "enum": [
7005
+ "today",
7006
+ "this_week",
7007
+ "last_week",
7008
+ "this_month",
7009
+ "last_month"
7010
+ ],
7011
+ "description": "A named range instead of `from` and `to`, in UTC: `today`, `this_week` or `last_week` (weeks start on Monday), `this_month` or `last_month`. A current one ends now."
7012
+ }
7013
+ },
7014
+ {
7015
+ "name": "from",
7016
+ "in": "query",
7017
+ "type": "string",
7018
+ "required": false,
7019
+ "description": "The start of the range, in ISO 8601.",
7020
+ "example": "2026-10-01T00:00:00Z",
7021
+ "schema": {
7022
+ "type": "string",
7023
+ "format": "date-time",
7024
+ "description": "The start of the range, in ISO 8601."
7025
+ }
7026
+ },
7027
+ {
7028
+ "name": "to",
7029
+ "in": "query",
7030
+ "type": "string",
7031
+ "required": false,
7032
+ "description": "The end of the range, in ISO 8601. Default: now.",
7033
+ "example": "2026-11-01T00:00:00Z",
7034
+ "schema": {
7035
+ "type": "string",
7036
+ "format": "date-time",
7037
+ "description": "The end of the range, in ISO 8601. Default: now."
7038
+ }
7039
+ },
7040
+ {
7041
+ "name": "sort",
7042
+ "in": "query",
7043
+ "type": "string",
7044
+ "required": false,
7045
+ "description": "`used` lists each limit's most used subjects first, and `refused` only its refused subjects, the most refused first. Default: used.",
7046
+ "schema": {
7047
+ "type": "string",
7048
+ "enum": [
7049
+ "used",
7050
+ "refused"
7051
+ ],
7052
+ "default": "used",
7053
+ "description": "`used` lists each limit's most used subjects first, and `refused` only its refused subjects, the most refused first. Default: used."
7054
+ }
7055
+ },
7056
+ {
7057
+ "name": "top",
7058
+ "in": "query",
7059
+ "type": "number",
7060
+ "required": false,
7061
+ "description": "How many subjects to list for each limit, up to 20. Default: 5.",
7062
+ "schema": {
7063
+ "type": [
7064
+ "integer",
7065
+ "null"
7066
+ ],
7067
+ "minimum": 0,
7068
+ "maximum": 20,
7069
+ "default": 5,
7070
+ "description": "How many subjects to list for each limit, up to 20. Default: 5."
7071
+ }
7072
+ }
7073
+ ],
7074
+ "hasBody": false,
7075
+ "workspace": true,
7076
+ "acceptsApiKey": true,
7077
+ "scope": "limits:read"
7078
+ },
6917
7079
  {
6918
7080
  "operationId": "usage.query",
6919
7081
  "method": "get",
@@ -6933,18 +7095,31 @@ var OPERATIONS = [
6933
7095
  "idempotentHint": true
6934
7096
  }
6935
7097
  },
6936
- "description": "Returns one limit's usage over time: the units used, and the checks allowed and refused. It covers every subject, or one subject named in `subject` as `kind:id`. Usage comes in hourly or daily buckets in UTC, and the response includes every bucket in the range. It can be up to about a minute behind live checks. By default, it covers the last 30 days, by day. A request returns at most 2,000 buckets. Usage older than your plan's history isn't returned.",
7098
+ "description": "Returns one limit's usage over time: the units used, and the checks allowed and refused, with the range's `total` beside the buckets. It covers every subject, or one subject named in `subject` as `kind:id`. Name the limit by `limitId` or `limitName`. Choose the range with `period` (such as `last_month`) or `from` and `to`. Usage comes in hourly or daily buckets in UTC, and the response includes every bucket in the range. It can be up to about a minute behind live checks. By default, it covers the last 30 days, by day. A request returns at most 2,000 buckets. Usage older than your plan's history isn't returned.",
6937
7099
  "fields": [
6938
7100
  {
6939
7101
  "name": "limitId",
6940
7102
  "in": "query",
6941
7103
  "type": "string",
6942
- "required": true,
6943
- "description": "The limit's ID.",
7104
+ "required": false,
7105
+ "description": "The limit's ID. Send this or `limitName`.",
6944
7106
  "example": "lmt_6f1c2a9e-4b7d-4e3a-9c5f-8d2b1a0e7c34",
6945
7107
  "schema": {
6946
7108
  "type": "string",
6947
- "description": "The limit's ID."
7109
+ "description": "The limit's ID. Send this or `limitName`."
7110
+ }
7111
+ },
7112
+ {
7113
+ "name": "limitName",
7114
+ "in": "query",
7115
+ "type": "string",
7116
+ "required": false,
7117
+ "description": "The limit's name, instead of its ID. It matches an active limit in this environment, exactly or else ignoring case.",
7118
+ "example": "AI budget",
7119
+ "schema": {
7120
+ "type": "string",
7121
+ "maxLength": 200,
7122
+ "description": "The limit's name, instead of its ID. It matches an active limit in this environment, exactly or else ignoring case."
6948
7123
  }
6949
7124
  },
6950
7125
  {
@@ -6961,6 +7136,25 @@ var OPERATIONS = [
6961
7136
  "description": "One subject, as `kind:id`, to see its usage instead of every subject's."
6962
7137
  }
6963
7138
  },
7139
+ {
7140
+ "name": "period",
7141
+ "in": "query",
7142
+ "type": "string",
7143
+ "required": false,
7144
+ "description": "A named range instead of `from` and `to`, in UTC: `today`, `this_week` or `last_week` (weeks start on Monday), `this_month` or `last_month`. A current one ends now.",
7145
+ "example": "last_month",
7146
+ "schema": {
7147
+ "type": "string",
7148
+ "enum": [
7149
+ "today",
7150
+ "this_week",
7151
+ "last_week",
7152
+ "this_month",
7153
+ "last_month"
7154
+ ],
7155
+ "description": "A named range instead of `from` and `to`, in UTC: `today`, `this_week` or `last_week` (weeks start on Monday), `this_month` or `last_month`. A current one ends now."
7156
+ }
7157
+ },
6964
7158
  {
6965
7159
  "name": "from",
6966
7160
  "in": "query",
@@ -6980,7 +7174,7 @@ var OPERATIONS = [
6980
7174
  "type": "string",
6981
7175
  "required": false,
6982
7176
  "description": "The end of the range, in ISO 8601. Default: now.",
6983
- "example": "2026-10-31T00:00:00Z",
7177
+ "example": "2026-11-01T00:00:00Z",
6984
7178
  "schema": {
6985
7179
  "type": "string",
6986
7180
  "format": "date-time",
@@ -7066,7 +7260,7 @@ var OPERATIONS = [
7066
7260
  "operationId": "usage.subjects",
7067
7261
  "method": "get",
7068
7262
  "path": "/usage/subjects",
7069
- "summary": "List who is using a limit now",
7263
+ "summary": "List who is using a limit",
7070
7264
  "cli": {
7071
7265
  "command": "usage subjects",
7072
7266
  "args": [],
@@ -7081,18 +7275,92 @@ var OPERATIONS = [
7081
7275
  "idempotentHint": true
7082
7276
  }
7083
7277
  },
7084
- "description": "Lists a limit's subjects in its current window, most used first. Each one shows the units used, what's left and how many checks the limit refused. The amounts are exact, but a subject first checked in the last minute may not appear yet. For a `concurrent` limit, it lists the slots each subject holds now, among the subjects checked in the last hour.",
7278
+ "description": "Lists a limit's subjects in its current window, most used first. Each one shows the units used, what's left and how many checks the limit refused. The amounts are exact, but a subject first checked in the last minute may not appear yet. For a `concurrent` limit, it lists the slots each subject holds now, among the subjects checked in the last hour. Name the limit by `limitId` or `limitName`. For a past range, send `period`, such as `last_month`, or `from` and `to`. The subjects are then ranked by their use in that range, from history. Each one's `remaining` is then null. Set `sort` to `refused` to list the most refused first. The current window is whole on every plan. A past range reaches no further back than your plan's history.",
7085
7279
  "fields": [
7086
7280
  {
7087
7281
  "name": "limitId",
7088
7282
  "in": "query",
7089
7283
  "type": "string",
7090
- "required": true,
7091
- "description": "The limit's ID.",
7284
+ "required": false,
7285
+ "description": "The limit's ID. Send this or `limitName`.",
7092
7286
  "example": "lmt_6f1c2a9e-4b7d-4e3a-9c5f-8d2b1a0e7c34",
7093
7287
  "schema": {
7094
7288
  "type": "string",
7095
- "description": "The limit's ID."
7289
+ "description": "The limit's ID. Send this or `limitName`."
7290
+ }
7291
+ },
7292
+ {
7293
+ "name": "limitName",
7294
+ "in": "query",
7295
+ "type": "string",
7296
+ "required": false,
7297
+ "description": "The limit's name, instead of its ID. It matches an active limit in this environment, exactly or else ignoring case.",
7298
+ "example": "AI budget",
7299
+ "schema": {
7300
+ "type": "string",
7301
+ "maxLength": 200,
7302
+ "description": "The limit's name, instead of its ID. It matches an active limit in this environment, exactly or else ignoring case."
7303
+ }
7304
+ },
7305
+ {
7306
+ "name": "period",
7307
+ "in": "query",
7308
+ "type": "string",
7309
+ "required": false,
7310
+ "description": "A named range instead of `from` and `to`, in UTC: `today`, `this_week` or `last_week` (weeks start on Monday), `this_month` or `last_month`. A current one ends now.",
7311
+ "example": "last_month",
7312
+ "schema": {
7313
+ "type": "string",
7314
+ "enum": [
7315
+ "today",
7316
+ "this_week",
7317
+ "last_week",
7318
+ "this_month",
7319
+ "last_month"
7320
+ ],
7321
+ "description": "A named range instead of `from` and `to`, in UTC: `today`, `this_week` or `last_week` (weeks start on Monday), `this_month` or `last_month`. A current one ends now."
7322
+ }
7323
+ },
7324
+ {
7325
+ "name": "from",
7326
+ "in": "query",
7327
+ "type": "string",
7328
+ "required": false,
7329
+ "description": "The start of the range, in ISO 8601.",
7330
+ "example": "2026-10-01T00:00:00Z",
7331
+ "schema": {
7332
+ "type": "string",
7333
+ "format": "date-time",
7334
+ "description": "The start of the range, in ISO 8601."
7335
+ }
7336
+ },
7337
+ {
7338
+ "name": "to",
7339
+ "in": "query",
7340
+ "type": "string",
7341
+ "required": false,
7342
+ "description": "The end of the range, in ISO 8601. Default: now.",
7343
+ "example": "2026-11-01T00:00:00Z",
7344
+ "schema": {
7345
+ "type": "string",
7346
+ "format": "date-time",
7347
+ "description": "The end of the range, in ISO 8601. Default: now."
7348
+ }
7349
+ },
7350
+ {
7351
+ "name": "sort",
7352
+ "in": "query",
7353
+ "type": "string",
7354
+ "required": false,
7355
+ "description": "`used` lists the most used first, and `refused` the most refused first. Default: used.",
7356
+ "schema": {
7357
+ "type": "string",
7358
+ "enum": [
7359
+ "used",
7360
+ "refused"
7361
+ ],
7362
+ "default": "used",
7363
+ "description": "`used` lists the most used first, and `refused` the most refused first. Default: used."
7096
7364
  }
7097
7365
  },
7098
7366
  {
@@ -7651,7 +7919,7 @@ var OPERATIONS = [
7651
7919
  "idempotentHint": true
7652
7920
  }
7653
7921
  },
7654
- "description": "Returns what the workspace used this period, with one entry for each thing its plan counts. Each entry has the plan's limit, or null when there is no limit. A period is one month from the workspace's billing date. That date comes from its subscription or, without one, from the day you created the workspace. On an annual plan, the counts still reset every month from the subscription's start.",
7922
+ "description": "Returns what the workspace used this period, with one entry for each thing its plan counts. Each entry has the plan's limit, or null when there is no limit. Each entry also says where it stands and where we start refusing new use. A period is one month from the workspace's billing date. That date comes from its subscription or, without one, from the day you created the workspace. On an annual plan, the counts still reset every month from the subscription's start.",
7655
7923
  "fields": [],
7656
7924
  "hasBody": false,
7657
7925
  "workspace": true,
@@ -7679,7 +7947,7 @@ var OPERATIONS = [
7679
7947
  "idempotentHint": true
7680
7948
  }
7681
7949
  },
7682
- "description": "Lists one endpoint's delivery history, newest first. Each entry shows the event's status, attempts and last HTTP status. Payloads aren't included. We keep the history for 30 days. Paginate with the opaque `nextCursor`. `before` starts from a moment, and `status` keeps one kind of delivery. With a personal access token, only workspace owners can call this. A workspace API key with this scope can.",
7950
+ "description": "Lists one endpoint's delivery history, newest first. Each entry shows the event's status, attempts and last HTTP status. Payloads aren't included. We keep the history for 30 days. Paginate with the opaque `nextCursor`. `before` starts from a moment, and `status` keeps one kind of delivery. With a personal access token, only the workspace owner can call this. So can an admin in a Developer seat. A workspace API key with this scope can.",
7683
7951
  "fields": [
7684
7952
  {
7685
7953
  "name": "endpointId",
@@ -7777,7 +8045,7 @@ var OPERATIONS = [
7777
8045
  "idempotentHint": false
7778
8046
  }
7779
8047
  },
7780
- "description": "Sends a recorded delivery's event again, as a new delivery. The new delivery gets its own history entry. The event id stays the same, so receivers can deduplicate. Redelivery only works on an enabled endpoint. With a personal access token, only workspace owners can call this. A workspace API key with this scope can.",
8048
+ "description": "Sends a recorded delivery's event again, as a new delivery. The new delivery gets its own history entry. The event id stays the same, so receivers can deduplicate. Redelivery only works on an enabled endpoint. With a personal access token, only the workspace owner can call this. So can an admin in a Developer seat. A workspace API key with this scope can.",
7781
8049
  "fields": [
7782
8050
  {
7783
8051
  "name": "endpointId",
@@ -7823,7 +8091,7 @@ var OPERATIONS = [
7823
8091
  "exposed": false,
7824
8092
  "reason": "Changes where workspace data is sent. A person configures webhook endpoints (Settings \u2192 Developers in the app)."
7825
8093
  },
7826
- "description": "Registers an HTTPS URL to receive the workspace's events. Deliveries use the same signature format as Svix. The response includes the endpoint's signing secret (`whsec_\u2026`). You see it only once, so store it to verify deliveries. The API refuses private hosts and hosts without HTTPS. A workspace can have at most 10 endpoints. With a personal access token, only workspace owners can call this. A workspace API key with this scope can.",
8094
+ "description": "Registers an HTTPS URL to receive the workspace's events. Deliveries use the same signature format as Svix. The response includes the endpoint's signing secret (`whsec_\u2026`). You see it only once, so store it to verify deliveries. The API refuses private hosts and hosts without HTTPS. A workspace can have at most 10 endpoints. With a personal access token, only the workspace owner can call this. So can an admin in a Developer seat. A workspace API key with this scope can.",
7827
8095
  "fields": [
7828
8096
  {
7829
8097
  "name": "url",
@@ -7891,7 +8159,7 @@ var OPERATIONS = [
7891
8159
  "exposed": false,
7892
8160
  "reason": "Changes where workspace data is sent. A person configures webhook endpoints (Settings \u2192 Developers in the app)."
7893
8161
  },
7894
- "description": "Deletes the endpoint and its signing secret. All deliveries to the endpoint stop. Its delivery history goes with it. With a personal access token, only workspace owners can call this. A workspace API key with this scope can.",
8162
+ "description": "Deletes the endpoint and its signing secret. All deliveries to the endpoint stop. Its delivery history goes with it. With a personal access token, only the workspace owner can call this. So can an admin in a Developer seat. A workspace API key with this scope can.",
7895
8163
  "fields": [
7896
8164
  {
7897
8165
  "name": "endpointId",
@@ -7927,7 +8195,7 @@ var OPERATIONS = [
7927
8195
  "exposed": false,
7928
8196
  "reason": "Changes where workspace data is sent. A person configures webhook endpoints (Settings \u2192 Developers in the app)."
7929
8197
  },
7930
- "description": "Resumes deliveries to an endpoint that stopped after repeated failures. The endpoint keeps its signing secret. Its failure count resets. With a personal access token, only workspace owners can call this. A workspace API key with this scope can.",
8198
+ "description": "Resumes deliveries to an endpoint that stopped after repeated failures. The endpoint keeps its signing secret. Its failure count resets. With a personal access token, only the workspace owner can call this. So can an admin in a Developer seat. A workspace API key with this scope can.",
7931
8199
  "fields": [
7932
8200
  {
7933
8201
  "name": "endpointId",
@@ -7968,7 +8236,7 @@ var OPERATIONS = [
7968
8236
  "idempotentHint": true
7969
8237
  }
7970
8238
  },
7971
- "description": "Returns one endpoint without its signing secret. It shows whether the endpoint is on, its consecutive failures and its last delivery status. With a personal access token, only workspace owners can call this. A workspace API key with this scope can.",
8239
+ "description": "Returns one endpoint without its signing secret. It shows whether the endpoint is on, its consecutive failures and its last delivery status. With a personal access token, only the workspace owner can call this. So can an admin in a Developer seat. A workspace API key with this scope can.",
7972
8240
  "fields": [
7973
8241
  {
7974
8242
  "name": "endpointId",
@@ -8007,7 +8275,7 @@ var OPERATIONS = [
8007
8275
  "idempotentHint": true
8008
8276
  }
8009
8277
  },
8010
- "description": "Lists the workspace's outgoing webhook endpoints, newest first. The list leaves out their signing secrets. A workspace has at most 10 endpoints, so the list is a single page. Its `nextCursor` is null. With a personal access token, only workspace owners can call this. A workspace API key with this scope can.",
8278
+ "description": "Lists the workspace's outgoing webhook endpoints, newest first. The list leaves out their signing secrets. A workspace has at most 10 endpoints, so the list is a single page. Its `nextCursor` is null. With a personal access token, only the workspace owner can call this. So can an admin in a Developer seat. A workspace API key with this scope can.",
8011
8279
  "fields": [],
8012
8280
  "hasBody": false,
8013
8281
  "workspace": true,
@@ -8035,7 +8303,7 @@ var OPERATIONS = [
8035
8303
  "idempotentHint": false
8036
8304
  }
8037
8305
  },
8038
- "description": "Sends a `ping` event to the endpoint, signed like every delivery. Use it to check that an integration verifies and accepts deliveries. With a personal access token, only workspace owners can call this. A workspace API key with this scope can.",
8306
+ "description": "Sends a `ping` event to the endpoint, signed like every delivery. Use it to check that an integration verifies and accepts deliveries. With a personal access token, only the workspace owner can call this. So can an admin in a Developer seat. A workspace API key with this scope can.",
8039
8307
  "fields": [
8040
8308
  {
8041
8309
  "name": "endpointId",
@@ -8071,7 +8339,7 @@ var OPERATIONS = [
8071
8339
  "exposed": false,
8072
8340
  "reason": "Changes where workspace data is sent. A person configures webhook endpoints (Settings \u2192 Developers in the app)."
8073
8341
  },
8074
- "description": "Changes an endpoint's URL, description or event types in place. Only the fields you send change. The endpoint keeps its signing secret, so receivers keep verifying deliveries. A new URL must pass the same checks as on create. It must use HTTPS and can't be a private host. With a personal access token, only workspace owners can call this. A workspace API key with this scope can.",
8342
+ "description": "Changes an endpoint's URL, description or event types in place. Only the fields you send change. The endpoint keeps its signing secret, so receivers keep verifying deliveries. A new URL must pass the same checks as on create. It must use HTTPS and can't be a private host. With a personal access token, only the workspace owner can call this. So can an admin in a Developer seat. A workspace API key with this scope can.",
8075
8343
  "fields": [
8076
8344
  {
8077
8345
  "name": "endpointId",
@@ -8291,6 +8559,8 @@ async function call2(ctx, op, args, options, flags) {
8291
8559
  `missing ${missing.map((f) => `--${flag(f.name)}`).join(", ")}`
8292
8560
  );
8293
8561
  }
8562
+ const problem = variantProblem(op, input, whole);
8563
+ if (problem) throw new Error(problem);
8294
8564
  const request = operationRequest(op, input, whole);
8295
8565
  const headers = {
8296
8566
  authorization: `Bearer ${token}`
@@ -8362,6 +8632,19 @@ function print(ctx, data, asJson) {
8362
8632
  }
8363
8633
  ctx.io.stdout(String(data));
8364
8634
  }
8635
+ function variantProblem(op, input, whole) {
8636
+ if (!op.variants) return void 0;
8637
+ const key = op.variants.field;
8638
+ const chosen = String(input[key] ?? whole[key]);
8639
+ const needs = op.variants.required[chosen];
8640
+ if (!needs) {
8641
+ return `--${flag(key)} must be one of ${Object.keys(op.variants.required).join(", ")}`;
8642
+ }
8643
+ const absent = needs.filter(
8644
+ (name) => input[name] === void 0 && whole[name] === void 0
8645
+ );
8646
+ return absent.length > 0 ? `missing ${absent.map((name) => `--${flag(name)}`).join(", ")} (needed with --${flag(key)} ${chosen})` : void 0;
8647
+ }
8365
8648
 
8366
8649
  // src/product/check.ts
8367
8650
  var checkCommand = (program2, ctx) => {
@@ -8559,7 +8842,7 @@ function tokenEnvVar() {
8559
8842
  function build(io) {
8560
8843
  let actedIn = null;
8561
8844
  let sending;
8562
- const program2 = new Command().name(brand.name).description(`The ${brand.productName} CLI`).version("1.0.0-rc.13").addHelpText(
8845
+ const program2 = new Command().name(brand.name).description(`The ${brand.productName} CLI`).version("1.0.0-rc.15").addHelpText(
8563
8846
  "after",
8564
8847
  `
8565
8848
  Token: \`${brand.name} login\` stores it in ~/.config/${brand.name}/; ${tokenEnvVar()} overrides.
package/package.json CHANGED
@@ -1,7 +1,16 @@
1
1
  {
2
2
  "name": "@limitry/cli",
3
- "version": "1.0.0-rc.13",
3
+ "version": "1.0.0-rc.15",
4
4
  "description": "Limitry command line",
5
+ "keywords": [
6
+ "usage-limits",
7
+ "rate-limiting",
8
+ "credits",
9
+ "budgets",
10
+ "quotas",
11
+ "cli",
12
+ "command-line-tool"
13
+ ],
5
14
  "type": "module",
6
15
  "bin": {
7
16
  "limitry": "./dist/limitry.mjs"
@@ -17,9 +26,9 @@
17
26
  "typecheck": "tsc --noEmit"
18
27
  },
19
28
  "devDependencies": {
20
- "@limitry/sdk": "1.0.0-rc.13",
29
+ "@limitry/sdk": "1.0.0-rc.15",
21
30
  "@types/node": "26.6.6",
22
- "commander": "15.0.0",
31
+ "commander": "15.1.0",
23
32
  "esbuild": "0.28.2",
24
33
  "typescript": "6.0.3",
25
34
  "vitest": "4.1.12"