@airctrl/cli 0.3.0 → 0.5.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
@@ -14,6 +14,29 @@ npm install --global @airctrl/cli
14
14
 
15
15
  Requires Node.js 22.x.
16
16
 
17
+ ## Current release
18
+
19
+ **Coordinated package version:** `0.5.0`
20
+
21
+ ### SDK
22
+
23
+ - Added privileged full-text gateway log search, HTTP status-family filtering, and gateway-scoped usage metrics and spend inputs.
24
+ - Added native connection URLs for Groq, Novita AI, Atlas Cloud, and xAI to the shared gateway connection builder.
25
+ - Added pricing display text and structured rate-card tiers so provider-published zero and context-tiered rates remain explicit.
26
+
27
+ ### CLI
28
+
29
+ - Added gateway log `--search` and `--status-class` filters plus gateway-scoped usage metrics and spend flags.
30
+
31
+ ### MCP
32
+
33
+ - Added the same gateway log search and scoped metrics inputs to `read_usage`, `read_usage_metrics`, and `read_usage_spend`.
34
+
35
+ ### Release engineering
36
+
37
+ - Coordinated SDK, CLI, MCP, Web, and Authenticator package references at `0.5.0` so clean builds consume the exact release candidate instead of the previously published SDK.
38
+ - Retained sealed-candidate certification and manual npm publication with final approval and 2FA.
39
+
17
40
  ## CLI overview
18
41
 
19
42
  `@airctrl/cli` lets you work with AIRCTRL from a terminal and inject records into a process without creating a local `.env` file.
@@ -183,12 +206,14 @@ airctrl record list [--account <id>] [--project <id>] [--tab owned|shared]
183
206
  [--include-archived true|false] [--limit <n>] [--offset <n>]
184
207
  airctrl record versions <recordId>
185
208
  airctrl record audit <recordId> [--limit <n>]
209
+ airctrl record audit-events <recordId> [--cursor <opaque>] [--action <name>] [--actor <text>]
210
+ [--from <iso>] [--to <iso>] [--limit <n>] [--offset <legacy-n>]
186
211
  airctrl record anomalies [--account <id>] [--scope-type user|project] [--scope-id <id>]
187
212
  airctrl record activity <YYYY-MM-DD> [--account <id>] [--scope-type user|project] [--scope-id <id>]
188
213
  airctrl record alerts [--account <id>] [--scope-type user|project] [--scope-id <id>]
