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