@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 +82 -11
- package/dist/gateway-commands.js +21 -7
- package/dist/record-commands.js +20 -2
- package/package.json +2 -2
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>] [--
|
|
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>] [--
|
|
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] [--
|
|
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
|
|
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
|
|
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
|
|
1847
|
-
--metrics true --traces true --
|
|
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
|
|
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', '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 =
|
|
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;
|
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.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.
|
|
42
|
+
"@airctrl/sdk": "0.5.0"
|
|
43
43
|
}
|
|
44
44
|
}
|