@airctrl/cli 0.3.0 → 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.
package/README.md CHANGED
@@ -14,6 +14,39 @@ 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.4.0`
20
+
21
+ ### SDK
22
+
23
+ - Added `OAuthPartnerClient`, PKCE generation, authorization-code exchange, rotating refresh tokens, and token revocation for confidential partner backends.
24
+ - Added provider resolution, provider-key validation, live model discovery, entitlement preflight, atomic protection provisioning, and installation-bound protection reads and updates.
25
+ - Added provider-key rotation, runtime-token rotation, revoke, and reactivate lifecycle operations with typed idempotency and error handling.
26
+ - Added public multi-organization OAuth Apps: one publisher-owned Client ID can create isolated installations inside customer-selected AIRCTRL organizations.
27
+ - Added `listProtectionLogs()` and `getProtectionSpend()` with dedicated least-privilege scopes and strict installation/protection binding.
28
+ - Added stable cursor pagination and canonical account, project, gateway, token, principal, trace, and span correlation across request-log, usage, and audit feeds.
29
+ - Added OpenTelemetry body-export controls and shared gateway connection types aligned with the public API contract.
30
+
31
+ ### CLI
32
+
33
+ - Added opaque cursor support to gateway logs, provider-key access, usage logs, record alerts, and record access commands.
34
+ - Added the `audit-events` command with cursor, action, actor, and date filters.
35
+ - Added OpenTelemetry request/response body-export configuration while preserving the existing header-custody contract.
36
+
37
+ ### MCP
38
+
39
+ - Added opaque cursor inputs to gateway, usage, record-alert, and record-access tools.
40
+ - Added `list_record_audit` with stable filters and pagination.
41
+ - Added OpenTelemetry body-export configuration and aligned pagination limits with the API contract.
42
+
43
+ ### Release engineering
44
+
45
+ - Kept SDK, CLI, and MCP manifests, internal dependencies, exported version constants, generated READMEs, and tarball names aligned at `0.4.0`.
46
+ - Build `@airctrl/client-contracts` before OpenAPI generation and full-stack certification so clean release runners never depend on cached workspace output.
47
+ - Expanded package verification across the public API, generated examples, installed-package behavior, exact tarballs, and Linux, Windows, and macOS certification.
48
+ - Kept `@airctrl/crypto` and `@airctrl/secrets` private and bundled the required runtime into the public SDK.
49
+
17
50
  ## CLI overview
18
51
 
19
52
  `@airctrl/cli` lets you work with AIRCTRL from a terminal and inject records into a process without creating a local `.env` file.
@@ -183,12 +216,14 @@ airctrl record list [--account <id>] [--project <id>] [--tab owned|shared]
183
216
  [--include-archived true|false] [--limit <n>] [--offset <n>]
184
217
  airctrl record versions <recordId>
185
218
  airctrl record audit <recordId> [--limit <n>]
219
+ airctrl record audit-events <recordId> [--cursor <opaque>] [--action <name>] [--actor <text>]
220
+ [--from <iso>] [--to <iso>] [--limit <n>] [--offset <legacy-n>]
186
221
  airctrl record anomalies [--account <id>] [--scope-type user|project] [--scope-id <id>]
187
222
  airctrl record activity <YYYY-MM-DD> [--account <id>] [--scope-type user|project] [--scope-id <id>]
188
223
  airctrl record alerts [--account <id>] [--scope-type user|project] [--scope-id <id>]
189
- [--limit <n>] [--offset <n>]
224
+ [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
190
225
  airctrl record access [--account <id>] [--scope-type user|project] [--scope-id <id>]
191
- [--actions a,b] [--limit <n>] [--offset <n>]
226
+ [--actions a,b] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
192
227
  airctrl record metadata <recordId> [--name <name>] [--tags a,b|none]
193
228
  [--env development|staging|production] [--secret-due <iso|null>] [--rotation-days <n|null>]
194
229
  airctrl record archive <recordId>
@@ -261,19 +296,21 @@ Observability:
261
296
 
262
297
  ```text
263
298
  airctrl gateway logs <gatewayId> [--since <iso>] [--provider <id>] [--model <name>]
264
- [--status <code>] [--limit <n>] [--offset <n>]
299
+ [--status <code>] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
265
300
  airctrl gateway log <gatewayId> <logId>
266
301
  airctrl gateway key-access <gatewayId> [--outcome granted|denied|error]
267
- [--since <iso>] [--limit <n>] [--offset <n>]
302
+ [--since <iso>] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
268
303
  airctrl gateway usage-logs --project <id> [--since <iso>] [--provider <id>]
269
- [--model <name>] [--status <code>] [--gateway <id>] [--limit <n>] [--offset <n>]
304
+ [--model <name>] [--status <code>] [--gateway <id>] [--cursor <opaque>]
305
+ [--limit <n>] [--offset <legacy-n>]
270
306
  airctrl gateway usage-log <logId> --project <id>
271
307
  airctrl gateway usage-spend --project <id>
272
308
  airctrl gateway usage-metrics --project <id> [--since <iso>] [--bucket hour|day]
273
309
  airctrl gateway otel <gatewayId> --account <id>
274
310
  airctrl gateway otel-update <gatewayId> --account <id>
275
311
  [--enabled true|false] [--endpoint <url|null>] [--metrics true|false]
276
- [--traces true|false] [--headers-env <variable>] [--clear-headers true|false]
312
+ [--traces true|false] [--bodies true|false]
313
+ [--headers-env <variable>] [--clear-headers true|false]
277
314
  ```
278
315
 
279
316
  Provider credentials and OpenTelemetry headers are read from named environment variables. Their values do not belong in command arguments.
@@ -425,6 +462,19 @@ airctrl get "$RECORD_ID" --profile ci
425
462
  airctrl gateway logs "$GATEWAY_ID" --profile ci
426
463
  ```
