@airctrl/cli 0.4.0 → 0.6.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 +320 -620
- package/dist/cli.js +8 -0
- package/dist/gateway-commands.js +19 -6
- package/dist/mcp-gateway-commands.js +185 -0
- package/dist/sa-commands.js +20 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -16,36 +16,27 @@ Requires Node.js 22.x.
|
|
|
16
16
|
|
|
17
17
|
## Current release
|
|
18
18
|
|
|
19
|
-
**Coordinated package version:** `0.
|
|
19
|
+
**Coordinated package version:** `0.6.0`
|
|
20
20
|
|
|
21
21
|
### SDK
|
|
22
22
|
|
|
23
|
-
- Added
|
|
24
|
-
- Added
|
|
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.
|
|
23
|
+
- Added the canonical typed MCP Gateway client for gateway, catalog, server, tool, client-key, policy-as-code and call-evidence operations.
|
|
24
|
+
- Added progressive/eager tool-discovery configuration and connector-backed `stdio` catalog server inputs.
|
|
30
25
|
|
|
31
26
|
### CLI
|
|
32
27
|
|
|
33
|
-
- Added
|
|
34
|
-
- Added
|
|
35
|
-
- Added OpenTelemetry request/response body-export configuration while preserving the existing header-custody contract.
|
|
28
|
+
- Added the `airctrl mcp-gateway` command family as a thin binding over the SDK.
|
|
29
|
+
- Added `--discovery-mode` runtime configuration and `--connector` for local catalog servers.
|
|
36
30
|
|
|
37
31
|
### MCP
|
|
38
32
|
|
|
39
|
-
- Added
|
|
40
|
-
- Added
|
|
41
|
-
- Added OpenTelemetry body-export configuration and aligned pagination limits with the API contract.
|
|
33
|
+
- Added MCP Gateway discovery, provisioning, policy-preview and scoped client-key tools backed by the same SDK owner.
|
|
34
|
+
- Added progressive discovery controls; gateway clients can search ranked schemas before invoking one selected tool.
|
|
42
35
|
|
|
43
36
|
### Release engineering
|
|
44
37
|
|
|
45
|
-
-
|
|
46
|
-
-
|
|
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.
|
|
38
|
+
- Coordinated SDK, CLI, MCP, Web, and Authenticator package references at `0.6.0`.
|
|
39
|
+
- Added production-image, tarball, installed-consumer, generated README, and public-contract verification for the MCP Gateway release.
|
|
49
40
|
|
|
50
41
|
## CLI overview
|
|
51
42
|
|
|
@@ -144,6 +135,19 @@ airctrl gateway tokens <gatewayId>
|
|
|
144
135
|
airctrl gateway logs <gatewayId>
|
|
145
136
|
airctrl gateway log <gatewayId> <logId>
|
|
146
137
|
airctrl gateway key-access <gatewayId>
|
|
138
|
+
airctrl mcp-gateway list --project <projectId>
|
|
139
|
+
airctrl mcp-gateway get <gatewayId>
|
|
140
|
+
airctrl mcp-gateway catalog
|
|
141
|
+
airctrl mcp-gateway servers <gatewayId>
|
|
142
|
+
airctrl mcp-gateway server-health <gatewayId> <serverId>
|
|
143
|
+
airctrl mcp-gateway tools <gatewayId>
|
|
144
|
+
airctrl mcp-gateway clients <gatewayId>
|
|
145
|
+
airctrl mcp-gateway keys <gatewayId> <clientId>
|
|
146
|
+
airctrl mcp-gateway policies <gatewayId>
|
|
147
|
+
airctrl mcp-gateway calls <gatewayId>
|
|
148
|
+
airctrl mcp-gateway metrics <gatewayId>
|
|
149
|
+
airctrl mcp-gateway calls-export <gatewayId>
|
|
150
|
+
airctrl mcp-gateway grants <gatewayId>
|
|
147
151
|
```
|
|
148
152
|
|
|
149
153
|
The CLI rejects every other command before making an SDK or API call. RBAC can still deny a command
|
|
@@ -243,6 +247,60 @@ airctrl record revoke-group <recordId> --group <id>
|
|
|
243
247
|
|
|
244
248
|
Project audit scope requires both `--scope-type project` and `--scope-id`.
|
|
245
249
|
|
|
250
|
+
### MCP Gateway commands
|
|
251
|
+
|
|
252
|
+
`airctrl mcp-gateway` is a thin binding over `AirctrlClient.mcpGateways()`. It lists and manages MCP gateways, servers, tools, clients, scoped keys, policies, grants and call evidence without a second HTTP implementation.
|
|
253
|
+
|
|
254
|
+
```text
|
|
255
|
+
airctrl mcp-gateway list --project <id>
|
|
256
|
+
airctrl mcp-gateway get <gatewayId>
|
|
257
|
+
airctrl mcp-gateway servers <gatewayId>
|
|
258
|
+
airctrl mcp-gateway tools <gatewayId>
|
|
259
|
+
airctrl mcp-gateway clients <gatewayId>
|
|
260
|
+
airctrl mcp-gateway policies <gatewayId>
|
|
261
|
+
airctrl mcp-gateway calls <gatewayId>
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Run `airctrl mcp-gateway help` for creation, scoped-key, grant and policy-as-code commands. A newly created client key is printed once; redirect it only to a secure destination.
|
|
265
|
+
|
|
266
|
+
Use `server-create --auth-secret-env <NAME>` so hosted bearer/custom-header material comes from the process environment rather than a command argument. A local `stdio` server uses `--connector <connectorId>`. Use `runtime --discovery-mode progressive|eager` for tool discovery plus bounded timeout, result-size, concurrency and CIDR settings.
|
|
267
|
+
|
|
268
|
+
```text
|
|
269
|
+
airctrl mcp-gateway list --project <id>
|
|
270
|
+
airctrl mcp-gateway create --project <id> --name <name>
|
|
271
|
+
airctrl mcp-gateway catalog
|
|
272
|
+
airctrl mcp-gateway get <gatewayId>
|
|
273
|
+
airctrl mcp-gateway update <gatewayId> --name <name>
|
|
274
|
+
airctrl mcp-gateway delete <gatewayId>
|
|
275
|
+
airctrl mcp-gateway runtime <gatewayId> --discovery-mode progressive --timeout-ms <n>
|
|
276
|
+
airctrl mcp-gateway servers <gatewayId>
|
|
277
|
+
airctrl mcp-gateway server-create <gatewayId> --name <name> --namespace <name> --transport <transport> --connector <connectorId> --auth <mode>
|
|
278
|
+
airctrl mcp-gateway server-delete <gatewayId> <serverId>
|
|
279
|
+
airctrl mcp-gateway server-update <gatewayId> <serverId> --name <name>
|
|
280
|
+
airctrl mcp-gateway server-sync <gatewayId> <serverId>
|
|
281
|
+
airctrl mcp-gateway server-health <gatewayId> <serverId>
|
|
282
|
+
airctrl mcp-gateway tools <gatewayId>
|
|
283
|
+
airctrl mcp-gateway clients <gatewayId>
|
|
284
|
+
airctrl mcp-gateway client-create <gatewayId> --name <name> --type api_key
|
|
285
|
+
airctrl mcp-gateway client-revoke <gatewayId> <clientId>
|
|
286
|
+
airctrl mcp-gateway client-update <gatewayId> <clientId> --name <name>
|
|
287
|
+
airctrl mcp-gateway keys <gatewayId> <clientId>
|
|
288
|
+
airctrl mcp-gateway key-create <gatewayId> <clientId>
|
|
289
|
+
airctrl mcp-gateway key-revoke <gatewayId> <clientId> <keyId>
|
|
290
|
+
airctrl mcp-gateway policies <gatewayId>
|
|
291
|
+
airctrl mcp-gateway policy-create <gatewayId> --name <name> --pattern <glob> --effect allow --access full
|
|
292
|
+
airctrl mcp-gateway policy-delete <gatewayId> <policyId>
|
|
293
|
+
airctrl mcp-gateway grants <gatewayId>
|
|
294
|
+
airctrl mcp-gateway grant-create <gatewayId> --subject-type group --subject-id <id> --access read_only
|
|
295
|
+
airctrl mcp-gateway grant-revoke <gatewayId> <grantId>
|
|
296
|
+
airctrl mcp-gateway policy-export <gatewayId>
|
|
297
|
+
airctrl mcp-gateway policy-apply <gatewayId> <file>
|
|
298
|
+
airctrl mcp-gateway calls <gatewayId>
|
|
299
|
+
airctrl mcp-gateway metrics <gatewayId>
|
|
300
|
+
airctrl mcp-gateway payload <gatewayId> <callId>
|
|
301
|
+
airctrl mcp-gateway calls-export <gatewayId>
|
|
302
|
+
```
|
|
303
|
+
|
|
246
304
|
### Gateway commands
|
|
247
305
|
|
|
248
306
|
Discovery and lifecycle:
|
|
@@ -292,20 +350,27 @@ airctrl gateway provider-credential-update <credentialId> --account <id> --label
|
|
|
292
350
|
airctrl gateway provider-credential-revoke <credentialId> --account <id>
|
|
293
351
|
```
|
|
294
352
|
|
|
353
|
+
`gateway provider-models` includes current official pricing for each discovered model. Numeric token
|
|
354
|
+
rates use USD per one million tokens; `displayText` and `rateCard` preserve provider-published zero
|
|
355
|
+
and context-tiered policies.
|
|
356
|
+
|
|
295
357
|
Observability:
|
|
296
358
|
|
|
297
359
|
```text
|
|
298
|
-
airctrl gateway logs <gatewayId> [--since <iso>] [--provider <id>] [--model <name>]
|
|
299
|
-
[--status <code>] [--
|
|
360
|
+
airctrl gateway logs <gatewayId> [--since <iso>] [--until <iso>] [--provider <id>] [--model <name>]
|
|
361
|
+
[--status <code>] [--status-class 2xx|4xx|5xx|other] [--search <keywords>]
|
|
362
|
+
[--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
|
|
300
363
|
airctrl gateway log <gatewayId> <logId>
|
|
301
364
|
airctrl gateway key-access <gatewayId> [--outcome granted|denied|error]
|
|
302
|
-
[--since <iso>] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
|
|
303
|
-
airctrl gateway usage-logs --project <id> [--since <iso>] [--provider <id>]
|
|
365
|
+
[--since <iso>] [--until <iso>] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
|
|
366
|
+
airctrl gateway usage-logs --project <id> [--since <iso>] [--until <iso>] [--provider <id>]
|
|
304
367
|
[--model <name>] [--status <code>] [--gateway <id>] [--cursor <opaque>]
|
|
305
368
|
[--limit <n>] [--offset <legacy-n>]
|
|
306
369
|
airctrl gateway usage-log <logId> --project <id>
|
|
307
|
-
airctrl gateway usage-spend --project <id>
|
|
308
|
-
airctrl gateway usage-metrics --project <id> [--since <iso>] [--bucket hour|day]
|
|
370
|
+
airctrl gateway usage-spend --project <id> [--gateway <id>]
|
|
371
|
+
airctrl gateway usage-metrics --project <id> [--since <iso>] [--until <iso>] [--bucket hour|day]
|
|
372
|
+
[--gateway <id>] [--provider <slug>] [--model <name>]
|
|
373
|
+
[--status-class 2xx|4xx|5xx|other] [--search <keywords>]
|
|
309
374
|
airctrl gateway otel <gatewayId> --account <id>
|
|
310
375
|
airctrl gateway otel-update <gatewayId> --account <id>
|
|
311
376
|
[--enabled true|false] [--endpoint <url|null>] [--metrics true|false]
|
|
@@ -492,11 +557,8 @@ adding a human PAT to the same machine configuration.
|
|
|
492
557
|
## CLI example catalog
|
|
493
558
|
|
|
494
559
|
This page shows every public CLI command. Replace the environment variables with IDs from your AIRCTRL account. Commands that read secret values should run only in a trusted terminal.
|
|
495
|
-
|
|
496
560
|
### Prepare the examples
|
|
497
|
-
|
|
498
561
|
The examples assume these non-secret IDs are already available:
|
|
499
|
-
|
|
500
562
|
```bash
|
|
501
563
|
export AIRCTRL_ACCOUNT_ID="00000000-0000-4000-8000-000000000001"
|
|
502
564
|
export PROJECT_ID="00000000-0000-4000-8000-000000000010"
|
|
@@ -504,130 +566,77 @@ export RECORD_ID="00000000-0000-4000-8000-000000000020"
|
|
|
504
566
|
export GATEWAY_ID="00000000-0000-4000-8000-000000000030"
|
|
505
567
|
export IDEMPOTENCY_KEY="00000000-0000-4000-8000-000000000090"
|
|
506
568
|
```
|
|
507
|
-
|
|
508
569
|
Use `airctrl project accounts`, `airctrl project list`, `airctrl record list` and `airctrl gateway list`
|
|
509
570
|
to discover resource IDs. Generate one new UUID idempotency key for each intended write, and reuse it only when retrying that same input. Never guess a resource ID or try nearby IDs after an authorization failure.
|
|
510
|
-
|
|
511
571
|
Every flag takes a separate value. Booleans use `true` or `false`; lists use comma-separated values;
|
|
512
572
|
repeatable inputs repeat the flag. Run `airctrl project`, `airctrl record`, `airctrl gateway` or
|
|
513
573
|
`airctrl sa` to see the exact syntax installed on the machine.
|
|
514
|
-
|
|
515
574
|
### Local setup and record access
|
|
516
|
-
|
|
517
575
|
#### Sign in to AIRCTRL
|
|
518
576
|
|
|
519
|
-
|
|
520
|
-
|
|
521
577
|
Store a human PAT in the local CLI profile. The CLI asks for the token without placing it in shell history. It returns a success message after the profile is saved.
|
|
522
578
|
|
|
523
|
-
|
|
524
|
-
|
|
525
579
|
```bash
|
|
526
580
|
airctrl login
|
|
527
581
|
```
|
|
528
582
|
|
|
529
|
-
|
|
530
|
-
|
|
531
583
|
**CLI command:** `airctrl login`
|
|
532
584
|
|
|
533
|
-
|
|
534
|
-
|
|
535
585
|
#### Read a complete record
|
|
536
586
|
|
|
537
|
-
|
|
538
|
-
|
|
539
587
|
Decrypt one accessible record and return all fields. Use `--profile ci` for an active Service Account profile. A missing wrapper returns `no_wrapper_for_caller`.
|
|
540
588
|
|
|
541
|
-
|
|
542
|
-
|
|
543
589
|
```bash
|
|
544
590
|
airctrl get "$RECORD_ID"
|
|
545
591
|
```
|
|
546
|
-
|
|
547
592
|
For a By Environment record, select exactly one value:
|
|
548
|
-
|
|
549
593
|
```bash
|
|
550
594
|
airctrl get "$RECORD_ID" --env staging
|
|
551
595
|
```
|
|
552
596
|
|
|
553
|
-
|
|
554
|
-
|
|
555
597
|
**CLI command:** `airctrl get`
|
|
556
598
|
|
|
557
|
-
|
|
558
|
-
|
|
559
599
|
#### Read selected record sections
|
|
560
600
|
|
|
561
|
-
|
|
562
|
-
|
|
563
601
|
Read selected record sections. `fields` returns the complete decrypted field map; scope values are section names, not individual field names. Omit `--env` for General or pass `--env staging` to read only Staging. The PAT or Service Account token must permit that scope; AIRCTRL never expands access beyond the record grant.
|
|
564
602
|
|
|
565
|
-
|
|
566
|
-
|
|
567
603
|
```bash
|
|
568
604
|
airctrl read "$RECORD_ID" --scope meta,fields
|
|
569
605
|
```
|
|
570
|
-
|
|
571
606
|
To read the Staging value of an Environment record:
|
|
572
|
-
|
|
573
607
|
```bash
|
|
574
608
|
airctrl read "$RECORD_ID" --scope meta,fields --env staging
|
|
575
609
|
```
|
|
576
610
|
|
|
577
|
-
|
|
578
|
-
|
|
579
611
|
**CLI command:** `airctrl read`
|
|
580
612
|
|
|
581
|
-
|
|
582
|
-
|
|
583
613
|
#### Inject records into a process
|
|
584
614
|
|
|
585
|
-
|
|
586
|
-
|
|
587
615
|
Inject accessible General project records into one child process. Pass `--env staging` to inject only Staging values instead. The values exist only in the child process environment. The command returns the child process exit status.
|
|
588
616
|
|
|
589
|
-
|
|
590
|
-
|
|
591
617
|
```bash
|
|
592
618
|
airctrl run --project "$PROJECT_ID" -- npm run dev
|
|
593
619
|
```
|
|
594
|
-
|
|
595
620
|
```bash
|
|
596
621
|
airctrl run --project "$PROJECT_ID" --env staging -- npm run dev
|
|
597
622
|
```
|
|
598
623
|
|
|
599
|
-
|
|
600
|
-
|
|
601
624
|
**CLI command:** `airctrl run`
|
|
602
625
|
|
|
603
|
-
|
|
604
|
-
|
|
605
626
|
#### Generate a secret locally
|
|
606
627
|
|
|
607
|
-
|
|
608
|
-
|
|
609
628
|
Generate secret material locally without storing it. The generated fields are printed once. This command does not call the API.
|
|
610
629
|
|
|
611
|
-
|
|
612
|
-
|
|
613
630
|
```bash
|
|
614
631
|
airctrl generate password --length 32
|
|
615
632
|
```
|
|
616
633
|
|
|
617
|
-
|
|
618
|
-
|
|
619
634
|
**CLI command:** `airctrl generate`
|
|
620
635
|
|
|
621
|
-
|
|
622
|
-
|
|
623
636
|
#### Create an encrypted record
|
|
624
637
|
|
|
625
|
-
|
|
626
|
-
|
|
627
638
|
Create an encrypted record from supplied fields. The CLI returns the new record ID. Avoid literal secret values in shell history; prefer an import or protected environment variable.
|
|
628
639
|
|
|
629
|
-
|
|
630
|
-
|
|
631
640
|
```bash
|
|
632
641
|
airctrl create password --project "$PROJECT_ID" --name "Database login" \
|
|
633
642
|
--field service_name=Database --field username=app_user --field password="$DATABASE_PASSWORD" \
|
|
@@ -635,257 +644,146 @@ airctrl create password --project "$PROJECT_ID" --name "Database login" \
|
|
|
635
644
|
--idempotency-key "$IDEMPOTENCY_KEY"
|
|
636
645
|
```
|
|
637
646
|
|
|
638
|
-
|
|
639
|
-
|
|
640
647
|
**CLI command:** `airctrl create`
|
|
641
648
|
|
|
642
|
-
|
|
643
|
-
|
|
644
649
|
#### Create or replace record fields
|
|
645
650
|
|
|
646
|
-
|
|
647
|
-
|
|
648
651
|
Update a matching record or create it when it does not exist. The result states whether AIRCTRL created or updated the record.
|
|
649
652
|
|
|
650
|
-
|
|
651
|
-
|
|
652
653
|
```bash
|
|
653
654
|
airctrl set plain --project "$PROJECT_ID" --name "Payments token" \
|
|
654
655
|
--field body="$PAYMENTS_TOKEN" \
|
|
655
656
|
--idempotency-key "$IDEMPOTENCY_KEY"
|
|
656
657
|
```
|
|
657
658
|
|
|
658
|
-
|
|
659
|
-
|
|
660
659
|
**CLI command:** `airctrl set`
|
|
661
660
|
|
|
662
|
-
|
|
663
|
-
|
|
664
661
|
#### Create a generated record
|
|
665
662
|
|
|
666
|
-
|
|
667
|
-
|
|
668
663
|
Generate, encrypt and store a new record. The command returns the record ID. The generated value is encrypted before it leaves the CLI. This certificate generator fills the format's required fields; other formats may need additional non-secret fields supplied through the SDK or Web app.
|
|
669
664
|
|
|
670
|
-
|
|
671
|
-
|
|
672
665
|
```bash
|
|
673
666
|
airctrl new certificate --project "$PROJECT_ID" --name "Generated TLS certificate" --cn api.example.invalid
|
|
674
667
|
```
|
|
675
668
|
|
|
676
|
-
|
|
677
|
-
|
|
678
669
|
**CLI command:** `airctrl new`
|
|
679
670
|
|
|
680
|
-
|
|
681
|
-
|
|
682
671
|
#### Import environment variables
|
|
683
672
|
|
|
684
|
-
|
|
685
|
-
|
|
686
673
|
Import an ENV file as one encrypted record. The source file stays unchanged. Review it before import so unrelated local variables are not stored. `--target-env` names a field inside the ENV-format record; `--env` separately selects the record's encrypted Development, Staging, or Production value.
|
|
687
674
|
|
|
688
|
-
|
|
689
|
-
|
|
690
675
|
```bash
|
|
691
676
|
airctrl import env ./.env.production --project "$PROJECT_ID" \
|
|
692
677
|
--name "Production environment" --target-env production
|
|
693
678
|
```
|
|
694
679
|
|
|
695
|
-
|
|
696
|
-
|
|
697
680
|
**CLI command:** `airctrl import`
|
|
698
681
|
|
|
699
|
-
|
|
700
|
-
|
|
701
682
|
### Account and project commands
|
|
702
|
-
|
|
703
683
|
#### List accessible accounts
|
|
704
684
|
|
|
705
|
-
|
|
706
|
-
|
|
707
685
|
Returns accounts available to the human PAT. Service Accounts cannot discover accounts.
|
|
708
686
|
|
|
709
|
-
|
|
710
|
-
|
|
711
687
|
```bash
|
|
712
688
|
airctrl project accounts
|
|
713
689
|
```
|
|
714
690
|
|
|
715
|
-
|
|
716
|
-
|
|
717
691
|
**CLI command:** `airctrl project accounts`
|
|
718
692
|
|
|
719
|
-
|
|
720
|
-
|
|
721
693
|
#### List projects
|
|
722
694
|
|
|
723
|
-
|
|
724
|
-
|
|
725
695
|
Returns accessible projects in the selected account.
|
|
726
696
|
|
|
727
|
-
|
|
728
|
-
|
|
729
697
|
```bash
|
|
730
698
|
airctrl project list --account "$ACCOUNT_ID" --include-archived false
|
|
731
699
|
```
|
|
732
700
|
|
|
733
|
-
|
|
734
|
-
|
|
735
701
|
**CLI command:** `airctrl project list`
|
|
736
702
|
|
|
737
|
-
|
|
738
|
-
|
|
739
703
|
#### View a project
|
|
740
704
|
|
|
741
|
-
|
|
742
|
-
|
|
743
705
|
Returns one project or a not-found result when it is unavailable.
|
|
744
706
|
|
|
745
|
-
|
|
746
|
-
|
|
747
707
|
```bash
|
|
748
708
|
airctrl project get "$PROJECT_ID" --account "$ACCOUNT_ID"
|
|
749
709
|
```
|
|
750
710
|
|
|
751
|
-
|
|
752
|
-
|
|
753
711
|
**CLI command:** `airctrl project get`
|
|
754
712
|
|
|
755
|
-
|
|
756
|
-
|
|
757
713
|
#### Create a project
|
|
758
714
|
|
|
759
|
-
|
|
760
|
-
|
|
761
715
|
Returns the new project ID. The caller becomes its Project Administrator.
|
|
762
716
|
|
|
763
|
-
|
|
764
|
-
|
|
765
717
|
```bash
|
|
766
718
|
airctrl project create --account "$ACCOUNT_ID" --name "Payments" \
|
|
767
719
|
--description "Credentials used by the payments service"
|
|
768
720
|
```
|
|
769
721
|
|
|
770
|
-
|
|
771
|
-
|
|
772
722
|
**CLI command:** `airctrl project create`
|
|
773
723
|
|
|
774
|
-
|
|
775
|
-
|
|
776
724
|
#### Update a project
|
|
777
725
|
|
|
778
|
-
|
|
779
|
-
|
|
780
726
|
This command replaces all three editable values, so pass the values you want to keep.
|
|
781
727
|
|
|
782
|
-
|
|
783
|
-
|
|
784
728
|
```bash
|
|
785
729
|
airctrl project update "$PROJECT_ID" --account "$ACCOUNT_ID" \
|
|
786
730
|
--name "Payments production" --description "Production credentials" --active true
|
|
787
731
|
```
|
|
788
732
|
|
|
789
|
-
|
|
790
|
-
|
|
791
733
|
**CLI command:** `airctrl project update`
|
|
792
734
|
|
|
793
|
-
|
|
794
|
-
|
|
795
735
|
#### Archive a project
|
|
796
736
|
|
|
797
|
-
|
|
798
|
-
|
|
799
737
|
Archived projects remain stored but leave normal active lists.
|
|
800
738
|
|
|
801
|
-
|
|
802
|
-
|
|
803
739
|
```bash
|
|
804
740
|
airctrl project archive "$PROJECT_ID" --account "$ACCOUNT_ID"
|
|
805
741
|
```
|
|
806
742
|
|
|
807
|
-
|
|
808
|
-
|
|
809
743
|
**CLI command:** `airctrl project archive`
|
|
810
744
|
|
|
811
|
-
|
|
812
|
-
|
|
813
745
|
#### Restore a project
|
|
814
746
|
|
|
815
|
-
|
|
816
|
-
|
|
817
747
|
Returns the restored project state.
|
|
818
748
|
|
|
819
|
-
|
|
820
|
-
|
|
821
749
|
```bash
|
|
822
750
|
airctrl project restore "$PROJECT_ID" --account "$ACCOUNT_ID"
|
|
823
751
|
```
|
|
824
752
|
|
|
825
|
-
|
|
826
|
-
|
|
827
753
|
**CLI command:** `airctrl project restore`
|
|
828
754
|
|
|
829
|
-
|
|
830
|
-
|
|
831
755
|
### Record metadata and history
|
|
832
|
-
|
|
833
756
|
#### List record metadata
|
|
834
757
|
|
|
835
|
-
|
|
836
|
-
|
|
837
758
|
Returns safe metadata, not decrypted fields. Service Account results are limited by its grants and custom role.
|
|
838
759
|
|
|
839
|
-
|
|
840
|
-
|
|
841
760
|
```bash
|
|
842
761
|
airctrl record list --project "$PROJECT_ID" --tab owned --limit 50 --offset 0
|
|
843
762
|
```
|
|
844
763
|
|
|
845
|
-
|
|
846
|
-
|
|
847
764
|
**CLI command:** `airctrl record list`
|
|
848
765
|
|
|
849
|
-
|
|
850
|
-
|
|
851
766
|
#### View record version history
|
|
852
767
|
|
|
853
|
-
|
|
854
|
-
|
|
855
768
|
Returns encrypted version metadata in newest-first order.
|
|
856
769
|
|
|
857
|
-
|
|
858
|
-
|
|
859
770
|
```bash
|
|
860
771
|
airctrl record versions "$RECORD_ID"
|
|
861
772
|
```
|
|
862
773
|
|
|
863
|
-
|
|
864
|
-
|
|
865
774
|
**CLI command:** `airctrl record versions`
|
|
866
775
|
|
|
867
|
-
|
|
868
|
-
|
|
869
776
|
#### Review one record's audit history
|
|
870
777
|
|
|
871
|
-
|
|
872
|
-
|
|
873
778
|
Returns recent audit events when the caller can view this record's audit history.
|
|
874
779
|
|
|
875
|
-
|
|
876
|
-
|
|
877
780
|
```bash
|
|
878
781
|
airctrl record audit "$RECORD_ID" --limit 25
|
|
879
782
|
```
|
|
880
783
|
|
|
881
|
-
|
|
882
|
-
|
|
883
784
|
**CLI command:** `airctrl record audit`
|
|
884
785
|
|
|
885
|
-
|
|
886
|
-
|
|
887
786
|
#### Page and filter one record's audit history
|
|
888
|
-
|
|
889
787
|
```bash
|
|
890
788
|
airctrl record audit-events "$RECORD_ID" --action record.update --actor david --limit 25
|
|
891
789
|
# Continue with pagination.next_cursor from the previous JSON response.
|
|
@@ -893,185 +791,105 @@ airctrl record audit-events "$RECORD_ID" --action record.update --actor david \
|
|
|
893
791
|
--limit 25 --cursor "$NEXT_CURSOR"
|
|
894
792
|
```
|
|
895
793
|
|
|
896
|
-
|
|
897
|
-
|
|
898
794
|
**CLI command:** `airctrl record audit-events`
|
|
899
795
|
|
|
900
|
-
|
|
901
|
-
|
|
902
796
|
#### Find unusual record activity
|
|
903
797
|
|
|
904
|
-
|
|
905
|
-
|
|
906
798
|
Returns unusual record events for the selected scope.
|
|
907
799
|
|
|
908
|
-
|
|
909
|
-
|
|
910
800
|
```bash
|
|
911
801
|
airctrl record anomalies --account "$ACCOUNT_ID" --scope-type project --scope-id "$PROJECT_ID"
|
|
912
802
|
```
|
|
913
803
|
|
|
914
|
-
|
|
915
|
-
|
|
916
804
|
**CLI command:** `airctrl record anomalies`
|
|
917
805
|
|
|
918
|
-
|
|
919
|
-
|
|
920
806
|
#### Review daily record activity
|
|
921
807
|
|
|
922
|
-
|
|
923
|
-
|
|
924
808
|
The date is UTC and must use `YYYY-MM-DD`.
|
|
925
809
|
|
|
926
|
-
|
|
927
|
-
|
|
928
810
|
```bash
|
|
929
811
|
airctrl record activity 2026-09-10 --account "$ACCOUNT_ID" \
|
|
930
812
|
--scope-type project --scope-id "$PROJECT_ID"
|
|
931
813
|
```
|
|
932
814
|
|
|
933
|
-
|
|
934
|
-
|
|
935
815
|
**CLI command:** `airctrl record activity`
|
|
936
816
|
|
|
937
|
-
|
|
938
|
-
|
|
939
817
|
#### Review record alerts
|
|
940
818
|
|
|
941
|
-
|
|
942
|
-
|
|
943
819
|
Returns the paginated alert feed.
|
|
944
820
|
|
|
945
|
-
|
|
946
|
-
|
|
947
821
|
```bash
|
|
948
822
|
airctrl record alerts --account "$ACCOUNT_ID" --scope-type project \
|
|
949
823
|
--scope-id "$PROJECT_ID" --limit 25 --offset 0
|
|
950
824
|
```
|
|
951
825
|
|
|
952
|
-
|
|
953
|
-
|
|
954
826
|
**CLI command:** `airctrl record alerts`
|
|
955
827
|
|
|
956
|
-
|
|
957
|
-
|
|
958
828
|
#### Review secret access events
|
|
959
829
|
|
|
960
|
-
|
|
961
|
-
|
|
962
830
|
Returns matching record access events. Action names are exact strings.
|
|
963
831
|
|
|
964
|
-
|
|
965
|
-
|
|
966
832
|
```bash
|
|
967
833
|
airctrl record access --account "$ACCOUNT_ID" --scope-type project \
|
|
968
834
|
--scope-id "$PROJECT_ID" --actions record.secret_access,record.read --limit 25
|
|
969
835
|
```
|
|
970
836
|
|
|
971
|
-
|
|
972
|
-
|
|
973
837
|
**CLI command:** `airctrl record access`
|
|
974
838
|
|
|
975
|
-
|
|
976
|
-
|
|
977
839
|
#### Update record details
|
|
978
840
|
|
|
979
|
-
|
|
980
|
-
|
|
981
841
|
Only supplied fields change. Use the documented `null` or `none` value to clear optional fields.
|
|
982
842
|
|
|
983
|
-
|
|
984
|
-
|
|
985
843
|
```bash
|
|
986
844
|
airctrl record metadata "$RECORD_ID" --tags payments,production \
|
|
987
845
|
--secret-due 2026-12-01T00:00:00Z --rotation-days 90
|
|
988
846
|
```
|
|
989
847
|
|
|
990
|
-
|
|
991
|
-
|
|
992
848
|
**CLI command:** `airctrl record metadata`
|
|
993
849
|
|
|
994
|
-
|
|
995
|
-
|
|
996
850
|
#### Archive a record
|
|
997
851
|
|
|
998
|
-
|
|
999
|
-
|
|
1000
852
|
Archives the record without deleting encrypted history.
|
|
1001
853
|
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
854
|
```bash
|
|
1005
855
|
airctrl record archive "$RECORD_ID"
|
|
1006
856
|
```
|
|
1007
857
|
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
858
|
**CLI command:** `airctrl record archive`
|
|
1011
859
|
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
860
|
#### Restore a record
|
|
1015
861
|
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
862
|
Restores an archived record to active lists.
|
|
1019
863
|
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
864
|
```bash
|
|
1023
865
|
airctrl record restore "$RECORD_ID"
|
|
1024
866
|
```
|
|
1025
867
|
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
868
|
**CLI command:** `airctrl record restore`
|
|
1029
869
|
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
870
|
#### Transfer record ownership
|
|
1033
871
|
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
872
|
The new owner must be eligible. Confirm both IDs before transferring ownership.
|
|
1037
873
|
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
874
|
```bash
|
|
1041
875
|
airctrl record transfer "$RECORD_ID" --owner "$NEW_OWNER_USER_ID"
|
|
1042
876
|
```
|
|
1043
877
|
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
878
|
**CLI command:** `airctrl record transfer`
|
|
1047
879
|
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
880
|
#### Restore a previous record version
|
|
1051
881
|
|
|
1052
|
-
|
|
1053
|
-
|
|
1054
882
|
AIRCTRL decrypts the selected version locally and saves a new current version under the current record key. Later history remains intact. A human PAT and vault unlock are required.
|
|
1055
883
|
|
|
1056
|
-
|
|
1057
|
-
|
|
1058
884
|
```bash
|
|
1059
885
|
airctrl record rollback "$RECORD_ID" --version "$VERSION_ID"
|
|
1060
886
|
```
|
|
1061
887
|
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
888
|
**CLI command:** `airctrl record rollback`
|
|
1065
889
|
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
890
|
#### Replace record fields by ID
|
|
1069
891
|
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
Updates the encrypted value under the record's existing key. This replaces the complete field map; include unchanged fields you need to retain.
|
|
1073
|
-
|
|
1074
|
-
|
|
892
|
+
Updates the encrypted value under the record's existing key. This replaces the complete field map; include unchanged fields you need to retain.
|
|
1075
893
|
|
|
1076
894
|
```bash
|
|
1077
895
|
airctrl record set "$RECORD_ID" --field service_name=Database \
|
|
@@ -1079,894 +897,776 @@ airctrl record set "$RECORD_ID" --field service_name=Database \
|
|
|
1079
897
|
--idempotency-key "$IDEMPOTENCY_KEY"
|
|
1080
898
|
```
|
|
1081
899
|
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
900
|
**CLI command:** `airctrl record set`
|
|
1085
901
|
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
902
|
#### Rotate a record
|
|
1089
903
|
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
904
|
Rotates the record data key locally and saves a new encrypted version.
|
|
1093
905
|
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
906
|
```bash
|
|
1097
907
|
airctrl record rotate "$RECORD_ID"
|
|
1098
908
|
```
|
|
1099
909
|
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
910
|
**CLI command:** `airctrl record rotate`
|
|
1103
911
|
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
912
|
### Groups
|
|
1107
|
-
|
|
1108
913
|
Use a human PAT and Team+ collaboration with the required RBAC permissions. GROUP_ID, USER_ID and ROLE_ID are actual IDs from earlier reads, not sample values to try against an account. See [the access model](https://docs.airctrl.dev/guides/projects#groups-and-effective-access).
|
|
1109
|
-
|
|
1110
914
|
#### List context groups
|
|
1111
|
-
|
|
1112
915
|
```bash
|
|
1113
916
|
airctrl group list "$PROJECT_ID" --account "$AIRCTRL_ACCOUNT_ID"
|
|
1114
917
|
```
|
|
1115
918
|
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
919
|
**CLI command:** `airctrl group list`
|
|
1119
920
|
|
|
1120
|
-
|
|
1121
|
-
|
|
1122
921
|
#### Read a record's group grants
|
|
1123
|
-
|
|
1124
922
|
```bash
|
|
1125
923
|
airctrl group record-grants "$RECORD_ID" --account "$AIRCTRL_ACCOUNT_ID"
|
|
1126
924
|
```
|
|
1127
925
|
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
926
|
**CLI command:** `airctrl group record-grants`
|
|
1131
927
|
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
928
|
#### Create a group
|
|
1135
|
-
|
|
1136
929
|
Creation does not grant a project role.
|
|
1137
|
-
|
|
1138
930
|
```bash
|
|
1139
931
|
airctrl group create "$PROJECT_ID" --account "$AIRCTRL_ACCOUNT_ID" --name "Payments team" --description "Payments operators"
|
|
1140
932
|
```
|
|
1141
933
|
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
934
|
**CLI command:** `airctrl group create`
|
|
1145
935
|
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
936
|
#### Rename a group
|
|
1149
|
-
|
|
1150
937
|
Omitting description clears it.
|
|
1151
|
-
|
|
1152
938
|
```bash
|
|
1153
939
|
airctrl group update "$GROUP_ID" --account "$AIRCTRL_ACCOUNT_ID" --name "Payments operators" --description "Payments access"
|
|
1154
940
|
```
|
|
1155
941
|
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
942
|
**CLI command:** `airctrl group update`
|
|
1159
943
|
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
944
|
#### Delete a group
|
|
1163
|
-
|
|
1164
945
|
Deletes only this group's access paths. Review remaining sources and pending re-keying.
|
|
1165
|
-
|
|
1166
946
|
```bash
|
|
1167
947
|
airctrl group delete "$GROUP_ID" --account "$AIRCTRL_ACCOUNT_ID"
|
|
1168
948
|
```
|
|
1169
949
|
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
950
|
**CLI command:** `airctrl group delete`
|
|
1173
951
|
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
952
|
#### List group members
|
|
1177
|
-
|
|
1178
953
|
```bash
|
|
1179
954
|
airctrl group members "$GROUP_ID" --account "$AIRCTRL_ACCOUNT_ID"
|
|
1180
955
|
```
|
|
1181
956
|
|
|
1182
|
-
|
|
1183
|
-
|
|
1184
957
|
**CLI command:** `airctrl group members`
|
|
1185
958
|
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
959
|
#### Add a group member
|
|
1189
|
-
|
|
1190
960
|
The person must be an onboarded account member. The result can report pending encrypted material.
|
|
1191
|
-
|
|
1192
961
|
```bash
|
|
1193
962
|
airctrl group add-member "$GROUP_ID" "$USER_ID" --account "$AIRCTRL_ACCOUNT_ID"
|
|
1194
963
|
```
|
|
1195
964
|
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
965
|
**CLI command:** `airctrl group add-member`
|
|
1199
966
|
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
967
|
#### Remove a group member
|
|
1203
|
-
|
|
1204
968
|
Preserves access through other groups, project membership or direct record shares.
|
|
1205
|
-
|
|
1206
969
|
```bash
|
|
1207
970
|
airctrl group remove-member "$GROUP_ID" "$USER_ID" --account "$AIRCTRL_ACCOUNT_ID"
|
|
1208
971
|
```
|
|
1209
972
|
|
|
1210
|
-
|
|
1211
|
-
|
|
1212
973
|
**CLI command:** `airctrl group remove-member`
|
|
1213
974
|
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
975
|
#### Grant a project role to a group
|
|
1217
|
-
|
|
1218
976
|
Use a delegable role ID from the SDK catalog or API reference; do not guess IDs.
|
|
1219
|
-
|
|
1220
977
|
```bash
|
|
1221
978
|
airctrl group grant-project "$PROJECT_ID" "$GROUP_ID" "$ROLE_ID" --account "$AIRCTRL_ACCOUNT_ID"
|
|
1222
979
|
```
|
|
1223
980
|
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
981
|
**CLI command:** `airctrl group grant-project`
|
|
1227
982
|
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
983
|
#### Revoke one project role from a group
|
|
1231
|
-
|
|
1232
984
|
Removes only this project/group/role assignment.
|
|
1233
|
-
|
|
1234
985
|
```bash
|
|
1235
986
|
airctrl group revoke-project "$PROJECT_ID" "$GROUP_ID" "$ROLE_ID" --account "$AIRCTRL_ACCOUNT_ID"
|
|
1236
987
|
```
|
|
1237
988
|
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
989
|
**CLI command:** `airctrl group revoke-project`
|
|
1241
990
|
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
991
|
#### Complete pending encrypted access
|
|
1245
|
-
|
|
1246
992
|
Uses the configured local passphrase. The project filter does not limit pending direct group-record repairs in the account. Attempts are not proof of completed recipient access.
|
|
1247
|
-
|
|
1248
993
|
```bash
|
|
1249
994
|
airctrl group reconcile --account "$AIRCTRL_ACCOUNT_ID" --project "$PROJECT_ID"
|
|
1250
995
|
```
|
|
1251
996
|
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
997
|
**CLI command:** `airctrl group reconcile`
|
|
1255
998
|
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
999
|
### Record sharing
|
|
1259
|
-
|
|
1260
1000
|
#### Share a record with a user
|
|
1261
1001
|
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
1002
|
The recipient must be onboarded and eligible for the project.
|
|
1265
1003
|
|
|
1266
|
-
|
|
1267
|
-
|
|
1268
1004
|
```bash
|
|
1269
1005
|
airctrl record share-user "$RECORD_ID" --user "$USER_ID" --permission read
|
|
1270
1006
|
```
|
|
1271
1007
|
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
1008
|
**CLI command:** `airctrl record share-user`
|
|
1275
1009
|
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
1010
|
#### Share a record with a Service Account
|
|
1279
1011
|
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
1012
|
Encrypts a wrapper for the Service Account. This does not change its custom role.
|
|
1283
1013
|
|
|
1284
|
-
|
|
1285
|
-
|
|
1286
1014
|
```bash
|
|
1287
1015
|
airctrl record share-sa "$RECORD_ID" --account "$ACCOUNT_ID" \
|
|
1288
1016
|
--service-account "$SERVICE_ACCOUNT_ID"
|
|
1289
1017
|
```
|
|
1290
1018
|
|
|
1291
|
-
|
|
1292
|
-
|
|
1293
1019
|
**CLI command:** `airctrl record share-sa`
|
|
1294
1020
|
|
|
1295
|
-
|
|
1296
|
-
|
|
1297
1021
|
#### Share a record with a group
|
|
1298
1022
|
|
|
1299
|
-
|
|
1300
|
-
|
|
1301
1023
|
The group must belong to the record's account. A direct record share does not grant project access.
|
|
1302
1024
|
|
|
1303
|
-
|
|
1304
|
-
|
|
1305
1025
|
```bash
|
|
1306
1026
|
airctrl record share-group "$RECORD_ID" --group "$GROUP_ID"
|
|
1307
1027
|
```
|
|
1308
1028
|
|
|
1309
|
-
|
|
1310
|
-
|
|
1311
1029
|
**CLI command:** `airctrl record share-group`
|
|
1312
1030
|
|
|
1313
|
-
|
|
1314
|
-
|
|
1315
1031
|
#### Remove a user's record access
|
|
1316
1032
|
|
|
1317
|
-
|
|
1318
|
-
|
|
1319
1033
|
Removes the user's direct grant. Other authorized paths remain; wrappers are removed only where effective access is lost.
|
|
1320
1034
|
|
|
1321
|
-
|
|
1322
|
-
|
|
1323
1035
|
```bash
|
|
1324
1036
|
airctrl record revoke-user "$RECORD_ID" --user "$USER_ID"
|
|
1325
1037
|
```
|
|
1326
1038
|
|
|
1327
|
-
|
|
1328
|
-
|
|
1329
1039
|
**CLI command:** `airctrl record revoke-user`
|
|
1330
1040
|
|
|
1331
|
-
|
|
1332
|
-
|
|
1333
1041
|
#### Remove a Service Account's record access
|
|
1334
1042
|
|
|
1335
|
-
|
|
1336
|
-
|
|
1337
1043
|
Removes only this record grant. Other Service Account grants remain unchanged.
|
|
1338
1044
|
|
|
1339
|
-
|
|
1340
|
-
|
|
1341
1045
|
```bash
|
|
1342
1046
|
airctrl record revoke-sa "$RECORD_ID" --service-account "$SERVICE_ACCOUNT_ID"
|
|
1343
1047
|
```
|
|
1344
1048
|
|
|
1345
|
-
|
|
1346
|
-
|
|
1347
1049
|
**CLI command:** `airctrl record revoke-sa`
|
|
1348
1050
|
|
|
1349
|
-
|
|
1350
|
-
|
|
1351
1051
|
#### Remove a group's record access
|
|
1352
1052
|
|
|
1353
|
-
|
|
1354
|
-
|
|
1355
1053
|
Removes the group grant. Other authorized paths remain; wrappers are removed only where effective access is lost.
|
|
1356
1054
|
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
1055
|
```bash
|
|
1360
1056
|
airctrl record revoke-group "$RECORD_ID" --group "$GROUP_ID"
|
|
1361
1057
|
```
|
|
1362
1058
|
|
|
1363
|
-
|
|
1364
|
-
|
|
1365
1059
|
**CLI command:** `airctrl record revoke-group`
|
|
1366
1060
|
|
|
1367
|
-
|
|
1368
|
-
|
|
1369
1061
|
### Gateway discovery and lifecycle
|
|
1370
|
-
|
|
1371
1062
|
#### List supported AI providers
|
|
1372
1063
|
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
1064
|
Returns enabled providers. This command is available to both human and Service Account identities.
|
|
1376
1065
|
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
1066
|
```bash
|
|
1380
1067
|
airctrl gateway providers
|
|
1381
1068
|
```
|
|
1382
1069
|
|
|
1383
|
-
|
|
1384
|
-
|
|
1385
1070
|
**CLI command:** `airctrl gateway providers`
|
|
1386
1071
|
|
|
1387
|
-
|
|
1388
|
-
|
|
1389
1072
|
#### List gateways
|
|
1390
1073
|
|
|
1391
|
-
|
|
1392
|
-
|
|
1393
1074
|
Returns gateways in one project. This command requires a human PAT.
|
|
1394
1075
|
|
|
1395
|
-
|
|
1396
|
-
|
|
1397
1076
|
```bash
|
|
1398
1077
|
airctrl gateway list --project "$PROJECT_ID"
|
|
1399
1078
|
```
|
|
1400
1079
|
|
|
1401
|
-
|
|
1402
|
-
|
|
1403
1080
|
**CLI command:** `airctrl gateway list`
|
|
1404
1081
|
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
1082
|
#### View a gateway
|
|
1408
1083
|
|
|
1409
|
-
|
|
1410
|
-
|
|
1411
1084
|
Returns one accessible gateway and safe settings. Service Accounts may use this read.
|
|
1412
1085
|
|
|
1413
|
-
|
|
1414
|
-
|
|
1415
1086
|
```bash
|
|
1416
1087
|
airctrl gateway get "$GATEWAY_ID"
|
|
1417
1088
|
```
|
|
1418
1089
|
|
|
1419
|
-
|
|
1420
|
-
|
|
1421
1090
|
**CLI command:** `airctrl gateway get`
|
|
1422
1091
|
|
|
1423
|
-
|
|
1424
|
-
|
|
1425
1092
|
#### Create a gateway
|
|
1426
1093
|
|
|
1427
|
-
|
|
1428
|
-
|
|
1429
1094
|
Returns the gateway ID. Each provider credential must belong to the same account, and `--model` must exist in that credential's live catalog.
|
|
1430
1095
|
|
|
1431
|
-
|
|
1432
|
-
|
|
1433
1096
|
```bash
|
|
1434
1097
|
airctrl gateway create --account "$ACCOUNT_ID" --project "$PROJECT_ID" \
|
|
1435
1098
|
--name "Payments AI" --provider "$PROVIDER_ID" --model gpt-5 \
|
|
1436
1099
|
--credential-binding "$PROVIDER_CREDENTIAL_ID=gpt-5"
|
|
1437
1100
|
```
|
|
1438
1101
|
|
|
1439
|
-
|
|
1440
|
-
|
|
1441
1102
|
**CLI command:** `airctrl gateway create`
|
|
1442
1103
|
|
|
1443
|
-
|
|
1444
|
-
|
|
1445
1104
|
#### Update a gateway
|
|
1446
1105
|
|
|
1447
|
-
|
|
1448
|
-
|
|
1449
1106
|
Only supplied fields change.
|
|
1450
1107
|
|
|
1451
|
-
|
|
1452
|
-
|
|
1453
1108
|
```bash
|
|
1454
1109
|
airctrl gateway update "$GATEWAY_ID" --account "$ACCOUNT_ID" \
|
|
1455
1110
|
--name "Payments AI production" --model gpt-5 --active true
|
|
1456
1111
|
```
|
|
1457
1112
|
|
|
1458
|
-
|
|
1459
|
-
|
|
1460
1113
|
**CLI command:** `airctrl gateway update`
|
|
1461
1114
|
|
|
1462
|
-
|
|
1463
|
-
|
|
1464
1115
|
#### Delete a gateway
|
|
1465
1116
|
|
|
1466
|
-
|
|
1467
|
-
|
|
1468
1117
|
This disables the gateway and revokes its gateway tokens. Confirm the gateway ID first.
|
|
1469
1118
|
|
|
1470
|
-
|
|
1471
|
-
|
|
1472
1119
|
```bash
|
|
1473
1120
|
airctrl gateway delete "$GATEWAY_ID" --account "$ACCOUNT_ID"
|
|
1474
1121
|
```
|
|
1475
1122
|
|
|
1476
|
-
|
|
1477
|
-
|
|
1478
1123
|
**CLI command:** `airctrl gateway delete`
|
|
1479
1124
|
|
|
1480
|
-
|
|
1481
|
-
|
|
1482
1125
|
### Provider credentials
|
|
1483
|
-
|
|
1484
1126
|
#### List provider credentials
|
|
1485
1127
|
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
1128
|
Returns safe credential metadata; provider secret values never appear.
|
|
1489
1129
|
|
|
1490
|
-
|
|
1491
|
-
|
|
1492
1130
|
```bash
|
|
1493
1131
|
airctrl gateway provider-credentials --account "$ACCOUNT_ID"
|
|
1494
1132
|
```
|
|
1495
1133
|
|
|
1496
|
-
|
|
1497
|
-
|
|
1498
1134
|
**CLI command:** `airctrl gateway provider-credentials`
|
|
1499
1135
|
|
|
1500
|
-
|
|
1501
|
-
|
|
1502
1136
|
#### Add a provider credential
|
|
1503
1137
|
|
|
1504
|
-
|
|
1505
|
-
|
|
1506
1138
|
The CLI reads the secret from the named environment variable and never places it in the command arguments.
|
|
1507
1139
|
|
|
1508
|
-
|
|
1509
|
-
|
|
1510
1140
|
```bash
|
|
1511
1141
|
airctrl gateway provider-credential-create --account "$ACCOUNT_ID" \
|
|
1512
1142
|
--provider "$PROVIDER_ID" --label "Production OpenAI" \
|
|
1513
1143
|
--api-key-env OPENAI_PRODUCTION_KEY --kind api_key
|
|
1514
1144
|
```
|
|
1515
1145
|
|
|
1516
|
-
|
|
1517
|
-
|
|
1518
1146
|
**CLI command:** `airctrl gateway provider-credential-create`
|
|
1519
1147
|
|
|
1520
|
-
|
|
1521
|
-
|
|
1522
1148
|
#### List models for a credential
|
|
1523
1149
|
|
|
1524
|
-
|
|
1525
|
-
|
|
1526
1150
|
Returns the selected credential's live model catalog, capability tags, supported capabilities, and `airctrlSupport` status. Unsupported entries remain visible but cannot be attached to a gateway.
|
|
1527
1151
|
|
|
1528
|
-
|
|
1529
|
-
|
|
1530
1152
|
```bash
|
|
1531
1153
|
airctrl gateway provider-models "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"
|
|
1532
1154
|
```
|
|
1533
1155
|
|
|
1534
|
-
|
|
1535
|
-
|
|
1536
1156
|
**CLI command:** `airctrl gateway provider-models`
|
|
1537
1157
|
|
|
1538
|
-
|
|
1539
|
-
|
|
1540
1158
|
#### Replace a provider key
|
|
1541
1159
|
|
|
1542
|
-
|
|
1543
|
-
|
|
1544
1160
|
The old provider key stops being used after the replacement validates.
|
|
1545
1161
|
|
|
1546
|
-
|
|
1547
|
-
|
|
1548
1162
|
```bash
|
|
1549
1163
|
airctrl gateway provider-credential-rotate "$PROVIDER_CREDENTIAL_ID" \
|
|
1550
1164
|
--account "$ACCOUNT_ID" --api-key-env OPENAI_REPLACEMENT_KEY
|
|
1551
1165
|
```
|
|
1552
1166
|
|
|
1553
|
-
|
|
1554
|
-
|
|
1555
1167
|
**CLI command:** `airctrl gateway provider-credential-rotate`
|
|
1556
1168
|
|
|
1557
|
-
|
|
1558
|
-
|
|
1559
1169
|
#### Rename a provider credential
|
|
1560
1170
|
|
|
1561
|
-
|
|
1562
|
-
|
|
1563
1171
|
Changes only the display label.
|
|
1564
1172
|
|
|
1565
|
-
|
|
1566
|
-
|
|
1567
1173
|
```bash
|
|
1568
1174
|
airctrl gateway provider-credential-update "$PROVIDER_CREDENTIAL_ID" \
|
|
1569
1175
|
--account "$ACCOUNT_ID" --label "Primary OpenAI"
|
|
1570
1176
|
```
|
|
1571
1177
|
|
|
1572
|
-
|
|
1573
|
-
|
|
1574
1178
|
**CLI command:** `airctrl gateway provider-credential-update`
|
|
1575
1179
|
|
|
1576
|
-
|
|
1577
|
-
|
|
1578
1180
|
#### Revoke a provider credential
|
|
1579
1181
|
|
|
1580
|
-
|
|
1581
|
-
|
|
1582
1182
|
Revocation prevents future provider use. Confirm dependent gateways first.
|
|
1583
1183
|
|
|
1584
|
-
|
|
1585
|
-
|
|
1586
1184
|
```bash
|
|
1587
1185
|
airctrl gateway provider-credential-revoke "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"
|
|
1588
1186
|
```
|
|
1589
1187
|
|
|
1590
|
-
|
|
1591
|
-
|
|
1592
1188
|
**CLI command:** `airctrl gateway provider-credential-revoke`
|
|
1593
1189
|
|
|
1594
|
-
|
|
1595
|
-
|
|
1596
1190
|
#### Attach a provider credential
|
|
1597
1191
|
|
|
1598
|
-
|
|
1599
|
-
|
|
1600
1192
|
Validates every repeated `--model` against one live catalog, then attaches all exact key/model bindings to the gateway.
|
|
1601
1193
|
|
|
1602
|
-
|
|
1603
|
-
|
|
1604
1194
|
```bash
|
|
1605
1195
|
airctrl gateway credential-attach "$GATEWAY_ID" "$PROVIDER_CREDENTIAL_ID" \
|
|
1606
1196
|
--account "$ACCOUNT_ID" --model gpt-5 --model gpt-5-mini
|
|
1607
1197
|
```
|
|
1608
1198
|
|
|
1609
|
-
|
|
1610
|
-
|
|
1611
1199
|
**CLI command:** `airctrl gateway credential-attach`
|
|
1612
1200
|
|
|
1613
|
-
|
|
1614
|
-
|
|
1615
1201
|
#### Detach a provider credential
|
|
1616
1202
|
|
|
1617
|
-
|
|
1618
|
-
|
|
1619
1203
|
With `--model`, removes only that exact model binding. Without `--model`, detaches every model for the credential from this gateway. Neither form revokes the credential itself.
|
|
1620
1204
|
|
|
1621
|
-
|
|
1622
|
-
|
|
1623
1205
|
```bash
|
|
1624
1206
|
airctrl gateway credential-detach "$GATEWAY_ID" "$PROVIDER_CREDENTIAL_ID" \
|
|
1625
1207
|
--account "$ACCOUNT_ID" --model gpt-5
|
|
1626
|
-
|
|
1627
1208
|
airctrl gateway credential-detach "$GATEWAY_ID" "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"
|
|
1628
1209
|
```
|
|
1629
1210
|
|
|
1630
|
-
|
|
1631
|
-
|
|
1632
1211
|
**CLI command:** `airctrl gateway credential-detach`
|
|
1633
1212
|
|
|
1634
|
-
|
|
1635
|
-
|
|
1636
1213
|
### Gateway tokens
|
|
1637
|
-
|
|
1638
1214
|
#### List gateway tokens
|
|
1639
1215
|
|
|
1640
|
-
|
|
1641
|
-
|
|
1642
1216
|
Returns safe token metadata. Token plaintext is never listed again.
|
|
1643
1217
|
|
|
1644
|
-
|
|
1645
|
-
|
|
1646
1218
|
```bash
|
|
1647
1219
|
airctrl gateway tokens "$GATEWAY_ID"
|
|
1648
1220
|
```
|
|
1649
1221
|
|
|
1650
|
-
|
|
1651
|
-
|
|
1652
1222
|
**CLI command:** `airctrl gateway tokens`
|
|
1653
1223
|
|
|
1654
|
-
|
|
1655
|
-
|
|
1656
1224
|
#### Create a gateway token
|
|
1657
1225
|
|
|
1658
|
-
|
|
1659
|
-
|
|
1660
1226
|
The token value appears once. Save it immediately in an approved destination.
|
|
1661
1227
|
|
|
1662
|
-
|
|
1663
|
-
|
|
1664
1228
|
```bash
|
|
1665
1229
|
airctrl gateway token-create "$GATEWAY_ID" --account "$ACCOUNT_ID" \
|
|
1666
1230
|
--name "Local development" --expires-days 30 --scopes run,read_logs \
|
|
1667
1231
|
--allowed-models gpt-5,gpt-5-mini --rate-limit 60
|
|
1668
1232
|
```
|
|
1669
1233
|
|
|
1670
|
-
|
|
1671
|
-
|
|
1672
1234
|
**CLI command:** `airctrl gateway token-create`
|
|
1673
1235
|
|
|
1674
|
-
|
|
1675
|
-
|
|
1676
1236
|
#### Rename a gateway token
|
|
1677
1237
|
|
|
1678
|
-
|
|
1679
|
-
|
|
1680
1238
|
Changes the label, not the token value.
|
|
1681
1239
|
|
|
1682
|
-
|
|
1683
|
-
|
|
1684
1240
|
```bash
|
|
1685
1241
|
airctrl gateway token-rename "$GATEWAY_ID" "$TOKEN_ID" \
|
|
1686
1242
|
--account "$ACCOUNT_ID" --name "CI production"
|
|
1687
1243
|
```
|
|
1688
1244
|
|
|
1689
|
-
|
|
1690
|
-
|
|
1691
1245
|
**CLI command:** `airctrl gateway token-rename`
|
|
1692
1246
|
|
|
1693
|
-
|
|
1694
|
-
|
|
1695
1247
|
#### Revoke a gateway token
|
|
1696
1248
|
|
|
1697
|
-
|
|
1698
|
-
|
|
1699
1249
|
Authentication stops immediately. The token row remains available for audit.
|
|
1700
1250
|
|
|
1701
|
-
|
|
1702
|
-
|
|
1703
1251
|
```bash
|
|
1704
1252
|
airctrl gateway token-revoke "$GATEWAY_ID" "$TOKEN_ID" --account "$ACCOUNT_ID"
|
|
1705
1253
|
```
|
|
1706
1254
|
|
|
1707
|
-
|
|
1708
|
-
|
|
1709
1255
|
**CLI command:** `airctrl gateway token-revoke`
|
|
1710
1256
|
|
|
1711
|
-
|
|
1712
|
-
|
|
1713
1257
|
#### Delete a gateway token
|
|
1714
1258
|
|
|
1715
|
-
|
|
1716
|
-
|
|
1717
1259
|
Deletes token metadata. Revoke first when you need a clear audit transition.
|
|
1718
1260
|
|
|
1719
|
-
|
|
1720
|
-
|
|
1721
1261
|
```bash
|
|
1722
1262
|
airctrl gateway token-delete "$GATEWAY_ID" "$TOKEN_ID" --account "$ACCOUNT_ID"
|
|
1723
1263
|
```
|
|
1724
1264
|
|
|
1725
|
-
|
|
1726
|
-
|
|
1727
1265
|
**CLI command:** `airctrl gateway token-delete`
|
|
1728
1266
|
|
|
1729
|
-
|
|
1730
|
-
|
|
1731
1267
|
### Routing, limits and telemetry
|
|
1732
|
-
|
|
1733
1268
|
#### Change gateway limits and behavior
|
|
1734
1269
|
|
|
1735
|
-
|
|
1736
|
-
|
|
1737
1270
|
Only supplied settings change. Body logging can store sensitive request content, so keep it disabled unless required.
|
|
1738
1271
|
|
|
1739
|
-
|
|
1740
|
-
|
|
1741
1272
|
```bash
|
|
1742
1273
|
airctrl gateway settings "$GATEWAY_ID" --account "$ACCOUNT_ID" \
|
|
1743
1274
|
--spend-limit 100 --spend-window monthly --rate-limit 120 \
|
|
1744
1275
|
--logging true --log-bodies false --guardrail flag
|
|
1745
1276
|
```
|
|
1746
1277
|
|
|
1278
|
+
**CLI command:** `airctrl gateway settings`
|
|
1747
1279
|
|
|
1280
|
+
#### Review gateway requests
|
|
1748
1281
|
|
|
1749
|
-
|
|
1282
|
+
Returns request metadata. Service Accounts may use this read when their role permits it.
|
|
1750
1283
|
|
|
1284
|
+
```bash
|
|
1285
|
+
airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z --until 2026-10-01T00:00:00Z \
|
|
1286
|
+
--status 200 --limit 50
|
|
1287
|
+
# Continue with pagination.next_cursor from the previous JSON response.
|
|
1288
|
+
airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z --until 2026-10-01T00:00:00Z \
|
|
1289
|
+
--status 200 --limit 50 --cursor "$NEXT_CURSOR"
|
|
1290
|
+
```
|
|
1751
1291
|
|
|
1292
|
+
**CLI command:** `airctrl gateway logs`
|
|
1752
1293
|
|
|
1753
|
-
####
|
|
1294
|
+
#### Inspect one gateway request
|
|
1754
1295
|
|
|
1296
|
+
Returns stored bodies only when body logging and the required permission are both present.
|
|
1755
1297
|
|
|
1298
|
+
```bash
|
|
1299
|
+
airctrl gateway log "$GATEWAY_ID" "$LOG_ID"
|
|
1300
|
+
```
|
|
1756
1301
|
|
|
1757
|
-
|
|
1302
|
+
**CLI command:** `airctrl gateway log`
|
|
1758
1303
|
|
|
1304
|
+
#### Review provider-key access
|
|
1759
1305
|
|
|
1306
|
+
Returns provider-key access decisions without returning provider keys.
|
|
1760
1307
|
|
|
1761
1308
|
```bash
|
|
1762
|
-
airctrl gateway
|
|
1763
|
-
--
|
|
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"
|
|
1309
|
+
airctrl gateway key-access "$GATEWAY_ID" --outcome denied \
|
|
1310
|
+
--since 2026-09-01T00:00:00Z --until 2026-10-01T00:00:00Z --limit 50 --offset 0
|
|
1768
1311
|
```
|
|
1769
1312
|
|
|
1313
|
+
**CLI command:** `airctrl gateway key-access`
|
|
1770
1314
|
|
|
1315
|
+
#### Review project usage logs
|
|
1771
1316
|
|
|
1772
|
-
|
|
1317
|
+
Returns usage metadata across the selected project.
|
|
1773
1318
|
|
|
1319
|
+
```bash
|
|
1320
|
+
airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
|
|
1321
|
+
--since 2026-09-01T00:00:00Z --until 2026-10-01T00:00:00Z --limit 50
|
|
1322
|
+
# Keep the exact same filters when continuing a cursor.
|
|
1323
|
+
airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
|
|
1324
|
+
--since 2026-09-01T00:00:00Z --until 2026-10-01T00:00:00Z --limit 50 --cursor "$NEXT_CURSOR"
|
|
1325
|
+
```
|
|
1774
1326
|
|
|
1327
|
+
**CLI command:** `airctrl gateway usage-logs`
|
|
1775
1328
|
|
|
1776
|
-
#### Inspect one
|
|
1329
|
+
#### Inspect one project usage log
|
|
1777
1330
|
|
|
1331
|
+
Returns one project log and any stored bodies allowed by RBAC.
|
|
1778
1332
|
|
|
1333
|
+
```bash
|
|
1334
|
+
airctrl gateway usage-log "$LOG_ID" --project "$PROJECT_ID"
|
|
1335
|
+
```
|
|
1779
1336
|
|
|
1780
|
-
|
|
1337
|
+
**CLI command:** `airctrl gateway usage-log`
|
|
1781
1338
|
|
|
1339
|
+
#### Review project spend
|
|
1782
1340
|
|
|
1341
|
+
Returns current spend and the effective project or account limit.
|
|
1783
1342
|
|
|
1784
1343
|
```bash
|
|
1785
|
-
airctrl gateway
|
|
1344
|
+
airctrl gateway usage-spend --project "$PROJECT_ID"
|
|
1786
1345
|
```
|
|
1787
1346
|
|
|
1347
|
+
**CLI command:** `airctrl gateway usage-spend`
|
|
1788
1348
|
|
|
1349
|
+
#### Review project usage metrics
|
|
1789
1350
|
|
|
1790
|
-
|
|
1351
|
+
Returns request, error, token, latency and spend aggregates.
|
|
1791
1352
|
|
|
1353
|
+
```bash
|
|
1354
|
+
airctrl gateway usage-metrics --project "$PROJECT_ID" \
|
|
1355
|
+
--since 2026-09-01T00:00:00Z --until 2026-10-01T00:00:00Z --bucket day
|
|
1356
|
+
```
|
|
1792
1357
|
|
|
1358
|
+
**CLI command:** `airctrl gateway usage-metrics`
|
|
1793
1359
|
|
|
1794
|
-
####
|
|
1360
|
+
#### View OpenTelemetry settings
|
|
1795
1361
|
|
|
1362
|
+
Returns safe OpenTelemetry settings. Secret header values are never returned.
|
|
1796
1363
|
|
|
1364
|
+
```bash
|
|
1365
|
+
airctrl gateway otel "$GATEWAY_ID" --account "$ACCOUNT_ID"
|
|
1366
|
+
```
|
|
1797
1367
|
|
|
1798
|
-
|
|
1368
|
+
**CLI command:** `airctrl gateway otel`
|
|
1799
1369
|
|
|
1370
|
+
#### Change OpenTelemetry settings
|
|
1800
1371
|
|
|
1372
|
+
The CLI reads header values from the named environment variable. Use `--clear-headers true` to remove stored headers.
|
|
1801
1373
|
|
|
1802
1374
|
```bash
|
|
1803
|
-
airctrl gateway
|
|
1804
|
-
--
|
|
1375
|
+
airctrl gateway otel-update "$GATEWAY_ID" --account "$ACCOUNT_ID" \
|
|
1376
|
+
--enabled true --endpoint https://otel.example.com \
|
|
1377
|
+
--metrics true --traces true --bodies true \
|
|
1378
|
+
--headers-env OTEL_EXPORT_HEADERS
|
|
1805
1379
|
```
|
|
1806
1380
|
|
|
1381
|
+
**CLI command:** `airctrl gateway otel-update`
|
|
1807
1382
|
|
|
1383
|
+
### Service Account metadata
|
|
1384
|
+
#### List Service Accounts
|
|
1808
1385
|
|
|
1809
|
-
|
|
1386
|
+
Returns safe Service Account metadata to a human PAT.
|
|
1387
|
+
|
|
1388
|
+
```bash
|
|
1389
|
+
airctrl sa list --account "$ACCOUNT_ID"
|
|
1390
|
+
```
|
|
1810
1391
|
|
|
1392
|
+
**CLI command:** `airctrl sa list`
|
|
1811
1393
|
|
|
1394
|
+
#### View a Service Account
|
|
1812
1395
|
|
|
1813
|
-
|
|
1396
|
+
Returns one Service Account from the safe metadata list. Lifecycle and credential actions remain dashboard-only.
|
|
1814
1397
|
|
|
1398
|
+
```bash
|
|
1399
|
+
airctrl sa get "$SERVICE_ACCOUNT_ID" --account "$ACCOUNT_ID"
|
|
1400
|
+
```
|
|
1815
1401
|
|
|
1402
|
+
**CLI command:** `airctrl sa get`
|
|
1816
1403
|
|
|
1817
|
-
|
|
1404
|
+
### MCP Gateway examples
|
|
1405
|
+
#### List MCP gateways
|
|
1406
|
+
```bash
|
|
1407
|
+
airctrl mcp-gateway list --project "$PROJECT_ID"
|
|
1408
|
+
```
|
|
1818
1409
|
|
|
1410
|
+
**CLI command:** `airctrl mcp-gateway list`
|
|
1819
1411
|
|
|
1820
1412
|
|
|
1413
|
+
#### Create MCP gateway
|
|
1821
1414
|
```bash
|
|
1822
|
-
airctrl gateway
|
|
1823
|
-
|
|
1415
|
+
airctrl mcp-gateway create --project "$PROJECT_ID" --name Engineering
|
|
1416
|
+
```
|
|
1824
1417
|
|
|
1825
|
-
|
|
1826
|
-
|
|
1827
|
-
|
|
1418
|
+
**CLI command:** `airctrl mcp-gateway create`
|
|
1419
|
+
|
|
1420
|
+
|
|
1421
|
+
#### List MCP catalog
|
|
1422
|
+
```bash
|
|
1423
|
+
airctrl mcp-gateway catalog
|
|
1828
1424
|
```
|
|
1829
1425
|
|
|
1426
|
+
**CLI command:** `airctrl mcp-gateway catalog`
|
|
1830
1427
|
|
|
1831
1428
|
|
|
1832
|
-
|
|
1429
|
+
#### Read MCP gateway
|
|
1430
|
+
```bash
|
|
1431
|
+
airctrl mcp-gateway get "$GATEWAY_ID"
|
|
1432
|
+
```
|
|
1833
1433
|
|
|
1434
|
+
**CLI command:** `airctrl mcp-gateway get`
|
|
1834
1435
|
|
|
1835
1436
|
|
|
1836
|
-
####
|
|
1437
|
+
#### Update MCP gateway
|
|
1438
|
+
```bash
|
|
1439
|
+
airctrl mcp-gateway update "$GATEWAY_ID" --name Engineering
|
|
1440
|
+
```
|
|
1837
1441
|
|
|
1442
|
+
**CLI command:** `airctrl mcp-gateway update`
|
|
1838
1443
|
|
|
1839
1444
|
|
|
1840
|
-
|
|
1445
|
+
#### Delete MCP gateway
|
|
1446
|
+
```bash
|
|
1447
|
+
airctrl mcp-gateway delete "$GATEWAY_ID"
|
|
1448
|
+
```
|
|
1841
1449
|
|
|
1450
|
+
**CLI command:** `airctrl mcp-gateway delete`
|
|
1842
1451
|
|
|
1843
1452
|
|
|
1453
|
+
#### Configure MCP runtime
|
|
1844
1454
|
```bash
|
|
1845
|
-
airctrl gateway
|
|
1455
|
+
airctrl mcp-gateway runtime "$GATEWAY_ID" --timeout-ms 30000
|
|
1846
1456
|
```
|
|
1847
1457
|
|
|
1458
|
+
**CLI command:** `airctrl mcp-gateway runtime`
|
|
1848
1459
|
|
|
1849
1460
|
|
|
1850
|
-
|
|
1461
|
+
#### List MCP servers
|
|
1462
|
+
```bash
|
|
1463
|
+
airctrl mcp-gateway servers "$GATEWAY_ID"
|
|
1464
|
+
```
|
|
1851
1465
|
|
|
1466
|
+
**CLI command:** `airctrl mcp-gateway servers`
|
|
1852
1467
|
|
|
1853
1468
|
|
|
1854
|
-
####
|
|
1469
|
+
#### Create MCP server
|
|
1470
|
+
```bash
|
|
1471
|
+
airctrl mcp-gateway server-create "$GATEWAY_ID" --name Linear --namespace linear --transport streamable_http --endpoint https://mcp.linear.app/mcp --auth bearer --auth-secret-env AIRCTRL_MCP_KEY_LINEAR
|
|
1472
|
+
```
|
|
1855
1473
|
|
|
1474
|
+
**CLI command:** `airctrl mcp-gateway server-create`
|
|
1856
1475
|
|
|
1857
1476
|
|
|
1858
|
-
|
|
1477
|
+
#### Delete MCP server
|
|
1478
|
+
```bash
|
|
1479
|
+
airctrl mcp-gateway server-delete "$GATEWAY_ID" "$SERVER_ID"
|
|
1480
|
+
```
|
|
1859
1481
|
|
|
1482
|
+
**CLI command:** `airctrl mcp-gateway server-delete`
|
|
1860
1483
|
|
|
1861
1484
|
|
|
1485
|
+
#### Update MCP server
|
|
1862
1486
|
```bash
|
|
1863
|
-
airctrl gateway
|
|
1487
|
+
airctrl mcp-gateway server-update "$GATEWAY_ID" "$SERVER_ID" --enabled true
|
|
1864
1488
|
```
|
|
1865
1489
|
|
|
1490
|
+
**CLI command:** `airctrl mcp-gateway server-update`
|
|
1866
1491
|
|
|
1867
1492
|
|
|
1868
|
-
|
|
1493
|
+
#### Synchronize MCP server
|
|
1494
|
+
```bash
|
|
1495
|
+
airctrl mcp-gateway server-sync "$GATEWAY_ID" "$SERVER_ID"
|
|
1496
|
+
```
|
|
1869
1497
|
|
|
1498
|
+
**CLI command:** `airctrl mcp-gateway server-sync`
|
|
1870
1499
|
|
|
1871
1500
|
|
|
1872
|
-
####
|
|
1501
|
+
#### Read MCP server health
|
|
1502
|
+
```bash
|
|
1503
|
+
airctrl mcp-gateway server-health "$GATEWAY_ID" "$SERVER_ID"
|
|
1504
|
+
```
|
|
1873
1505
|
|
|
1506
|
+
**CLI command:** `airctrl mcp-gateway server-health`
|
|
1874
1507
|
|
|
1875
1508
|
|
|
1876
|
-
|
|
1509
|
+
#### List MCP tools
|
|
1510
|
+
```bash
|
|
1511
|
+
airctrl mcp-gateway tools "$GATEWAY_ID"
|
|
1512
|
+
```
|
|
1877
1513
|
|
|
1514
|
+
**CLI command:** `airctrl mcp-gateway tools`
|
|
1878
1515
|
|
|
1879
1516
|
|
|
1517
|
+
#### List MCP clients
|
|
1880
1518
|
```bash
|
|
1881
|
-
airctrl gateway
|
|
1882
|
-
--since 2026-09-01T00:00:00Z --bucket day
|
|
1519
|
+
airctrl mcp-gateway clients "$GATEWAY_ID"
|
|
1883
1520
|
```
|
|
1884
1521
|
|
|
1522
|
+
**CLI command:** `airctrl mcp-gateway clients`
|
|
1885
1523
|
|
|
1886
1524
|
|
|
1887
|
-
|
|
1525
|
+
#### Create MCP client
|
|
1526
|
+
```bash
|
|
1527
|
+
airctrl mcp-gateway client-create "$GATEWAY_ID" --name Cursor --type api_key
|
|
1528
|
+
```
|
|
1888
1529
|
|
|
1530
|
+
**CLI command:** `airctrl mcp-gateway client-create`
|
|
1889
1531
|
|
|
1890
1532
|
|
|
1891
|
-
####
|
|
1533
|
+
#### Revoke MCP client
|
|
1534
|
+
```bash
|
|
1535
|
+
airctrl mcp-gateway client-revoke "$GATEWAY_ID" "$CLIENT_ID"
|
|
1536
|
+
```
|
|
1892
1537
|
|
|
1538
|
+
**CLI command:** `airctrl mcp-gateway client-revoke`
|
|
1893
1539
|
|
|
1894
1540
|
|
|
1895
|
-
|
|
1541
|
+
#### Update MCP client
|
|
1542
|
+
```bash
|
|
1543
|
+
airctrl mcp-gateway client-update "$GATEWAY_ID" "$CLIENT_ID" --name Cursor-CI
|
|
1544
|
+
```
|
|
1896
1545
|
|
|
1546
|
+
**CLI command:** `airctrl mcp-gateway client-update`
|
|
1897
1547
|
|
|
1898
1548
|
|
|
1549
|
+
#### List MCP keys
|
|
1899
1550
|
```bash
|
|
1900
|
-
airctrl gateway
|
|
1551
|
+
airctrl mcp-gateway keys "$GATEWAY_ID" "$CLIENT_ID"
|
|
1901
1552
|
```
|
|
1902
1553
|
|
|
1554
|
+
**CLI command:** `airctrl mcp-gateway keys`
|
|
1903
1555
|
|
|
1904
1556
|
|
|
1905
|
-
|
|
1557
|
+
#### Create MCP key
|
|
1558
|
+
```bash
|
|
1559
|
+
airctrl mcp-gateway key-create "$GATEWAY_ID" "$CLIENT_ID" --scopes mcp:connect,mcp:call
|
|
1560
|
+
```
|
|
1906
1561
|
|
|
1562
|
+
**CLI command:** `airctrl mcp-gateway key-create`
|
|
1907
1563
|
|
|
1908
1564
|
|
|
1909
|
-
####
|
|
1565
|
+
#### Revoke MCP key
|
|
1566
|
+
```bash
|
|
1567
|
+
airctrl mcp-gateway key-revoke "$GATEWAY_ID" "$CLIENT_ID" "$KEY_ID"
|
|
1568
|
+
```
|
|
1910
1569
|
|
|
1570
|
+
**CLI command:** `airctrl mcp-gateway key-revoke`
|
|
1911
1571
|
|
|
1912
1572
|
|
|
1913
|
-
|
|
1573
|
+
#### List MCP policies
|
|
1574
|
+
```bash
|
|
1575
|
+
airctrl mcp-gateway policies "$GATEWAY_ID"
|
|
1576
|
+
```
|
|
1914
1577
|
|
|
1578
|
+
**CLI command:** `airctrl mcp-gateway policies`
|
|
1915
1579
|
|
|
1916
1580
|
|
|
1581
|
+
#### Create MCP policy
|
|
1917
1582
|
```bash
|
|
1918
|
-
airctrl gateway
|
|
1919
|
-
--enabled true --endpoint https://otel.example.com \
|
|
1920
|
-
--metrics true --traces true --bodies true \
|
|
1921
|
-
--headers-env OTEL_EXPORT_HEADERS
|
|
1583
|
+
airctrl mcp-gateway policy-create "$GATEWAY_ID" --name Read-only --pattern '*' --effect allow --access read_only
|
|
1922
1584
|
```
|
|
1923
1585
|
|
|
1586
|
+
**CLI command:** `airctrl mcp-gateway policy-create`
|
|
1924
1587
|
|
|
1925
1588
|
|
|
1926
|
-
|
|
1589
|
+
#### Delete MCP policy
|
|
1590
|
+
```bash
|
|
1591
|
+
airctrl mcp-gateway policy-delete "$GATEWAY_ID" "$POLICY_ID"
|
|
1592
|
+
```
|
|
1927
1593
|
|
|
1594
|
+
**CLI command:** `airctrl mcp-gateway policy-delete`
|
|
1928
1595
|
|
|
1929
1596
|
|
|
1930
|
-
|
|
1597
|
+
#### List MCP grants
|
|
1598
|
+
```bash
|
|
1599
|
+
airctrl mcp-gateway grants "$GATEWAY_ID"
|
|
1600
|
+
```
|
|
1931
1601
|
|
|
1932
|
-
|
|
1602
|
+
**CLI command:** `airctrl mcp-gateway grants`
|
|
1933
1603
|
|
|
1934
1604
|
|
|
1605
|
+
#### Create MCP grant
|
|
1606
|
+
```bash
|
|
1607
|
+
airctrl mcp-gateway grant-create "$GATEWAY_ID" --subject-type group --subject-id "$GROUP_ID" --access read_only
|
|
1608
|
+
```
|
|
1935
1609
|
|
|
1936
|
-
|
|
1610
|
+
**CLI command:** `airctrl mcp-gateway grant-create`
|
|
1937
1611
|
|
|
1938
1612
|
|
|
1613
|
+
#### Revoke MCP grant
|
|
1614
|
+
```bash
|
|
1615
|
+
airctrl mcp-gateway grant-revoke "$GATEWAY_ID" "$GRANT_ID"
|
|
1616
|
+
```
|
|
1939
1617
|
|
|
1618
|
+
**CLI command:** `airctrl mcp-gateway grant-revoke`
|
|
1619
|
+
|
|
1620
|
+
|
|
1621
|
+
#### Export MCP policy
|
|
1940
1622
|
```bash
|
|
1941
|
-
airctrl
|
|
1623
|
+
airctrl mcp-gateway policy-export "$GATEWAY_ID"
|
|
1942
1624
|
```
|
|
1943
1625
|
|
|
1626
|
+
**CLI command:** `airctrl mcp-gateway policy-export`
|
|
1944
1627
|
|
|
1945
1628
|
|
|
1946
|
-
|
|
1629
|
+
#### Apply MCP policy
|
|
1630
|
+
```bash
|
|
1631
|
+
airctrl mcp-gateway policy-apply "$GATEWAY_ID" ./policy.yml
|
|
1632
|
+
```
|
|
1947
1633
|
|
|
1634
|
+
**CLI command:** `airctrl mcp-gateway policy-apply`
|
|
1948
1635
|
|
|
1949
1636
|
|
|
1950
|
-
####
|
|
1637
|
+
#### List MCP calls
|
|
1638
|
+
```bash
|
|
1639
|
+
airctrl mcp-gateway calls "$GATEWAY_ID"
|
|
1640
|
+
```
|
|
1951
1641
|
|
|
1642
|
+
**CLI command:** `airctrl mcp-gateway calls`
|
|
1952
1643
|
|
|
1953
1644
|
|
|
1954
|
-
|
|
1645
|
+
#### Read MCP metrics
|
|
1646
|
+
```bash
|
|
1647
|
+
airctrl mcp-gateway metrics "$GATEWAY_ID"
|
|
1648
|
+
```
|
|
1955
1649
|
|
|
1650
|
+
**CLI command:** `airctrl mcp-gateway metrics`
|
|
1956
1651
|
|
|
1957
1652
|
|
|
1653
|
+
#### Read retained MCP payload
|
|
1958
1654
|
```bash
|
|
1959
|
-
airctrl
|
|
1655
|
+
airctrl mcp-gateway payload "$GATEWAY_ID" "$CALL_ID"
|
|
1960
1656
|
```
|
|
1961
1657
|
|
|
1658
|
+
**CLI command:** `airctrl mcp-gateway payload`
|
|
1962
1659
|
|
|
1963
1660
|
|
|
1964
|
-
|
|
1661
|
+
#### Export MCP call CSV
|
|
1662
|
+
```bash
|
|
1663
|
+
airctrl mcp-gateway calls-export "$GATEWAY_ID"
|
|
1664
|
+
```
|
|
1965
1665
|
|
|
1666
|
+
**CLI command:** `airctrl mcp-gateway calls-export`
|
|
1966
1667
|
|
|
1967
1668
|
|
|
1968
1669
|
### Common exit behavior
|
|
1969
|
-
|
|
1970
1670
|
Successful commands exit with `0`. Validation, authentication, authorization and missing-resource failures exit with a non-zero status and a stable code on stderr. Do not retry `400`, `403` or `404` failures without changing the request. Retry temporary `429`, `500` and `503` failures with a bounded backoff.
|
|
1971
1671
|
## Use the CLI with Bash
|
|
1972
1672
|
|