@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 CHANGED
@@ -16,36 +16,27 @@ Requires Node.js 22.x.
16
16
 
17
17
  ## Current release
18
18
 
19
- **Coordinated package version:** `0.4.0`
19
+ **Coordinated package version:** `0.6.0`
20
20
 
21
21
  ### SDK
22
22
 
23
- - Added `OAuthPartnerClient`, PKCE generation, authorization-code exchange, rotating refresh tokens, and token revocation for confidential partner backends.
24
- - Added provider resolution, provider-key validation, live model discovery, entitlement preflight, atomic protection provisioning, and installation-bound protection reads and updates.
25
- - Added provider-key rotation, runtime-token rotation, revoke, and reactivate lifecycle operations with typed idempotency and error handling.
26
- - Added public multi-organization OAuth Apps: one publisher-owned Client ID can create isolated installations inside customer-selected AIRCTRL organizations.
27
- - Added `listProtectionLogs()` and `getProtectionSpend()` with dedicated least-privilege scopes and strict installation/protection binding.
28
- - Added stable cursor pagination and canonical account, project, gateway, token, principal, trace, and span correlation across request-log, usage, and audit feeds.
29
- - Added OpenTelemetry body-export controls and shared gateway connection types aligned with the public API contract.
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 opaque cursor support to gateway logs, provider-key access, usage logs, record alerts, and record access commands.
34
- - Added the `audit-events` command with cursor, action, actor, and date filters.
35
- - Added OpenTelemetry request/response body-export configuration while preserving the existing header-custody contract.
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 opaque cursor inputs to gateway, usage, record-alert, and record-access tools.
40
- - Added `list_record_audit` with stable filters and pagination.
41
- - Added OpenTelemetry body-export configuration and aligned pagination limits with the API contract.
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
- - Kept SDK, CLI, and MCP manifests, internal dependencies, exported version constants, generated READMEs, and tarball names aligned at `0.4.0`.
46
- - Build `@airctrl/client-contracts` before OpenAPI generation and full-stack certification so clean release runners never depend on cached workspace output.
47
- - Expanded package verification across the public API, generated examples, installed-package behavior, exact tarballs, and Linux, Windows, and macOS certification.
48
- - Kept `@airctrl/crypto` and `@airctrl/secrets` private and bundled the required runtime into the public SDK.
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>] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
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
- **CLI command:** `airctrl gateway settings`
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
- #### Review gateway requests
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
- Returns request metadata. Service Accounts may use this read when their role permits it.
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 logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z \
1763
- --status 200 --limit 50
1764
-
1765
- # Continue with pagination.next_cursor from the previous JSON response.
1766
- airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z \
1767
- --status 200 --limit 50 --cursor "$NEXT_CURSOR"
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
- **CLI command:** `airctrl gateway logs`
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 gateway request
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
- Returns stored bodies only when body logging and the required permission are both present.
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 log "$GATEWAY_ID" "$LOG_ID"
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
- **CLI command:** `airctrl gateway log`
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
- #### Review provider-key access
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
- Returns provider-key access decisions without returning provider keys.
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 key-access "$GATEWAY_ID" --outcome denied \
1804
- --since 2026-09-01T00:00:00Z --limit 50 --offset 0
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
- **CLI command:** `airctrl gateway key-access`
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
- #### Review project usage logs
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
- Returns usage metadata across the selected project.
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 usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
1823
- --since 2026-09-01T00:00:00Z --limit 50
1415
+ airctrl mcp-gateway create --project "$PROJECT_ID" --name Engineering
1416
+ ```
1824
1417
 
1825
- # Keep the exact same filters when continuing a cursor.
1826
- airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
1827
- --since 2026-09-01T00:00:00Z --limit 50 --cursor "$NEXT_CURSOR"
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
- **CLI command:** `airctrl gateway usage-logs`
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
- #### Inspect one project usage log
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
- Returns one project log and any stored bodies allowed by RBAC.
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 usage-log "$LOG_ID" --project "$PROJECT_ID"
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
- **CLI command:** `airctrl gateway usage-log`
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
- #### Review project spend
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
- Returns current spend and the effective project or account limit.
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 usage-spend --project "$PROJECT_ID"
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
- **CLI command:** `airctrl gateway usage-spend`
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
- #### Review project usage metrics
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
- Returns request, error, token, latency and spend aggregates.
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 usage-metrics --project "$PROJECT_ID" \
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
- **CLI command:** `airctrl gateway usage-metrics`
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
- #### View OpenTelemetry settings
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
- Returns safe OpenTelemetry settings. Secret header values are never returned.
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 otel "$GATEWAY_ID" --account "$ACCOUNT_ID"
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
- **CLI command:** `airctrl gateway otel`
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
- #### Change OpenTelemetry settings
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
- The CLI reads header values from the named environment variable. Use `--clear-headers true` to remove stored headers.
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 otel-update "$GATEWAY_ID" --account "$ACCOUNT_ID" \
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
- **CLI command:** `airctrl gateway otel-update`
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
- ### Service Account metadata
1597
+ #### List MCP grants
1598
+ ```bash
1599
+ airctrl mcp-gateway grants "$GATEWAY_ID"
1600
+ ```
1931
1601
 
1932
- #### List Service Accounts
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
- Returns safe Service Account metadata to a human PAT.
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 sa list --account "$ACCOUNT_ID"
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
- **CLI command:** `airctrl sa list`
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
- #### View a Service Account
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
- Returns one Service Account from the safe metadata list. Lifecycle and credential actions remain dashboard-only.
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 sa get "$SERVICE_ACCOUNT_ID" --account "$ACCOUNT_ID"
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
- **CLI command:** `airctrl sa get`
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