@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 CHANGED
@@ -16,26 +16,27 @@ Requires Node.js 22.x.
16
16
 
17
17
  ## Current release
18
18
 
19
- **Coordinated package version:** `0.5.0`
19
+ **Coordinated package version:** `0.6.0`
20
20
 
21
21
  ### SDK
22
22
 
23
- - Added privileged full-text gateway log search, HTTP status-family filtering, and gateway-scoped usage metrics and spend inputs.
24
- - Added native connection URLs for Groq, Novita AI, Atlas Cloud, and xAI to the shared gateway connection builder.
25
- - Added pricing display text and structured rate-card tiers so provider-published zero and context-tiered rates remain explicit.
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 gateway log `--search` and `--status-class` filters plus gateway-scoped usage metrics and spend flags.
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 the same gateway log search and scoped metrics inputs to `read_usage`, `read_usage_metrics`, and `read_usage_spend`.
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.5.0` so clean builds consume the exact release candidate instead of the previously published SDK.
38
- - Retained sealed-candidate certification and manual npm publication with final approval and 2FA.
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
- **CLI command:** `airctrl gateway settings`
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
- #### Review gateway requests
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
- Returns request metadata. Service Accounts may use this read when their role permits it.
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 logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z \
1760
- --status 200 --limit 50
1761
-
1762
- # Continue with pagination.next_cursor from the previous JSON response.
1763
- airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z \
1764
- --status 200 --limit 50 --cursor "$NEXT_CURSOR"
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
- **CLI command:** `airctrl gateway logs`
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 gateway request
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
- Returns stored bodies only when body logging and the required permission are both present.
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 log "$GATEWAY_ID" "$LOG_ID"
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
- **CLI command:** `airctrl gateway log`
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
- #### Review provider-key access
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
- Returns provider-key access decisions without returning provider keys.
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 key-access "$GATEWAY_ID" --outcome denied \
1801
- --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
1802
1379
  ```
1803
1380
 
1381
+ **CLI command:** `airctrl gateway otel-update`
1804
1382
 
1383
+ ### Service Account metadata
1384
+ #### List Service Accounts
1805
1385
 
1806
- **CLI command:** `airctrl gateway key-access`
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
- #### Review project usage logs
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
- 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
+ ```
1815
1409
 
1410
+ **CLI command:** `airctrl mcp-gateway list`
1816
1411
 
1817
1412
 
1413
+ #### Create MCP gateway
1818
1414
  ```bash
1819
- airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
1820
- --since 2026-09-01T00:00:00Z --limit 50
1415
+ airctrl mcp-gateway create --project "$PROJECT_ID" --name Engineering
1416
+ ```
1821
1417
 
1822
- # Keep the exact same filters when continuing a cursor.
1823
- airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
1824
- --since 2026-09-01T00:00:00Z --limit 50 --cursor "$NEXT_CURSOR"
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
- **CLI command:** `airctrl gateway usage-logs`
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
- #### Inspect one project usage log
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
- 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
+ ```
1838
1449
 
1450
+ **CLI command:** `airctrl mcp-gateway delete`
1839
1451
 
1840
1452
 
1453
+ #### Configure MCP runtime
1841
1454
  ```bash
1842
- airctrl gateway usage-log "$LOG_ID" --project "$PROJECT_ID"
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
- **CLI command:** `airctrl gateway usage-log`
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
- #### 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
+ ```
1852
1473
 
1474
+ **CLI command:** `airctrl mcp-gateway server-create`
1853
1475
 
1854
1476
 
1855
- 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
+ ```
1856
1481
 
1482
+ **CLI command:** `airctrl mcp-gateway server-delete`
1857
1483
 
1858
1484
 
1485
+ #### Update MCP server
1859
1486
  ```bash
1860
- airctrl gateway usage-spend --project "$PROJECT_ID"
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
- **CLI command:** `airctrl gateway usage-spend`
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
- #### Review project usage metrics
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
- Returns request, error, token, latency and spend aggregates.
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 usage-metrics --project "$PROJECT_ID" \
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
- **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
+ ```
1885
1529
 
1530
+ **CLI command:** `airctrl mcp-gateway client-create`
1886
1531
 
1887
1532
 
1888
- #### View OpenTelemetry settings
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
- 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
+ ```
1893
1545
 
1546
+ **CLI command:** `airctrl mcp-gateway client-update`
1894
1547
 
1895
1548
 
1549
+ #### List MCP keys
1896
1550
  ```bash
1897
- airctrl gateway otel "$GATEWAY_ID" --account "$ACCOUNT_ID"
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
- **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
+ ```
1903
1561
 
1562
+ **CLI command:** `airctrl mcp-gateway key-create`
1904
1563
 
1905
1564
 
1906
- #### Change OpenTelemetry settings
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
- 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
+ ```
1911
1577
 
1578
+ **CLI command:** `airctrl mcp-gateway policies`
1912
1579
 
1913
1580
 
1581
+ #### Create MCP policy
1914
1582
  ```bash
1915
- airctrl gateway otel-update "$GATEWAY_ID" --account "$ACCOUNT_ID" \
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
- **CLI command:** `airctrl gateway otel-update`
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
- ### Service Account metadata
1597
+ #### List MCP grants
1598
+ ```bash
1599
+ airctrl mcp-gateway grants "$GATEWAY_ID"
1600
+ ```
1928
1601
 
1929
- #### List Service Accounts
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
- Returns safe Service Account metadata to a human PAT.
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 sa list --account "$ACCOUNT_ID"
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
- **CLI command:** `airctrl sa list`
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
- #### View a Service Account
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
- 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
+ ```
1952
1649
 
1650
+ **CLI command:** `airctrl mcp-gateway metrics`
1953
1651
 
1954
1652
 
1653
+ #### Read retained MCP payload
1955
1654
  ```bash
1956
- airctrl sa get "$SERVICE_ACCOUNT_ID" --account "$ACCOUNT_ID"
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
- **CLI command:** `airctrl sa get`
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