189
- [--limit <n>] [--offset <n>]
214
+ [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
190
215
  airctrl record access [--account <id>] [--scope-type user|project] [--scope-id <id>]
191
- [--actions a,b] [--limit <n>] [--offset <n>]
216
+ [--actions a,b] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
192
217
  airctrl record metadata <recordId> [--name <name>] [--tags a,b|none]
193
218
  [--env development|staging|production] [--secret-due <iso|null>] [--rotation-days <n|null>]
194
219
  airctrl record archive <recordId>
@@ -257,23 +282,32 @@ airctrl gateway provider-credential-update <credentialId> --account <id> --label
257
282
  airctrl gateway provider-credential-revoke <credentialId> --account <id>
258
283
  ```
259
284
 
285
+ `gateway provider-models` includes current official pricing for each discovered model. Numeric token
286
+ rates use USD per one million tokens; `displayText` and `rateCard` preserve provider-published zero
287
+ and context-tiered policies.
288
+
260
289
  Observability:
261
290
 
262
291
  ```text
263
292
  airctrl gateway logs <gatewayId> [--since <iso>] [--provider <id>] [--model <name>]
264
- [--status <code>] [--limit <n>] [--offset <n>]
293
+ [--status <code>] [--status-class 2xx|4xx|5xx|other] [--search <keywords>]
294
+ [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
265
295
  airctrl gateway log <gatewayId> <logId>
266
296
  airctrl gateway key-access <gatewayId> [--outcome granted|denied|error]
267
- [--since <iso>] [--limit <n>] [--offset <n>]
297
+ [--since <iso>] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
268
298
  airctrl gateway usage-logs --project <id> [--since <iso>] [--provider <id>]
269
- [--model <name>] [--status <code>] [--gateway <id>] [--limit <n>] [--offset <n>]
299
+ [--model <name>] [--status <code>] [--gateway <id>] [--cursor <opaque>]
300
+ [--limit <n>] [--offset <legacy-n>]
270
301
  airctrl gateway usage-log <logId> --project <id>
271
- airctrl gateway usage-spend --project <id>
302
+ airctrl gateway usage-spend --project <id> [--gateway <id>]
272
303
  airctrl gateway usage-metrics --project <id> [--since <iso>] [--bucket hour|day]
304
+ [--gateway <id>] [--provider <slug>] [--model <name>]
305
+ [--status-class 2xx|4xx|5xx|other] [--search <keywords>]
273
306
  airctrl gateway otel <gatewayId> --account <id>
274
307
  airctrl gateway otel-update <gatewayId> --account <id>
275
308
  [--enabled true|false] [--endpoint <url|null>] [--metrics true|false]
276
- [--traces true|false] [--headers-env <variable>] [--clear-headers true|false]
309
+ [--traces true|false] [--bodies true|false]
310
+ [--headers-env <variable>] [--clear-headers true|false]
277
311
  ```
278
312
 
279
313
  Provider credentials and OpenTelemetry headers are read from named environment variables. Their values do not belong in command arguments.
@@ -425,6 +459,19 @@ airctrl get "$RECORD_ID" --profile ci
425
459
  airctrl gateway logs "$GATEWAY_ID" --profile ci
426
460
  ```
427
461
 
462
+ ### OAuth partner Apps
463
+
464
+ The CLI has no OAuth App profile, authorization-code flow, or connection/protection lifecycle
465
+ commands. Do not place OAuth client secrets, authorization codes, access tokens, or refresh tokens in
466
+ its PAT/Service Account profiles or shell history. Those values belong in a confidential partner
467
+ backend.
468
+
469
+ Implement OAuth partner flows through the standards-based direct HTTP contract or
470
+ `OAuthPartnerClient`. See [OAuth partner integrations](https://docs.airctrl.dev/guides/oauth-partner-integrations),
471
+ [OAuth protocol](https://docs.airctrl.dev/reference/oauth-protocol), and
472
+ [OAuth protection API](https://docs.airctrl.dev/reference/oauth-protections). The CLI may still manage ordinary gateways with
473
+ a separately authorized human PAT; that is not the OAuth installation identity.
474
+
428
475
  ### CLI failures
429
476
 
430
477
  | Code or condition | Meaning | What to do |
@@ -834,6 +881,21 @@ airctrl record audit "$RECORD_ID" --limit 25
834
881
 
835
882
 
836
883
 
884
+ #### Page and filter one record's audit history
885
+
886
+ ```bash
887
+ airctrl record audit-events "$RECORD_ID" --action record.update --actor david --limit 25
888
+ # Continue with pagination.next_cursor from the previous JSON response.
889
+ airctrl record audit-events "$RECORD_ID" --action record.update --actor david \
890
+ --limit 25 --cursor "$NEXT_CURSOR"
891
+ ```
892
+
893
+
894
+
895
+ **CLI command:** `airctrl record audit-events`
896
+
897
+
898
+
837
899
  #### Find unusual record activity
838
900
 
839
901
 
@@ -1695,7 +1757,11 @@ Returns request metadata. Service Accounts may use this read when their role per
1695
1757
 
1696
1758
  ```bash
1697
1759
  airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z \
1698
- --status 200 --limit 50 --offset 0
1760
+ --status 200 --limit 50
1761
+
1762
+ # Continue with pagination.next_cursor from the previous JSON response.
1763
+ airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z \
1764
+ --status 200 --limit 50 --cursor "$NEXT_CURSOR"
1699
1765
  ```
1700
1766
 
1701
1767
 
@@ -1751,7 +1817,11 @@ Returns usage metadata across the selected project.
1751
1817
 
1752
1818
  ```bash
1753
1819
  airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
1754
- --since 2026-09-01T00:00:00Z --limit 50 --offset 0
1820
+ --since 2026-09-01T00:00:00Z --limit 50
1821
+
1822
+ # Keep the exact same filters when continuing a cursor.
1823
+ airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
1824
+ --since 2026-09-01T00:00:00Z --limit 50 --cursor "$NEXT_CURSOR"
1755
1825
  ```
1756
1826
 
1757
1827
 
@@ -1843,8 +1913,9 @@ The CLI reads header values from the named environment variable. Use `--clear-he
1843
1913
 
1844
1914
  ```bash
1845
1915
  airctrl gateway otel-update "$GATEWAY_ID" --account "$ACCOUNT_ID" \
1846
- --enabled true --endpoint https://otel.example.com/v1/traces \
1847
- --metrics true --traces true --headers-env OTEL_EXPORT_HEADERS
1916
+ --enabled true --endpoint https://otel.example.com \
1917
+ --metrics true --traces true --bodies true \
1918
+ --headers-env OTEL_EXPORT_HEADERS
1848
1919
  ```
1849
1920
 
1850
1921
 
@@ -81,16 +81,16 @@ export const GATEWAY_SPECS = {
81
81
  },
82
82
  logs: {
83
83
  positionals: ['gatewayId'],
84
- flags: ['since', 'provider', 'model', 'status', 'limit', 'offset', ...profile],
84
+ flags: ['since', 'provider', 'model', 'status', 'status-class', 'search', 'cursor', 'limit', 'offset', ...profile],
85
85
  },
86
86
  log: { positionals: ['gatewayId', 'logId'], flags: profile },
87
87
  'key-access': {
88
88
  positionals: ['gatewayId'],
89
- flags: ['outcome', 'since', 'limit', 'offset', ...profile],
89
+ flags: ['outcome', 'since', 'cursor', 'limit', 'offset', ...profile],
90
90
  },
91
91
  'usage-logs': {
92
92
  positionals: [],
93
- flags: ['project', 'since', 'provider', 'model', 'status', 'gateway', 'limit', 'offset', ...profile],
93
+ flags: ['project', 'since', 'provider', 'model', 'status', 'gateway', 'cursor', 'limit', 'offset', ...profile],
94
94
  requiredFlags: ['project'],
95
95
  },
96
96
  'usage-log': {
@@ -100,12 +100,12 @@ export const GATEWAY_SPECS = {
100
100
  },
101
101
  'usage-spend': {
102
102
  positionals: [],
103
- flags: ['project', ...profile],
103
+ flags: ['project', 'gateway', ...profile],
104
104
  requiredFlags: ['project'],
105
105
  },
106
106
  'usage-metrics': {
107
107
  positionals: [],
108
- flags: ['project', 'since', 'bucket', ...profile],
108
+ flags: ['project', 'since', 'bucket', 'gateway', 'provider', 'model', 'status-class', 'search', ...profile],
109
109
  requiredFlags: ['project'],
110
110
  },
111
111
  otel: {
@@ -115,7 +115,7 @@ export const GATEWAY_SPECS = {
115
115
  },
116
116
  'otel-update': {
117
117
  positionals: ['gatewayId'],
118
- flags: ['account', 'enabled', 'endpoint', 'metrics', 'traces', 'headers-env', 'clear-headers', ...profile],
118
+ flags: ['account', 'enabled', 'endpoint', 'metrics', 'traces', 'bodies', 'headers-env', 'clear-headers', ...profile],
119
119
  requiredFlags: ['account'],
120
120
  },
121
121
  'provider-credentials': {
@@ -389,6 +389,9 @@ export async function runGatewayCommand(argv, deps) {
389
389
  provider: parsed.flags.provider,
390
390
  model: parsed.flags.model,
391
391
  status: numberFlag(parsed.flags.status, true, 100, 599),
392
+ statusClass: enumFlag(parsed.flags['status-class'], ['2xx', '4xx', '5xx', 'other']),
393
+ search: parsed.flags.search,
394
+ cursor: parsed.flags.cursor,
392
395
  limit: numberFlag(parsed.flags.limit, true, 1, 200),
393
396
  offset: numberFlag(parsed.flags.offset, true),
394
397
  });
@@ -400,6 +403,7 @@ export async function runGatewayCommand(argv, deps) {
400
403
  result = await client.listGatewayKeyAccess(id, {
401
404
  outcome: enumFlag(parsed.flags.outcome, ['granted', 'denied', 'error']),
402
405
  since: parsed.flags.since,
406
+ cursor: parsed.flags.cursor,
403
407
  limit: numberFlag(parsed.flags.limit, true, 1, 200),
404
408
  offset: numberFlag(parsed.flags.offset, true),
405
409
  });
@@ -412,6 +416,7 @@ export async function runGatewayCommand(argv, deps) {
412
416
  model: parsed.flags.model,
413
417
  status: numberFlag(parsed.flags.status, true, 100, 599),
414
418
  gatewayId: parsed.flags.gateway,
419
+ cursor: parsed.flags.cursor,
415
420
  limit: numberFlag(parsed.flags.limit, true, 1, 200),
416
421
  offset: numberFlag(parsed.flags.offset, true),
417
422
  });
@@ -420,12 +425,19 @@ export async function runGatewayCommand(argv, deps) {
420
425
  result = await client.getUsageLogDetail(parsed.flags.project, id);
421
426
  break;
422
427
  case 'usage-spend':
423
- result = await client.getUsageSpend(parsed.flags.project);
428
+ result = parsed.flags.gateway
429
+ ? await client.getUsageSpend(parsed.flags.project, parsed.flags.gateway)
430
+ : await client.getUsageSpend(parsed.flags.project);
424
431
  break;
425
432
  case 'usage-metrics':
426
433
  result = await client.getUsageMetrics(parsed.flags.project, {
427
434
  since: parsed.flags.since,
428
435
  bucket: enumFlag(parsed.flags.bucket, ['hour', 'day']),
436
+ gatewayId: parsed.flags.gateway,
437
+ provider: parsed.flags.provider,
438
+ model: parsed.flags.model,
439
+ statusClass: enumFlag(parsed.flags['status-class'], ['2xx', '4xx', '5xx', 'other']),
440
+ search: parsed.flags.search,
429
441
  });
430
442
  break;
431
443
  case 'otel':
@@ -441,6 +453,8 @@ export async function runGatewayCommand(argv, deps) {
441
453
  patch.exportMetrics = booleanFlag(parsed.flags.metrics);
442
454
  if (parsed.flags.traces !== undefined)
443
455
  patch.exportTraces = booleanFlag(parsed.flags.traces);
456
+ if (parsed.flags.bodies !== undefined)
457
+ patch.exportBodies = booleanFlag(parsed.flags.bodies);
444
458
  const headers = headersFromEnv(parsed.flags['headers-env'], booleanFlag(parsed.flags['clear-headers']), deps.env ?? process.env);
445
459
  if (headers !== undefined)
446
460
  patch.headers = headers;
@@ -8,6 +8,10 @@ export const RECORD_SPECS = {
8
8
  },
9
9
  versions: { positionals: ['recordId'], flags: profile },
10
10
  audit: { positionals: ['recordId'], flags: ['limit', ...profile] },
11
+ 'audit-events': {
12
+ positionals: ['recordId'],
13
+ flags: ['limit', 'offset', 'cursor', 'action', 'actor', 'from', 'to', ...profile],
14
+ },
11
15
  anomalies: { positionals: [], flags: ['account', 'scope-type', 'scope-id', ...profile] },
12
16
  activity: {
13
17
  positionals: ['day'],
@@ -15,11 +19,11 @@ export const RECORD_SPECS = {
15
19
  },
16
20
  alerts: {
17
21
  positionals: [],
18
- flags: ['account', 'scope-type', 'scope-id', 'limit', 'offset', ...profile],
22
+ flags: ['account', 'scope-type', 'scope-id', 'cursor', 'limit', 'offset', ...profile],
19
23
  },
20
24
  access: {
21
25
  positionals: [],
22
- flags: ['account', 'scope-type', 'scope-id', 'limit', 'offset', 'actions', ...profile],
26
+ flags: ['account', 'scope-type', 'scope-id', 'cursor', 'limit', 'offset', 'actions', ...profile],
23
27
  },
24
28
  metadata: {
25
29
  positionals: ['recordId'],
@@ -81,6 +85,7 @@ export const RECORD_USAGE = `airctrl record commands
81
85
 
82
86
  list [--project <id>] [--tab owned|shared] [--include-archived true|false]
83
87
  versions <recordId> | audit <recordId> [--limit <n>]
88
+ audit-events <recordId> [--cursor <opaque>] [--action <name>] [--actor <text>] [--from <iso>] [--to <iso>]
84
89
  anomalies | activity <YYYY-MM-DD> | alerts | access [--scope-type user|project]
85
90
  metadata <recordId> [--name <n>] [--tags a,b|none] [--secret-due <iso>|null] [--env development|staging|production]
86
91
  archive <recordId> | restore <recordId>
@@ -189,6 +194,17 @@ export async function runRecordCommand(argv, deps) {
189
194
  case 'audit':
190
195
  result = await client.getRecordAudit(recordId, integerFlag(parsed.flags.limit, 1));
191
196
  break;
197
+ case 'audit-events':
198
+ result = await client.listRecordAudit(recordId, {
199
+ limit: integerFlag(parsed.flags.limit, 1),
200
+ offset: integerFlag(parsed.flags.offset),
201
+ cursor: parsed.flags.cursor,
202
+ action: parsed.flags.action,
203
+ actor: parsed.flags.actor,
204
+ from: parsed.flags.from,
205
+ to: parsed.flags.to,
206
+ });
207
+ break;
192
208
  case 'anomalies':
193
209
  result = await client.listRecordAnomalies(auditScope(parsed));
194
210
  break;
@@ -198,6 +214,7 @@ export async function runRecordCommand(argv, deps) {
198
214
  case 'alerts':
199
215
  result = await client.listRecordAlerts({
200
216
  ...auditScope(parsed),
217
+ cursor: parsed.flags.cursor,
201
218
  limit: integerFlag(parsed.flags.limit, 1),
202
219
  offset: integerFlag(parsed.flags.offset),
203
220
  });
@@ -205,6 +222,7 @@ export async function runRecordCommand(argv, deps) {
205
222
  case 'access':
206
223
  result = await client.listRecordAccess({
207
224
  ...auditScope(parsed),
225
+ cursor: parsed.flags.cursor,
208
226
  limit: integerFlag(parsed.flags.limit, 1),
209
227
  offset: integerFlag(parsed.flags.offset),
210
228
  actions: tagsFlag(parsed.flags.actions),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@airctrl/cli",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "description": "AIRCTRL CLI for encrypted records, process injection, projects, gateways and Service Accounts.",
6
6
  "license": "UNLICENSED",
@@ -39,6 +39,6 @@
39
39
  "dev": "tsx src/index.ts"
40
40
  },
41
41
  "dependencies": {
42
- "@airctrl/sdk": "0.3.0"
42
+ "@airctrl/sdk": "0.5.0"
43
43
  }
44
44
  }