427
464
 
465
+ ### OAuth partner Apps
466
+
467
+ The CLI has no OAuth App profile, authorization-code flow, or connection/protection lifecycle
468
+ commands. Do not place OAuth client secrets, authorization codes, access tokens, or refresh tokens in
469
+ its PAT/Service Account profiles or shell history. Those values belong in a confidential partner
470
+ backend.
471
+
472
+ Implement OAuth partner flows through the standards-based direct HTTP contract or
473
+ `OAuthPartnerClient`. See [OAuth partner integrations](https://docs.airctrl.dev/guides/oauth-partner-integrations),
474
+ [OAuth protocol](https://docs.airctrl.dev/reference/oauth-protocol), and
475
+ [OAuth protection API](https://docs.airctrl.dev/reference/oauth-protections). The CLI may still manage ordinary gateways with
476
+ a separately authorized human PAT; that is not the OAuth installation identity.
477
+
428
478
  ### CLI failures
429
479
 
430
480
  | Code or condition | Meaning | What to do |
@@ -834,6 +884,21 @@ airctrl record audit "$RECORD_ID" --limit 25
834
884
 
835
885
 
836
886
 
887
+ #### Page and filter one record's audit history
888
+
889
+ ```bash
890
+ airctrl record audit-events "$RECORD_ID" --action record.update --actor david --limit 25
891
+ # Continue with pagination.next_cursor from the previous JSON response.
892
+ airctrl record audit-events "$RECORD_ID" --action record.update --actor david \
893
+ --limit 25 --cursor "$NEXT_CURSOR"
894
+ ```
895
+
896
+
897
+
898
+ **CLI command:** `airctrl record audit-events`
899
+
900
+
901
+
837
902
  #### Find unusual record activity
838
903
 
839
904
 
@@ -1695,7 +1760,11 @@ Returns request metadata. Service Accounts may use this read when their role per
1695
1760
 
1696
1761
  ```bash
1697
1762
  airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z \
1698
- --status 200 --limit 50 --offset 0
1763
+ --status 200 --limit 50
1764
+
1765
+ # Continue with pagination.next_cursor from the previous JSON response.
1766
+ airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z \
1767
+ --status 200 --limit 50 --cursor "$NEXT_CURSOR"
1699
1768
  ```
1700
1769
 
1701
1770
 
@@ -1751,7 +1820,11 @@ Returns usage metadata across the selected project.
1751
1820
 
1752
1821
  ```bash
1753
1822
  airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
1754
- --since 2026-09-01T00:00:00Z --limit 50 --offset 0
1823
+ --since 2026-09-01T00:00:00Z --limit 50
1824
+
1825
+ # Keep the exact same filters when continuing a cursor.
1826
+ airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
1827
+ --since 2026-09-01T00:00:00Z --limit 50 --cursor "$NEXT_CURSOR"
1755
1828
  ```
1756
1829
 
1757
1830
 
@@ -1843,8 +1916,9 @@ The CLI reads header values from the named environment variable. Use `--clear-he
1843
1916
 
1844
1917
  ```bash
1845
1918
  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
1919
+ --enabled true --endpoint https://otel.example.com \
1920
+ --metrics true --traces true --bodies true \
1921
+ --headers-env OTEL_EXPORT_HEADERS
1848
1922
  ```
1849
1923
 
1850
1924
 
@@ -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', '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': {
@@ -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,7 @@ 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
+ cursor: parsed.flags.cursor,
392
393
  limit: numberFlag(parsed.flags.limit, true, 1, 200),
393
394
  offset: numberFlag(parsed.flags.offset, true),
394
395
  });
@@ -400,6 +401,7 @@ export async function runGatewayCommand(argv, deps) {
400
401
  result = await client.listGatewayKeyAccess(id, {
401
402
  outcome: enumFlag(parsed.flags.outcome, ['granted', 'denied', 'error']),
402
403
  since: parsed.flags.since,
404
+ cursor: parsed.flags.cursor,
403
405
  limit: numberFlag(parsed.flags.limit, true, 1, 200),
404
406
  offset: numberFlag(parsed.flags.offset, true),
405
407
  });
@@ -412,6 +414,7 @@ export async function runGatewayCommand(argv, deps) {
412
414
  model: parsed.flags.model,
413
415
  status: numberFlag(parsed.flags.status, true, 100, 599),
414
416
  gatewayId: parsed.flags.gateway,
417
+ cursor: parsed.flags.cursor,
415
418
  limit: numberFlag(parsed.flags.limit, true, 1, 200),
416
419
  offset: numberFlag(parsed.flags.offset, true),
417
420
  });
@@ -441,6 +444,8 @@ export async function runGatewayCommand(argv, deps) {
441
444
  patch.exportMetrics = booleanFlag(parsed.flags.metrics);
442
445
  if (parsed.flags.traces !== undefined)
443
446
  patch.exportTraces = booleanFlag(parsed.flags.traces);
447
+ if (parsed.flags.bodies !== undefined)
448
+ patch.exportBodies = booleanFlag(parsed.flags.bodies);
444
449
  const headers = headersFromEnv(parsed.flags['headers-env'], booleanFlag(parsed.flags['clear-headers']), deps.env ?? process.env);
445
450
  if (headers !== undefined)
446
451
  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.4.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.4.0"
43
43
  }
44
44
  }