@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 +84 -10
- package/dist/gateway-commands.js +9 -4
- package/dist/record-commands.js +20 -2
- package/package.json +2 -2
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>] [--
|
|
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] [--
|
|
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
|
|
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
|
|
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
|
|
1847
|
-
--metrics true --traces true --
|
|
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
|
|
package/dist/gateway-commands.js
CHANGED
|
@@ -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;
|
package/dist/record-commands.js
CHANGED
|
@@ -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
|
+
"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.
|
|
42
|
+
"@airctrl/sdk": "0.4.0"
|
|
43
43
|
}
|
|
44
44
|
}
|