@airctrl/cli 0.0.0-stage → 0.4.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
@@ -1,3 +1,2081 @@
1
- # Temporary Holding Version
1
+ # @airctrl/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The AIRCTRL command-line client for encrypted records, process injection, projects, gateways and Service Accounts.
4
+
5
+ [Documentation](https://docs.airctrl.dev) · [AIRCTRL](https://airctrl.dev) · [Support](https://docs.airctrl.dev/reference/errors)
6
+
7
+ > This README is generated from AIRCTRL's verified public documentation. The HTTP API is the capability source of truth; SDK, CLI and MCP are thin bindings over that contract.
8
+
9
+ ## Install
10
+
11
+ ```sh
12
+ npm install --global @airctrl/cli
13
+ ```
14
+
15
+ Requires Node.js 22.x.
16
+
17
+ ## Current release
18
+
19
+ **Coordinated package version:** `0.4.0`
20
+
21
+ ### SDK
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.
30
+
31
+ ### CLI
32
+
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.
36
+
37
+ ### MCP
38
+
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.
42
+
43
+ ### Release engineering
44
+
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.
49
+
50
+ ## CLI overview
51
+
52
+ `@airctrl/cli` lets you work with AIRCTRL from a terminal and inject records into a process without creating a local `.env` file.
53
+
54
+ ### Install
55
+
56
+ ```bash
57
+ npm install --global @airctrl/cli
58
+ ```
59
+
60
+ The CLI requires Node.js 22.x.
61
+
62
+ You can also run it without a global installation:
63
+
64
+ ```bash
65
+ npx @airctrl/cli --help
66
+ ```
67
+
68
+ ### Human login
69
+
70
+ ```bash
71
+ airctrl login
72
+ ```
73
+
74
+ The command asks for:
75
+
76
+ - API base URL.
77
+ - Personal Access Token.
78
+ - Optional default project ID.
79
+
80
+ It saves this human configuration in `~/.airctrl/config.json`.
81
+
82
+ For non-interactive jobs, use:
83
+
84
+ | Variable | Purpose |
85
+ |---|---|
86
+ | `AC_API_BASE_URL` | AIRCTRL API URL. |
87
+ | `AC_TOKEN` | Human PAT or the bearer from a complete Service Account bundle. |
88
+ | `AC_VAULT_PASSWORD` | Human vault passphrase for local record cryptography. |
89
+
90
+ ### Service Account execution
91
+
92
+ An active Service Account requires `AC_TOKEN`, `AC_API_BASE_URL`, `AC_SA_CREDENTIAL_ID`, and `AC_SA_CAP_PRIVATE_KEY_B64` from one credential bundle. `AC_SA_SERVICE_ACCOUNT_ID` carries the bundle identity when available.
93
+
94
+ Do not mix fields from different bundles. An incomplete Service Account environment fails instead of falling back to human mode.
95
+
96
+ `--profile <name>` only selects an active Service Account profile that already exists in the CLI profile store. It does not import a bundle or create a credential. Service Account credential lifecycle is Web-only; when you have only an active bundle, use the environment variables above instead of creating or editing profile JSON manually.
97
+
98
+ Service Account mode exposes a smaller command set for unattended record and Gateway work. Human-only
99
+ commands fail before an SDK or API call. See [CLI commands](https://docs.airctrl.dev/cli/commands) for the exact list.
100
+
101
+ ### Inject records
102
+
103
+ ```bash
104
+ airctrl run --project "$PROJECT_ID" -- node server.js
105
+ ```
106
+
107
+ The CLI:
108
+
109
+ 1. Reads accessible records in that project.
110
+ 2. Decrypts them locally.
111
+ 3. Converts record names to uppercase environment keys.
112
+ 4. Removes AIRCTRL control variables from the child environment.
113
+ 5. Starts the child process with the record values in memory.
114
+
115
+ It does not write a `.env` file.
116
+
117
+ The CLI login belongs only to the CLI. SDK applications and MCP servers must receive their own explicit configuration. See [Combine AIRCTRL tools](https://docs.airctrl.dev/guides/tool-workflows) for safe mixed workflows.
118
+
119
+ ### Output and errors
120
+
121
+ Read commands print JSON or the requested value to stdout. Operational messages and stable errors use stderr. A failed command returns a non-zero exit status.
122
+
123
+ See [CLI commands](https://docs.airctrl.dev/cli/commands) and [Errors and retries](https://docs.airctrl.dev/reference/errors).
124
+ ## CLI commands
125
+
126
+ Use `--profile <name>` on supported commands only when an active Service Account profile already exists in the CLI profile store. The flag selects that profile; it does not import a bundle or create a credential. Service Account credential lifecycle is Web-only. When you have only an active bundle, configure the documented `AC_*` environment variables instead. Run a command family without a subcommand to display its built-in help.
127
+
128
+ For one copy-ready command example per command, continue to [CLI examples](https://docs.airctrl.dev/cli/examples).
129
+
130
+ ### Identity availability
131
+
132
+ A human PAT can use every API-backed command below when RBAC permits it. Local commands such as
133
+ `login` and `generate` do not require API authorization. A Service Account can use only:
134
+
135
+ ```text
136
+ airctrl get <recordId> [--env development|staging|production]
137
+ airctrl read <recordId> [--scope a,b] [--env development|staging|production]
138
+ airctrl run --project <id> [--env development|staging|production] -- <command> [args]
139
+ airctrl generate <format> [--option value] # local only
140
+ airctrl record list [--project <id>] [--tab shared]
141
+ airctrl gateway providers
142
+ airctrl gateway get <gatewayId>
143
+ airctrl gateway tokens <gatewayId>
144
+ airctrl gateway logs <gatewayId>
145
+ airctrl gateway log <gatewayId> <logId>
146
+ airctrl gateway key-access <gatewayId>
147
+ ```
148
+
149
+ The CLI rejects every other command before making an SDK or API call. RBAC can still deny a command
150
+ from this list when the Service Account lacks the required custom-role permission or project access.
151
+
152
+ ### Core record commands
153
+
154
+ ```text
155
+ airctrl login
156
+ airctrl get <recordId> [--env development|staging|production] [--profile <name>]
157
+ airctrl read <recordId> [--scope a,b] [--env development|staging|production] [--profile <name>]
158
+ airctrl run --project <id> [--env development|staging|production] [--profile <name>] -- <command> [args]
159
+ airctrl generate <format> [--option value]
160
+ airctrl create <format> --name <name> [--project <id>] [--field key=value]
161
+ [--env development|staging|production] [--tags a,b|none] [--secret-due <iso|null>]
162
+ [--rotation-days <n|null>] [--idempotency-key <key>]
163
+ airctrl set <format> --name <name> [--project <id>] [--field key=value]
164
+ [--env development|staging|production] [--tags a,b|none] [--secret-due <iso|null>]
165
+ [--rotation-days <n|null>] [--idempotency-key <key>]
166
+ airctrl new <format> --name <name> [--project <id>] [--option value]
167
+ [--env development|staging|production] [--tags a,b|none] [--secret-due <iso|null>]
168
+ [--rotation-days <n|null>] [--idempotency-key <key>]
169
+ airctrl import env <file> --name <name> [--project <id>] [--target-env <name>]
170
+ [--env development|staging|production] [--tags a,b|none] [--secret-due <iso|null>]
171
+ [--rotation-days <n|null>] [--idempotency-key <key>]
172
+ ```
173
+
174
+ `generate` only returns locally generated fields. `new` generates, encrypts and stores them. `set` updates a matching record or creates it when human mode has enough information.
175
+
176
+ ### Project commands
177
+
178
+ ```text
179
+ airctrl project accounts
180
+ airctrl project list --account <id> [--include-archived true|false]
181
+ airctrl project get <projectId> --account <id>
182
+ airctrl project create --account <id> --name <name> [--description <text>]
183
+ airctrl project update <projectId> --account <id> --name <name> --description <text|null> --active true|false
184
+ airctrl project archive <projectId> --account <id>
185
+ airctrl project restore <projectId> --account <id>
186
+ ```
187
+
188
+ ### Group commands
189
+
190
+ Human PAT only. All commands require `--account`; Team+ and RBAC apply. A group is reusable within its account. Creating it does not grant a project role.
191
+
192
+ ```text
193
+ airctrl group list <projectId> --account <id>
194
+ airctrl group record-grants <recordId> --account <id>
195
+ airctrl group create <projectId> --account <id> --name <name> [--description <text>]
196
+ airctrl group update <groupId> --account <id> --name <name> [--description <text>]
197
+ airctrl group delete <groupId> --account <id>
198
+ airctrl group members <groupId> --account <id>
199
+ airctrl group add-member <groupId> <userId> --account <id>
200
+ airctrl group remove-member <groupId> <userId> --account <id>
201
+ airctrl group grant-project <projectId> <groupId> <roleId> --account <id>
202
+ airctrl group revoke-project <projectId> <groupId> <roleId> --account <id>
203
+ airctrl group reconcile --account <id> [--project <id>]
204
+ ```
205
+
206
+ `update` replaces name and description; omitting description clears it. Membership, deletion and grant writes return the server's change snapshot, including pending material and remaining access sources. Removing one path preserves other authorized paths. Revocations need no vault unlock.
207
+
208
+ `reconcile` uses the configured local passphrase to attempt encrypted-material repair as an authorized holder; it never grants access. Its `attemptedProjectIds` are attempts, not proof that recipients can decrypt. Omitting `--project` attempts readable projects in the account. Pending direct group-record shares in the account are repaired in either mode; unavailable holder material can remain pending. See [Groups and effective access](https://docs.airctrl.dev/guides/projects#groups-and-effective-access).
209
+
210
+ The SDK group catalog exposes available role IDs and member candidates. `group list` and `group members` return context groups and current members; they are not catalog/candidate switches.
211
+
212
+ ### Record management commands
213
+
214
+ ```text
215
+ airctrl record list [--account <id>] [--project <id>] [--tab owned|shared]
216
+ [--include-archived true|false] [--limit <n>] [--offset <n>]
217
+ airctrl record versions <recordId>
218
+ airctrl record audit <recordId> [--limit <n>]
219
+ airctrl record audit-events <recordId> [--cursor <opaque>] [--action <name>] [--actor <text>]
220
+ [--from <iso>] [--to <iso>] [--limit <n>] [--offset <legacy-n>]
221
+ airctrl record anomalies [--account <id>] [--scope-type user|project] [--scope-id <id>]
222
+ airctrl record activity <YYYY-MM-DD> [--account <id>] [--scope-type user|project] [--scope-id <id>]
223
+ airctrl record alerts [--account <id>] [--scope-type user|project] [--scope-id <id>]
224
+ [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
225
+ airctrl record access [--account <id>] [--scope-type user|project] [--scope-id <id>]
226
+ [--actions a,b] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
227
+ airctrl record metadata <recordId> [--name <name>] [--tags a,b|none]
228
+ [--env development|staging|production] [--secret-due <iso|null>] [--rotation-days <n|null>]
229
+ airctrl record archive <recordId>
230
+ airctrl record restore <recordId>
231
+ airctrl record transfer <recordId> --owner <userId>
232
+ airctrl record rollback <recordId> --version <versionId>
233
+ airctrl record set <recordId> --field <key=value> [--field <key=value> ...]
234
+ [--env development|staging|production] [--idempotency-key <key>]
235
+ airctrl record rotate <recordId>
236
+ airctrl record share-user <recordId> --user <id> [--permission view|read]
237
+ airctrl record share-sa <recordId> --account <id> --service-account <id>
238
+ airctrl record share-group <recordId> --group <id>
239
+ airctrl record revoke-user <recordId> --user <id>
240
+ airctrl record revoke-sa <recordId> --service-account <id>
241
+ airctrl record revoke-group <recordId> --group <id>
242
+ ```
243
+
244
+ Project audit scope requires both `--scope-type project` and `--scope-id`.
245
+
246
+ ### Gateway commands
247
+
248
+ Discovery and lifecycle:
249
+
250
+ ```text
251
+ airctrl gateway providers
252
+ airctrl gateway list --project <id>
253
+ airctrl gateway get <gatewayId>
254
+ airctrl gateway create --account <id> --project <id> --name <name>
255
+ [--slug <slug>] [--credential-binding <credentialId=modelId>]
256
+ airctrl gateway update <gatewayId> --account <id>
257
+ [--name <name>] [--active true|false]
258
+ airctrl gateway delete <gatewayId> --account <id>
259
+ ```
260
+
261
+ Gateway tokens:
262
+
263
+ ```text
264
+ airctrl gateway tokens <gatewayId>
265
+ airctrl gateway token-create <gatewayId> --account <id> --name <name>
266
+ [--expires-days <n>] [--scopes run,read_logs,manage]
267
+ [--principal-type user|service_account --principal-id <id>]
268
+ [--allowed-models a,b] [--spend-limit <amount>]
269
+ [--spend-window daily|weekly|monthly] [--rate-limit <n>]
270
+ airctrl gateway token-rename <gatewayId> <tokenId> --account <id> --name <name>
271
+ airctrl gateway token-revoke <gatewayId> <tokenId> --account <id>
272
+ airctrl gateway token-delete <gatewayId> <tokenId> --account <id>
273
+ ```
274
+
275
+ Settings and credentials:
276
+
277
+ ```text
278
+ airctrl gateway settings <gatewayId> --account <id>
279
+ [--spend-limit <amount|null>] [--spend-window daily|weekly|monthly]
280
+ [--rate-limit <n|null>] [--logging true|false] [--log-bodies true|false]
281
+ [--guardrail off|flag|redact|block] [--allowed-models a,b|none]
282
+ airctrl gateway credential-attach <gatewayId> <credentialId> --account <id>
283
+ --model <name> [--model <name> ...]
284
+ airctrl gateway credential-detach <gatewayId> <credentialId> --account <id> [--model <name>]
285
+ airctrl gateway provider-credentials --account <id>
286
+ airctrl gateway provider-credential-create --account <id> --provider <id>
287
+ --label <name> --api-key-env <variable> [--base-url <url|null>]
288
+ [--kind api_key|oauth|aws_sigv4|gcp_sa]
289
+ airctrl gateway provider-models <credentialId> --account <id>
290
+ airctrl gateway provider-credential-rotate <credentialId> --account <id> --api-key-env <variable>
291
+ airctrl gateway provider-credential-update <credentialId> --account <id> --label <name>
292
+ airctrl gateway provider-credential-revoke <credentialId> --account <id>
293
+ ```
294
+
295
+ Observability:
296
+
297
+ ```text
298
+ airctrl gateway logs <gatewayId> [--since <iso>] [--provider <id>] [--model <name>]
299
+ [--status <code>] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
300
+ airctrl gateway log <gatewayId> <logId>
301
+ 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>]
304
+ [--model <name>] [--status <code>] [--gateway <id>] [--cursor <opaque>]
305
+ [--limit <n>] [--offset <legacy-n>]
306
+ 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]
309
+ airctrl gateway otel <gatewayId> --account <id>
310
+ airctrl gateway otel-update <gatewayId> --account <id>
311
+ [--enabled true|false] [--endpoint <url|null>] [--metrics true|false]
312
+ [--traces true|false] [--bodies true|false]
313
+ [--headers-env <variable>] [--clear-headers true|false]
314
+ ```
315
+
316
+ Provider credentials and OpenTelemetry headers are read from named environment variables. Their values do not belong in command arguments.
317
+
318
+ ### Service Account metadata commands
319
+
320
+ ```text
321
+ airctrl sa list --account <id>
322
+ airctrl sa get <serviceAccountId> --account <id>
323
+ ```
324
+
325
+ The public CLI does not create, pause, reactivate, delete, provision, rotate or revoke Service Account credentials.
326
+
327
+ ### Argument rules
328
+
329
+ - Values in angle brackets are required. Values in square brackets are optional.
330
+ - UUID arguments must be complete AIRCTRL IDs. Names are not accepted where an ID is required.
331
+ - `--account` selects account context. It does not add permissions.
332
+ - `--project` limits an operation to one project.
333
+ - `--profile` selects a stored Service Account profile for commands that support machine identity.
334
+ - `--scope` on `airctrl read` selects record sections: `fields`, `meta`, `owner`, `access`, or `full`. It does not select individual field names.
335
+ - Omit `--env` for a General record. Pass `--env development`, `--env staging`, or `--env production` to select that record value. The PAT or Service Account token must permit the selected scope; access never falls back to General or another value.
336
+ - `--target-env` on `airctrl import env` is a field stored inside that ENV-format record. It is separate from `--env`, which selects the record's encrypted value.
337
+ - Repeat `--field key=value`, `--model <name>`, or `--credential-binding <credentialId=modelId>` when you need more than one value.
338
+ - `--tags none`, `--secret-due null`, and `--rotation-days null` clear those optional values. A positive integer is required for `--rotation-days`.
339
+ - `--idempotency-key` identifies one intended record write. Reuse it only when retrying the same input.
340
+ - Use `null` only where the command syntax explicitly accepts it. It clears the stored optional value.
341
+ - Use `none` only where documented. It replaces a list with an empty list.
342
+ - Boolean flags accept only `true` or `false`.
343
+
344
+ Run a command family without a subcommand to see the installed version's exact syntax:
345
+
346
+ ```bash
347
+ airctrl project
348
+ airctrl record
349
+ airctrl gateway
350
+ airctrl sa
351
+ ```
352
+
353
+ ### Output
354
+
355
+ Normal commands write formatted JSON to stdout. Scripts should read stdout as JSON and use the process
356
+ exit status to decide whether the operation completed. Diagnostic text and stable error codes go to
357
+ stderr. Commands that return no resource print `{ "ok": true }`.
358
+
359
+ ```bash
360
+ if result="$(airctrl project get "$PROJECT_ID" --account "$AIRCTRL_ACCOUNT_ID")"; then
361
+ printf '%s\n' "$result"
362
+ else
363
+ status=$?
364
+ printf 'AIRCTRL failed with exit status %s\n' "$status" >&2
365
+ exit "$status"
366
+ fi
367
+ ```
368
+
369
+ One-time values, including newly created gateway tokens, are printed once. Redirect them only into an
370
+ approved custody process. Do not write them to a shared terminal log.
371
+
372
+ ### Complete workflow examples
373
+
374
+ Create and inspect a project:
375
+
376
+ ```bash
377
+ airctrl project create \
378
+ --account "$AIRCTRL_ACCOUNT_ID" \
379
+ --name "Payments" \
380
+ --description "Credentials for the payments service"
381
+
382
+ airctrl project list --account "$AIRCTRL_ACCOUNT_ID"
383
+ ```
384
+
385
+ Create a record without putting its secret value in command history:
386
+
387
+ ```bash
388
+ airctrl import env ./payments.env \
389
+ --project "$PROJECT_ID" \
390
+ --name "Payments environment" \
391
+ --target-env production
392
+ ```
393
+
394
+ Read metadata, then inject decrypted values only into a child process:
395
+
396
+ ```bash
397
+ airctrl record list --project "$PROJECT_ID" --limit 50
398
+ airctrl run --project "$PROJECT_ID" -- npm run dev
399
+ ```
400
+
401
+ Change safe metadata and review immutable history:
402
+
403
+ ```bash
404
+ airctrl record metadata "$RECORD_ID" --tags payments,production --rotation-days 90
405
+ airctrl record versions "$RECORD_ID"
406
+ airctrl record audit "$RECORD_ID" --limit 25
407
+ ```
408
+
409
+ Share a record, then revoke the same grant:
410
+
411
+ ```bash
412
+ airctrl record share-user "$RECORD_ID" --user "$USER_ID" --permission read
413
+ airctrl record revoke-user "$RECORD_ID" --user "$USER_ID"
414
+ ```
415
+
416
+ Create a provider credential from an environment variable, then create a gateway:
417
+
418
+ ```bash
419
+ export OPENAI_PRODUCTION_KEY="<loaded-by-your-runtime>"
420
+
421
+ airctrl gateway provider-credential-create \
422
+ --account "$AIRCTRL_ACCOUNT_ID" \
423
+ --provider "$PROVIDER_ID" \
424
+ --label "Production OpenAI" \
425
+ --api-key-env OPENAI_PRODUCTION_KEY
426
+
427
+ airctrl gateway create \
428
+ --account "$AIRCTRL_ACCOUNT_ID" \
429
+ --project "$PROJECT_ID" \
430
+ --name "Payments AI" \
431
+ --provider "$PROVIDER_ID" \
432
+ --credential "$PROVIDER_CREDENTIAL_ID"
433
+ ```
434
+
435
+ Create a short-lived gateway token and inspect usage without reading stored bodies:
436
+
437
+ ```bash
438
+ airctrl gateway token-create "$GATEWAY_ID" \
439
+ --account "$AIRCTRL_ACCOUNT_ID" \
440
+ --name "Local development" \
441
+ --expires-days 30 \
442
+ --scopes run,read_logs \
443
+ --rate-limit 60
444
+
445
+ airctrl gateway logs "$GATEWAY_ID" --limit 25
446
+ airctrl gateway usage-metrics --project "$PROJECT_ID" --bucket day
447
+ airctrl gateway usage-spend --project "$PROJECT_ID"
448
+ ```
449
+
450
+ Read safe Service Account metadata as a human:
451
+
452
+ ```bash
453
+ airctrl sa list --account "$AIRCTRL_ACCOUNT_ID"
454
+ airctrl sa get "$SERVICE_ACCOUNT_ID" --account "$AIRCTRL_ACCOUNT_ID"
455
+ ```
456
+
457
+ Run the supported read-only subset with an active Service Account profile:
458
+
459
+ ```bash
460
+ airctrl record list --project "$PROJECT_ID" --profile ci
461
+ airctrl get "$RECORD_ID" --profile ci
462
+ airctrl gateway logs "$GATEWAY_ID" --profile ci
463
+ ```
464
+
465
+ ### OAuth partner Apps
466
+
467
+ The CLI has no OAuth App profile, authorization-code flow, or connection/protection lifecycle
468
+ commands. Do not place OAuth client secrets, authorization codes, access tokens, or refresh tokens in
469
+ its PAT/Service Account profiles or shell history. Those values belong in a confidential partner
470
+ backend.
471
+
472
+ Implement OAuth partner flows through the standards-based direct HTTP contract or
473
+ `OAuthPartnerClient`. See [OAuth partner integrations](https://docs.airctrl.dev/guides/oauth-partner-integrations),
474
+ [OAuth protocol](https://docs.airctrl.dev/reference/oauth-protocol), and
475
+ [OAuth protection API](https://docs.airctrl.dev/reference/oauth-protections). The CLI may still manage ordinary gateways with
476
+ a separately authorized human PAT; that is not the OAuth installation identity.
477
+
478
+ ### CLI failures
479
+
480
+ | Code or condition | Meaning | What to do |
481
+ |---|---|---|
482
+ | `cli_unknown_command` | The command or subcommand is not supported. | Run the command family without a subcommand. |
483
+ | `cli_flag_missing_value` | A required positional value or flag is missing. | Compare the call with the syntax above. |
484
+ | `cli_flag_invalid_value` | A number, boolean, enum, date or list has an invalid value. | Correct the local input; no API call was made. |
485
+ | `service_account_not_supported` | The selected profile tried a human-only operation. | Use a human PAT or choose an operation listed in Identity availability. |
486
+ | `not_authorized` or `insufficient_permission` | The identity lacks RBAC or resource access. | Request the required role or project grant. Do not retry unchanged. |
487
+ | `record_not_found`, `project_not_found`, `gateway_not_found` | The ID is wrong or unavailable to the identity. | Verify the ID and active account or project. |
488
+ | `rate_limited` | The request limit was exceeded. | Wait and retry with bounded backoff. |
489
+
490
+ The CLI never treats an incomplete Service Account profile as a human login. Fix the profile instead of
491
+ adding a human PAT to the same machine configuration.
492
+ ## CLI example catalog
493
+
494
+ 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
+ ### Prepare the examples
497
+
498
+ The examples assume these non-secret IDs are already available:
499
+
500
+ ```bash
501
+ export AIRCTRL_ACCOUNT_ID="00000000-0000-4000-8000-000000000001"
502
+ export PROJECT_ID="00000000-0000-4000-8000-000000000010"
503
+ export RECORD_ID="00000000-0000-4000-8000-000000000020"
504
+ export GATEWAY_ID="00000000-0000-4000-8000-000000000030"
505
+ export IDEMPOTENCY_KEY="00000000-0000-4000-8000-000000000090"
506
+ ```
507
+
508
+ Use `airctrl project accounts`, `airctrl project list`, `airctrl record list` and `airctrl gateway list`
509
+ 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
+ Every flag takes a separate value. Booleans use `true` or `false`; lists use comma-separated values;
512
+ repeatable inputs repeat the flag. Run `airctrl project`, `airctrl record`, `airctrl gateway` or
513
+ `airctrl sa` to see the exact syntax installed on the machine.
514
+
515
+ ### Local setup and record access
516
+
517
+ #### Sign in to AIRCTRL
518
+
519
+
520
+
521
+ 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
+
523
+
524
+
525
+ ```bash
526
+ airctrl login
527
+ ```
528
+
529
+
530
+
531
+ **CLI command:** `airctrl login`
532
+
533
+
534
+
535
+ #### Read a complete record
536
+
537
+
538
+
539
+ 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
+
541
+
542
+
543
+ ```bash
544
+ airctrl get "$RECORD_ID"
545
+ ```
546
+
547
+ For a By Environment record, select exactly one value:
548
+
549
+ ```bash
550
+ airctrl get "$RECORD_ID" --env staging
551
+ ```
552
+
553
+
554
+
555
+ **CLI command:** `airctrl get`
556
+
557
+
558
+
559
+ #### Read selected record sections
560
+
561
+
562
+
563
+ 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
+
565
+
566
+
567
+ ```bash
568
+ airctrl read "$RECORD_ID" --scope meta,fields
569
+ ```
570
+
571
+ To read the Staging value of an Environment record:
572
+
573
+ ```bash
574
+ airctrl read "$RECORD_ID" --scope meta,fields --env staging
575
+ ```
576
+
577
+
578
+
579
+ **CLI command:** `airctrl read`
580
+
581
+
582
+
583
+ #### Inject records into a process
584
+
585
+
586
+
587
+ 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
+
589
+
590
+
591
+ ```bash
592
+ airctrl run --project "$PROJECT_ID" -- npm run dev
593
+ ```
594
+
595
+ ```bash
596
+ airctrl run --project "$PROJECT_ID" --env staging -- npm run dev
597
+ ```
598
+
599
+
600
+
601
+ **CLI command:** `airctrl run`
602
+
603
+
604
+
605
+ #### Generate a secret locally
606
+
607
+
608
+
609
+ Generate secret material locally without storing it. The generated fields are printed once. This command does not call the API.
610
+
611
+
612
+
613
+ ```bash
614
+ airctrl generate password --length 32
615
+ ```
616
+
617
+
618
+
619
+ **CLI command:** `airctrl generate`
620
+
621
+
622
+
623
+ #### Create an encrypted record
624
+
625
+
626
+
627
+ 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
+
629
+
630
+
631
+ ```bash
632
+ airctrl create password --project "$PROJECT_ID" --name "Database login" \
633
+ --field service_name=Database --field username=app_user --field password="$DATABASE_PASSWORD" \
634
+ --tags database,production --rotation-days 90 \
635
+ --idempotency-key "$IDEMPOTENCY_KEY"
636
+ ```
637
+
638
+
639
+
640
+ **CLI command:** `airctrl create`
641
+
642
+
643
+
644
+ #### Create or replace record fields
645
+
646
+
647
+
648
+ Update a matching record or create it when it does not exist. The result states whether AIRCTRL created or updated the record.
649
+
650
+
651
+
652
+ ```bash
653
+ airctrl set plain --project "$PROJECT_ID" --name "Payments token" \
654
+ --field body="$PAYMENTS_TOKEN" \
655
+ --idempotency-key "$IDEMPOTENCY_KEY"
656
+ ```
657
+
658
+
659
+
660
+ **CLI command:** `airctrl set`
661
+
662
+
663
+
664
+ #### Create a generated record
665
+
666
+
667
+
668
+ 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
+
670
+
671
+
672
+ ```bash
673
+ airctrl new certificate --project "$PROJECT_ID" --name "Generated TLS certificate" --cn api.example.invalid
674
+ ```
675
+
676
+
677
+
678
+ **CLI command:** `airctrl new`
679
+
680
+
681
+
682
+ #### Import environment variables
683
+
684
+
685
+
686
+ 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
+
688
+
689
+
690
+ ```bash
691
+ airctrl import env ./.env.production --project "$PROJECT_ID" \
692
+ --name "Production environment" --target-env production
693
+ ```
694
+
695
+
696
+
697
+ **CLI command:** `airctrl import`
698
+
699
+
700
+
701
+ ### Account and project commands
702
+
703
+ #### List accessible accounts
704
+
705
+
706
+
707
+ Returns accounts available to the human PAT. Service Accounts cannot discover accounts.
708
+
709
+
710
+
711
+ ```bash
712
+ airctrl project accounts
713
+ ```
714
+
715
+
716
+
717
+ **CLI command:** `airctrl project accounts`
718
+
719
+
720
+
721
+ #### List projects
722
+
723
+
724
+
725
+ Returns accessible projects in the selected account.
726
+
727
+
728
+
729
+ ```bash
730
+ airctrl project list --account "$ACCOUNT_ID" --include-archived false
731
+ ```
732
+
733
+
734
+
735
+ **CLI command:** `airctrl project list`
736
+
737
+
738
+
739
+ #### View a project
740
+
741
+
742
+
743
+ Returns one project or a not-found result when it is unavailable.
744
+
745
+
746
+
747
+ ```bash
748
+ airctrl project get "$PROJECT_ID" --account "$ACCOUNT_ID"
749
+ ```
750
+
751
+
752
+
753
+ **CLI command:** `airctrl project get`
754
+
755
+
756
+
757
+ #### Create a project
758
+
759
+
760
+
761
+ Returns the new project ID. The caller becomes its Project Administrator.
762
+
763
+
764
+
765
+ ```bash
766
+ airctrl project create --account "$ACCOUNT_ID" --name "Payments" \
767
+ --description "Credentials used by the payments service"
768
+ ```
769
+
770
+
771
+
772
+ **CLI command:** `airctrl project create`
773
+
774
+
775
+
776
+ #### Update a project
777
+
778
+
779
+
780
+ This command replaces all three editable values, so pass the values you want to keep.
781
+
782
+
783
+
784
+ ```bash
785
+ airctrl project update "$PROJECT_ID" --account "$ACCOUNT_ID" \
786
+ --name "Payments production" --description "Production credentials" --active true
787
+ ```
788
+
789
+
790
+
791
+ **CLI command:** `airctrl project update`
792
+
793
+
794
+
795
+ #### Archive a project
796
+
797
+
798
+
799
+ Archived projects remain stored but leave normal active lists.
800
+
801
+
802
+
803
+ ```bash
804
+ airctrl project archive "$PROJECT_ID" --account "$ACCOUNT_ID"
805
+ ```
806
+
807
+
808
+
809
+ **CLI command:** `airctrl project archive`
810
+
811
+
812
+
813
+ #### Restore a project
814
+
815
+
816
+
817
+ Returns the restored project state.
818
+
819
+
820
+
821
+ ```bash
822
+ airctrl project restore "$PROJECT_ID" --account "$ACCOUNT_ID"
823
+ ```
824
+
825
+
826
+
827
+ **CLI command:** `airctrl project restore`
828
+
829
+
830
+
831
+ ### Record metadata and history
832
+
833
+ #### List record metadata
834
+
835
+
836
+
837
+ Returns safe metadata, not decrypted fields. Service Account results are limited by its grants and custom role.
838
+
839
+
840
+
841
+ ```bash
842
+ airctrl record list --project "$PROJECT_ID" --tab owned --limit 50 --offset 0
843
+ ```
844
+
845
+
846
+
847
+ **CLI command:** `airctrl record list`
848
+
849
+
850
+
851
+ #### View record version history
852
+
853
+
854
+
855
+ Returns encrypted version metadata in newest-first order.
856
+
857
+
858
+
859
+ ```bash
860
+ airctrl record versions "$RECORD_ID"
861
+ ```
862
+
863
+
864
+
865
+ **CLI command:** `airctrl record versions`
866
+
867
+
868
+
869
+ #### Review one record's audit history
870
+
871
+
872
+
873
+ Returns recent audit events when the caller can view this record's audit history.
874
+
875
+
876
+
877
+ ```bash
878
+ airctrl record audit "$RECORD_ID" --limit 25
879
+ ```
880
+
881
+
882
+
883
+ **CLI command:** `airctrl record audit`
884
+
885
+
886
+
887
+ #### Page and filter one record's audit history
888
+
889
+ ```bash
890
+ airctrl record audit-events "$RECORD_ID" --action record.update --actor david --limit 25
891
+ # Continue with pagination.next_cursor from the previous JSON response.
892
+ airctrl record audit-events "$RECORD_ID" --action record.update --actor david \
893
+ --limit 25 --cursor "$NEXT_CURSOR"
894
+ ```
895
+
896
+
897
+
898
+ **CLI command:** `airctrl record audit-events`
899
+
900
+
901
+
902
+ #### Find unusual record activity
903
+
904
+
905
+
906
+ Returns unusual record events for the selected scope.
907
+
908
+
909
+
910
+ ```bash
911
+ airctrl record anomalies --account "$ACCOUNT_ID" --scope-type project --scope-id "$PROJECT_ID"
912
+ ```
913
+
914
+
915
+
916
+ **CLI command:** `airctrl record anomalies`
917
+
918
+
919
+
920
+ #### Review daily record activity
921
+
922
+
923
+
924
+ The date is UTC and must use `YYYY-MM-DD`.
925
+
926
+
927
+
928
+ ```bash
929
+ airctrl record activity 2026-09-10 --account "$ACCOUNT_ID" \
930
+ --scope-type project --scope-id "$PROJECT_ID"
931
+ ```
932
+
933
+
934
+
935
+ **CLI command:** `airctrl record activity`
936
+
937
+
938
+
939
+ #### Review record alerts
940
+
941
+
942
+
943
+ Returns the paginated alert feed.
944
+
945
+
946
+
947
+ ```bash
948
+ airctrl record alerts --account "$ACCOUNT_ID" --scope-type project \
949
+ --scope-id "$PROJECT_ID" --limit 25 --offset 0
950
+ ```
951
+
952
+
953
+
954
+ **CLI command:** `airctrl record alerts`
955
+
956
+
957
+
958
+ #### Review secret access events
959
+
960
+
961
+
962
+ Returns matching record access events. Action names are exact strings.
963
+
964
+
965
+
966
+ ```bash
967
+ airctrl record access --account "$ACCOUNT_ID" --scope-type project \
968
+ --scope-id "$PROJECT_ID" --actions record.secret_access,record.read --limit 25
969
+ ```
970
+
971
+
972
+
973
+ **CLI command:** `airctrl record access`
974
+
975
+
976
+
977
+ #### Update record details
978
+
979
+
980
+
981
+ Only supplied fields change. Use the documented `null` or `none` value to clear optional fields.
982
+
983
+
984
+
985
+ ```bash
986
+ airctrl record metadata "$RECORD_ID" --tags payments,production \
987
+ --secret-due 2026-12-01T00:00:00Z --rotation-days 90
988
+ ```
989
+
990
+
991
+
992
+ **CLI command:** `airctrl record metadata`
993
+
994
+
995
+
996
+ #### Archive a record
997
+
998
+
999
+
1000
+ Archives the record without deleting encrypted history.
1001
+
1002
+
1003
+
1004
+ ```bash
1005
+ airctrl record archive "$RECORD_ID"
1006
+ ```
1007
+
1008
+
1009
+
1010
+ **CLI command:** `airctrl record archive`
1011
+
1012
+
1013
+
1014
+ #### Restore a record
1015
+
1016
+
1017
+
1018
+ Restores an archived record to active lists.
1019
+
1020
+
1021
+
1022
+ ```bash
1023
+ airctrl record restore "$RECORD_ID"
1024
+ ```
1025
+
1026
+
1027
+
1028
+ **CLI command:** `airctrl record restore`
1029
+
1030
+
1031
+
1032
+ #### Transfer record ownership
1033
+
1034
+
1035
+
1036
+ The new owner must be eligible. Confirm both IDs before transferring ownership.
1037
+
1038
+
1039
+
1040
+ ```bash
1041
+ airctrl record transfer "$RECORD_ID" --owner "$NEW_OWNER_USER_ID"
1042
+ ```
1043
+
1044
+
1045
+
1046
+ **CLI command:** `airctrl record transfer`
1047
+
1048
+
1049
+
1050
+ #### Restore a previous record version
1051
+
1052
+
1053
+
1054
+ 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
+
1056
+
1057
+
1058
+ ```bash
1059
+ airctrl record rollback "$RECORD_ID" --version "$VERSION_ID"
1060
+ ```
1061
+
1062
+
1063
+
1064
+ **CLI command:** `airctrl record rollback`
1065
+
1066
+
1067
+
1068
+ #### Replace record fields by ID
1069
+
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
+
1075
+
1076
+ ```bash
1077
+ airctrl record set "$RECORD_ID" --field service_name=Database \
1078
+ --field username=app_user --field password="$NEW_PASSWORD" \
1079
+ --idempotency-key "$IDEMPOTENCY_KEY"
1080
+ ```
1081
+
1082
+
1083
+
1084
+ **CLI command:** `airctrl record set`
1085
+
1086
+
1087
+
1088
+ #### Rotate a record
1089
+
1090
+
1091
+
1092
+ Rotates the record data key locally and saves a new encrypted version.
1093
+
1094
+
1095
+
1096
+ ```bash
1097
+ airctrl record rotate "$RECORD_ID"
1098
+ ```
1099
+
1100
+
1101
+
1102
+ **CLI command:** `airctrl record rotate`
1103
+
1104
+
1105
+
1106
+ ### Groups
1107
+
1108
+ 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
+ #### List context groups
1111
+
1112
+ ```bash
1113
+ airctrl group list "$PROJECT_ID" --account "$AIRCTRL_ACCOUNT_ID"
1114
+ ```
1115
+
1116
+
1117
+
1118
+ **CLI command:** `airctrl group list`
1119
+
1120
+
1121
+
1122
+ #### Read a record's group grants
1123
+
1124
+ ```bash
1125
+ airctrl group record-grants "$RECORD_ID" --account "$AIRCTRL_ACCOUNT_ID"
1126
+ ```
1127
+
1128
+
1129
+
1130
+ **CLI command:** `airctrl group record-grants`
1131
+
1132
+
1133
+
1134
+ #### Create a group
1135
+
1136
+ Creation does not grant a project role.
1137
+
1138
+ ```bash
1139
+ airctrl group create "$PROJECT_ID" --account "$AIRCTRL_ACCOUNT_ID" --name "Payments team" --description "Payments operators"
1140
+ ```
1141
+
1142
+
1143
+
1144
+ **CLI command:** `airctrl group create`
1145
+
1146
+
1147
+
1148
+ #### Rename a group
1149
+
1150
+ Omitting description clears it.
1151
+
1152
+ ```bash
1153
+ airctrl group update "$GROUP_ID" --account "$AIRCTRL_ACCOUNT_ID" --name "Payments operators" --description "Payments access"
1154
+ ```
1155
+
1156
+
1157
+
1158
+ **CLI command:** `airctrl group update`
1159
+
1160
+
1161
+
1162
+ #### Delete a group
1163
+
1164
+ Deletes only this group's access paths. Review remaining sources and pending re-keying.
1165
+
1166
+ ```bash
1167
+ airctrl group delete "$GROUP_ID" --account "$AIRCTRL_ACCOUNT_ID"
1168
+ ```
1169
+
1170
+
1171
+
1172
+ **CLI command:** `airctrl group delete`
1173
+
1174
+
1175
+
1176
+ #### List group members
1177
+
1178
+ ```bash
1179
+ airctrl group members "$GROUP_ID" --account "$AIRCTRL_ACCOUNT_ID"
1180
+ ```
1181
+
1182
+
1183
+
1184
+ **CLI command:** `airctrl group members`
1185
+
1186
+
1187
+
1188
+ #### Add a group member
1189
+
1190
+ The person must be an onboarded account member. The result can report pending encrypted material.
1191
+
1192
+ ```bash
1193
+ airctrl group add-member "$GROUP_ID" "$USER_ID" --account "$AIRCTRL_ACCOUNT_ID"
1194
+ ```
1195
+
1196
+
1197
+
1198
+ **CLI command:** `airctrl group add-member`
1199
+
1200
+
1201
+
1202
+ #### Remove a group member
1203
+
1204
+ Preserves access through other groups, project membership or direct record shares.
1205
+
1206
+ ```bash
1207
+ airctrl group remove-member "$GROUP_ID" "$USER_ID" --account "$AIRCTRL_ACCOUNT_ID"
1208
+ ```
1209
+
1210
+
1211
+
1212
+ **CLI command:** `airctrl group remove-member`
1213
+
1214
+
1215
+
1216
+ #### Grant a project role to a group
1217
+
1218
+ Use a delegable role ID from the SDK catalog or API reference; do not guess IDs.
1219
+
1220
+ ```bash
1221
+ airctrl group grant-project "$PROJECT_ID" "$GROUP_ID" "$ROLE_ID" --account "$AIRCTRL_ACCOUNT_ID"
1222
+ ```
1223
+
1224
+
1225
+
1226
+ **CLI command:** `airctrl group grant-project`
1227
+
1228
+
1229
+
1230
+ #### Revoke one project role from a group
1231
+
1232
+ Removes only this project/group/role assignment.
1233
+
1234
+ ```bash
1235
+ airctrl group revoke-project "$PROJECT_ID" "$GROUP_ID" "$ROLE_ID" --account "$AIRCTRL_ACCOUNT_ID"
1236
+ ```
1237
+
1238
+
1239
+
1240
+ **CLI command:** `airctrl group revoke-project`
1241
+
1242
+
1243
+
1244
+ #### Complete pending encrypted access
1245
+
1246
+ 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
+ ```bash
1249
+ airctrl group reconcile --account "$AIRCTRL_ACCOUNT_ID" --project "$PROJECT_ID"
1250
+ ```
1251
+
1252
+
1253
+
1254
+ **CLI command:** `airctrl group reconcile`
1255
+
1256
+
1257
+
1258
+ ### Record sharing
1259
+
1260
+ #### Share a record with a user
1261
+
1262
+
1263
+
1264
+ The recipient must be onboarded and eligible for the project.
1265
+
1266
+
1267
+
1268
+ ```bash
1269
+ airctrl record share-user "$RECORD_ID" --user "$USER_ID" --permission read
1270
+ ```
1271
+
1272
+
1273
+
1274
+ **CLI command:** `airctrl record share-user`
1275
+
1276
+
1277
+
1278
+ #### Share a record with a Service Account
1279
+
1280
+
1281
+
1282
+ Encrypts a wrapper for the Service Account. This does not change its custom role.
1283
+
1284
+
1285
+
1286
+ ```bash
1287
+ airctrl record share-sa "$RECORD_ID" --account "$ACCOUNT_ID" \
1288
+ --service-account "$SERVICE_ACCOUNT_ID"
1289
+ ```
1290
+
1291
+
1292
+
1293
+ **CLI command:** `airctrl record share-sa`
1294
+
1295
+
1296
+
1297
+ #### Share a record with a group
1298
+
1299
+
1300
+
1301
+ The group must belong to the record's account. A direct record share does not grant project access.
1302
+
1303
+
1304
+
1305
+ ```bash
1306
+ airctrl record share-group "$RECORD_ID" --group "$GROUP_ID"
1307
+ ```
1308
+
1309
+
1310
+
1311
+ **CLI command:** `airctrl record share-group`
1312
+
1313
+
1314
+
1315
+ #### Remove a user's record access
1316
+
1317
+
1318
+
1319
+ Removes the user's direct grant. Other authorized paths remain; wrappers are removed only where effective access is lost.
1320
+
1321
+
1322
+
1323
+ ```bash
1324
+ airctrl record revoke-user "$RECORD_ID" --user "$USER_ID"
1325
+ ```
1326
+
1327
+
1328
+
1329
+ **CLI command:** `airctrl record revoke-user`
1330
+
1331
+
1332
+
1333
+ #### Remove a Service Account's record access
1334
+
1335
+
1336
+
1337
+ Removes only this record grant. Other Service Account grants remain unchanged.
1338
+
1339
+
1340
+
1341
+ ```bash
1342
+ airctrl record revoke-sa "$RECORD_ID" --service-account "$SERVICE_ACCOUNT_ID"
1343
+ ```
1344
+
1345
+
1346
+
1347
+ **CLI command:** `airctrl record revoke-sa`
1348
+
1349
+
1350
+
1351
+ #### Remove a group's record access
1352
+
1353
+
1354
+
1355
+ Removes the group grant. Other authorized paths remain; wrappers are removed only where effective access is lost.
1356
+
1357
+
1358
+
1359
+ ```bash
1360
+ airctrl record revoke-group "$RECORD_ID" --group "$GROUP_ID"
1361
+ ```
1362
+
1363
+
1364
+
1365
+ **CLI command:** `airctrl record revoke-group`
1366
+
1367
+
1368
+
1369
+ ### Gateway discovery and lifecycle
1370
+
1371
+ #### List supported AI providers
1372
+
1373
+
1374
+
1375
+ Returns enabled providers. This command is available to both human and Service Account identities.
1376
+
1377
+
1378
+
1379
+ ```bash
1380
+ airctrl gateway providers
1381
+ ```
1382
+
1383
+
1384
+
1385
+ **CLI command:** `airctrl gateway providers`
1386
+
1387
+
1388
+
1389
+ #### List gateways
1390
+
1391
+
1392
+
1393
+ Returns gateways in one project. This command requires a human PAT.
1394
+
1395
+
1396
+
1397
+ ```bash
1398
+ airctrl gateway list --project "$PROJECT_ID"
1399
+ ```
1400
+
1401
+
1402
+
1403
+ **CLI command:** `airctrl gateway list`
1404
+
1405
+
1406
+
1407
+ #### View a gateway
1408
+
1409
+
1410
+
1411
+ Returns one accessible gateway and safe settings. Service Accounts may use this read.
1412
+
1413
+
1414
+
1415
+ ```bash
1416
+ airctrl gateway get "$GATEWAY_ID"
1417
+ ```
1418
+
1419
+
1420
+
1421
+ **CLI command:** `airctrl gateway get`
1422
+
1423
+
1424
+
1425
+ #### Create a gateway
1426
+
1427
+
1428
+
1429
+ Returns the gateway ID. Each provider credential must belong to the same account, and `--model` must exist in that credential's live catalog.
1430
+
1431
+
1432
+
1433
+ ```bash
1434
+ airctrl gateway create --account "$ACCOUNT_ID" --project "$PROJECT_ID" \
1435
+ --name "Payments AI" --provider "$PROVIDER_ID" --model gpt-5 \
1436
+ --credential-binding "$PROVIDER_CREDENTIAL_ID=gpt-5"
1437
+ ```
1438
+
1439
+
1440
+
1441
+ **CLI command:** `airctrl gateway create`
1442
+
1443
+
1444
+
1445
+ #### Update a gateway
1446
+
1447
+
1448
+
1449
+ Only supplied fields change.
1450
+
1451
+
1452
+
1453
+ ```bash
1454
+ airctrl gateway update "$GATEWAY_ID" --account "$ACCOUNT_ID" \
1455
+ --name "Payments AI production" --model gpt-5 --active true
1456
+ ```
1457
+
1458
+
1459
+
1460
+ **CLI command:** `airctrl gateway update`
1461
+
1462
+
1463
+
1464
+ #### Delete a gateway
1465
+
1466
+
1467
+
1468
+ This disables the gateway and revokes its gateway tokens. Confirm the gateway ID first.
1469
+
1470
+
1471
+
1472
+ ```bash
1473
+ airctrl gateway delete "$GATEWAY_ID" --account "$ACCOUNT_ID"
1474
+ ```
1475
+
1476
+
1477
+
1478
+ **CLI command:** `airctrl gateway delete`
1479
+
1480
+
1481
+
1482
+ ### Provider credentials
1483
+
1484
+ #### List provider credentials
1485
+
1486
+
1487
+
1488
+ Returns safe credential metadata; provider secret values never appear.
1489
+
1490
+
1491
+
1492
+ ```bash
1493
+ airctrl gateway provider-credentials --account "$ACCOUNT_ID"
1494
+ ```
1495
+
1496
+
1497
+
1498
+ **CLI command:** `airctrl gateway provider-credentials`
1499
+
1500
+
1501
+
1502
+ #### Add a provider credential
1503
+
1504
+
1505
+
1506
+ The CLI reads the secret from the named environment variable and never places it in the command arguments.
1507
+
1508
+
1509
+
1510
+ ```bash
1511
+ airctrl gateway provider-credential-create --account "$ACCOUNT_ID" \
1512
+ --provider "$PROVIDER_ID" --label "Production OpenAI" \
1513
+ --api-key-env OPENAI_PRODUCTION_KEY --kind api_key
1514
+ ```
1515
+
1516
+
1517
+
1518
+ **CLI command:** `airctrl gateway provider-credential-create`
1519
+
1520
+
1521
+
1522
+ #### List models for a credential
1523
+
1524
+
1525
+
1526
+ 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
+
1528
+
1529
+
1530
+ ```bash
1531
+ airctrl gateway provider-models "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"
1532
+ ```
1533
+
1534
+
1535
+
1536
+ **CLI command:** `airctrl gateway provider-models`
1537
+
1538
+
1539
+
1540
+ #### Replace a provider key
1541
+
1542
+
1543
+
1544
+ The old provider key stops being used after the replacement validates.
1545
+
1546
+
1547
+
1548
+ ```bash
1549
+ airctrl gateway provider-credential-rotate "$PROVIDER_CREDENTIAL_ID" \
1550
+ --account "$ACCOUNT_ID" --api-key-env OPENAI_REPLACEMENT_KEY
1551
+ ```
1552
+
1553
+
1554
+
1555
+ **CLI command:** `airctrl gateway provider-credential-rotate`
1556
+
1557
+
1558
+
1559
+ #### Rename a provider credential
1560
+
1561
+
1562
+
1563
+ Changes only the display label.
1564
+
1565
+
1566
+
1567
+ ```bash
1568
+ airctrl gateway provider-credential-update "$PROVIDER_CREDENTIAL_ID" \
1569
+ --account "$ACCOUNT_ID" --label "Primary OpenAI"
1570
+ ```
1571
+
1572
+
1573
+
1574
+ **CLI command:** `airctrl gateway provider-credential-update`
1575
+
1576
+
1577
+
1578
+ #### Revoke a provider credential
1579
+
1580
+
1581
+
1582
+ Revocation prevents future provider use. Confirm dependent gateways first.
1583
+
1584
+
1585
+
1586
+ ```bash
1587
+ airctrl gateway provider-credential-revoke "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"
1588
+ ```
1589
+
1590
+
1591
+
1592
+ **CLI command:** `airctrl gateway provider-credential-revoke`
1593
+
1594
+
1595
+
1596
+ #### Attach a provider credential
1597
+
1598
+
1599
+
1600
+ Validates every repeated `--model` against one live catalog, then attaches all exact key/model bindings to the gateway.
1601
+
1602
+
1603
+
1604
+ ```bash
1605
+ airctrl gateway credential-attach "$GATEWAY_ID" "$PROVIDER_CREDENTIAL_ID" \
1606
+ --account "$ACCOUNT_ID" --model gpt-5 --model gpt-5-mini
1607
+ ```
1608
+
1609
+
1610
+
1611
+ **CLI command:** `airctrl gateway credential-attach`
1612
+
1613
+
1614
+
1615
+ #### Detach a provider credential
1616
+
1617
+
1618
+
1619
+ 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
+
1621
+
1622
+
1623
+ ```bash
1624
+ airctrl gateway credential-detach "$GATEWAY_ID" "$PROVIDER_CREDENTIAL_ID" \
1625
+ --account "$ACCOUNT_ID" --model gpt-5
1626
+
1627
+ airctrl gateway credential-detach "$GATEWAY_ID" "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"
1628
+ ```
1629
+
1630
+
1631
+
1632
+ **CLI command:** `airctrl gateway credential-detach`
1633
+
1634
+
1635
+
1636
+ ### Gateway tokens
1637
+
1638
+ #### List gateway tokens
1639
+
1640
+
1641
+
1642
+ Returns safe token metadata. Token plaintext is never listed again.
1643
+
1644
+
1645
+
1646
+ ```bash
1647
+ airctrl gateway tokens "$GATEWAY_ID"
1648
+ ```
1649
+
1650
+
1651
+
1652
+ **CLI command:** `airctrl gateway tokens`
1653
+
1654
+
1655
+
1656
+ #### Create a gateway token
1657
+
1658
+
1659
+
1660
+ The token value appears once. Save it immediately in an approved destination.
1661
+
1662
+
1663
+
1664
+ ```bash
1665
+ airctrl gateway token-create "$GATEWAY_ID" --account "$ACCOUNT_ID" \
1666
+ --name "Local development" --expires-days 30 --scopes run,read_logs \
1667
+ --allowed-models gpt-5,gpt-5-mini --rate-limit 60
1668
+ ```
1669
+
1670
+
1671
+
1672
+ **CLI command:** `airctrl gateway token-create`
1673
+
1674
+
1675
+
1676
+ #### Rename a gateway token
1677
+
1678
+
1679
+
1680
+ Changes the label, not the token value.
1681
+
1682
+
1683
+
1684
+ ```bash
1685
+ airctrl gateway token-rename "$GATEWAY_ID" "$TOKEN_ID" \
1686
+ --account "$ACCOUNT_ID" --name "CI production"
1687
+ ```
1688
+
1689
+
1690
+
1691
+ **CLI command:** `airctrl gateway token-rename`
1692
+
1693
+
1694
+
1695
+ #### Revoke a gateway token
1696
+
1697
+
1698
+
1699
+ Authentication stops immediately. The token row remains available for audit.
1700
+
1701
+
1702
+
1703
+ ```bash
1704
+ airctrl gateway token-revoke "$GATEWAY_ID" "$TOKEN_ID" --account "$ACCOUNT_ID"
1705
+ ```
1706
+
1707
+
1708
+
1709
+ **CLI command:** `airctrl gateway token-revoke`
1710
+
1711
+
1712
+
1713
+ #### Delete a gateway token
1714
+
1715
+
1716
+
1717
+ Deletes token metadata. Revoke first when you need a clear audit transition.
1718
+
1719
+
1720
+
1721
+ ```bash
1722
+ airctrl gateway token-delete "$GATEWAY_ID" "$TOKEN_ID" --account "$ACCOUNT_ID"
1723
+ ```
1724
+
1725
+
1726
+
1727
+ **CLI command:** `airctrl gateway token-delete`
1728
+
1729
+
1730
+
1731
+ ### Routing, limits and telemetry
1732
+
1733
+ #### Change gateway limits and behavior
1734
+
1735
+
1736
+
1737
+ Only supplied settings change. Body logging can store sensitive request content, so keep it disabled unless required.
1738
+
1739
+
1740
+
1741
+ ```bash
1742
+ airctrl gateway settings "$GATEWAY_ID" --account "$ACCOUNT_ID" \
1743
+ --spend-limit 100 --spend-window monthly --rate-limit 120 \
1744
+ --logging true --log-bodies false --guardrail flag
1745
+ ```
1746
+
1747
+
1748
+
1749
+ **CLI command:** `airctrl gateway settings`
1750
+
1751
+
1752
+
1753
+ #### Review gateway requests
1754
+
1755
+
1756
+
1757
+ Returns request metadata. Service Accounts may use this read when their role permits it.
1758
+
1759
+
1760
+
1761
+ ```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"
1768
+ ```
1769
+
1770
+
1771
+
1772
+ **CLI command:** `airctrl gateway logs`
1773
+
1774
+
1775
+
1776
+ #### Inspect one gateway request
1777
+
1778
+
1779
+
1780
+ Returns stored bodies only when body logging and the required permission are both present.
1781
+
1782
+
1783
+
1784
+ ```bash
1785
+ airctrl gateway log "$GATEWAY_ID" "$LOG_ID"
1786
+ ```
1787
+
1788
+
1789
+
1790
+ **CLI command:** `airctrl gateway log`
1791
+
1792
+
1793
+
1794
+ #### Review provider-key access
1795
+
1796
+
1797
+
1798
+ Returns provider-key access decisions without returning provider keys.
1799
+
1800
+
1801
+
1802
+ ```bash
1803
+ airctrl gateway key-access "$GATEWAY_ID" --outcome denied \
1804
+ --since 2026-09-01T00:00:00Z --limit 50 --offset 0
1805
+ ```
1806
+
1807
+
1808
+
1809
+ **CLI command:** `airctrl gateway key-access`
1810
+
1811
+
1812
+
1813
+ #### Review project usage logs
1814
+
1815
+
1816
+
1817
+ Returns usage metadata across the selected project.
1818
+
1819
+
1820
+
1821
+ ```bash
1822
+ airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
1823
+ --since 2026-09-01T00:00:00Z --limit 50
1824
+
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"
1828
+ ```
1829
+
1830
+
1831
+
1832
+ **CLI command:** `airctrl gateway usage-logs`
1833
+
1834
+
1835
+
1836
+ #### Inspect one project usage log
1837
+
1838
+
1839
+
1840
+ Returns one project log and any stored bodies allowed by RBAC.
1841
+
1842
+
1843
+
1844
+ ```bash
1845
+ airctrl gateway usage-log "$LOG_ID" --project "$PROJECT_ID"
1846
+ ```
1847
+
1848
+
1849
+
1850
+ **CLI command:** `airctrl gateway usage-log`
1851
+
1852
+
1853
+
1854
+ #### Review project spend
1855
+
1856
+
1857
+
1858
+ Returns current spend and the effective project or account limit.
1859
+
1860
+
1861
+
1862
+ ```bash
1863
+ airctrl gateway usage-spend --project "$PROJECT_ID"
1864
+ ```
1865
+
1866
+
1867
+
1868
+ **CLI command:** `airctrl gateway usage-spend`
1869
+
1870
+
1871
+
1872
+ #### Review project usage metrics
1873
+
1874
+
1875
+
1876
+ Returns request, error, token, latency and spend aggregates.
1877
+
1878
+
1879
+
1880
+ ```bash
1881
+ airctrl gateway usage-metrics --project "$PROJECT_ID" \
1882
+ --since 2026-09-01T00:00:00Z --bucket day
1883
+ ```
1884
+
1885
+
1886
+
1887
+ **CLI command:** `airctrl gateway usage-metrics`
1888
+
1889
+
1890
+
1891
+ #### View OpenTelemetry settings
1892
+
1893
+
1894
+
1895
+ Returns safe OpenTelemetry settings. Secret header values are never returned.
1896
+
1897
+
1898
+
1899
+ ```bash
1900
+ airctrl gateway otel "$GATEWAY_ID" --account "$ACCOUNT_ID"
1901
+ ```
1902
+
1903
+
1904
+
1905
+ **CLI command:** `airctrl gateway otel`
1906
+
1907
+
1908
+
1909
+ #### Change OpenTelemetry settings
1910
+
1911
+
1912
+
1913
+ The CLI reads header values from the named environment variable. Use `--clear-headers true` to remove stored headers.
1914
+
1915
+
1916
+
1917
+ ```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
1922
+ ```
1923
+
1924
+
1925
+
1926
+ **CLI command:** `airctrl gateway otel-update`
1927
+
1928
+
1929
+
1930
+ ### Service Account metadata
1931
+
1932
+ #### List Service Accounts
1933
+
1934
+
1935
+
1936
+ Returns safe Service Account metadata to a human PAT.
1937
+
1938
+
1939
+
1940
+ ```bash
1941
+ airctrl sa list --account "$ACCOUNT_ID"
1942
+ ```
1943
+
1944
+
1945
+
1946
+ **CLI command:** `airctrl sa list`
1947
+
1948
+
1949
+
1950
+ #### View a Service Account
1951
+
1952
+
1953
+
1954
+ Returns one Service Account from the safe metadata list. Lifecycle and credential actions remain dashboard-only.
1955
+
1956
+
1957
+
1958
+ ```bash
1959
+ airctrl sa get "$SERVICE_ACCOUNT_ID" --account "$ACCOUNT_ID"
1960
+ ```
1961
+
1962
+
1963
+
1964
+ **CLI command:** `airctrl sa get`
1965
+
1966
+
1967
+
1968
+ ### Common exit behavior
1969
+
1970
+ 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
+ ## Use the CLI with Bash
1972
+
1973
+ Use this guide in Bash on macOS or Linux. It keeps record values in the child process memory instead of writing a `.env` file into your repository.
1974
+
1975
+ ### Install and sign in
1976
+
1977
+ Install the CLI once, then use `airctrl login` to save your human setup in your user profile.
1978
+
1979
+ ```bash
1980
+ npm install --global @airctrl/cli
1981
+ airctrl login
1982
+ ```
1983
+
1984
+ The login command asks for the AIRCTRL API URL, your personal access token, and an optional default project. It stores only the human configuration in `~/.airctrl/config.json`.
1985
+
1986
+ Run a read-only command first to confirm the selected account:
1987
+
1988
+ ```bash
1989
+ airctrl project list --account "$AIRCTRL_ACCOUNT_ID"
1990
+ ```
1991
+
1992
+ ### Run an application with record values
1993
+
1994
+ Pass a project ID and the command after `--`. The CLI reads only the records you can access, decrypts them locally, and starts the child process with those values in its environment.
1995
+
1996
+ ```bash
1997
+ airctrl run --project "$AIRCTRL_PROJECT_ID" -- node server.js
1998
+ ```
1999
+
2000
+ The values exist only in the child process. AIRCTRL control values are removed before the process starts. The CLI does not create or modify a `.env` file.
2001
+
2002
+ ### Use a Service Account
2003
+
2004
+ For unattended work, load the active Service Account credential bundle through your CI or local secret mechanism. Keep all bundle fields together; partial or mixed credentials fail before AIRCTRL makes a request. The [CLI overview](https://docs.airctrl.dev/cli/overview) lists the configuration names used by the CLI.
2005
+
2006
+ ```bash
2007
+ airctrl record list --project "$AIRCTRL_PROJECT_ID"
2008
+ ```
2009
+
2010
+ A Service Account can use only its assigned permissions and projects. It cannot become a human identity by adding a human configuration file.
2011
+
2012
+ ### Diagnose a failure
2013
+
2014
+ Check the exit code instead of parsing terminal prose. A non-zero result means the command did not complete.
2015
+
2016
+ ```bash
2017
+ if ! airctrl project list --account "$AIRCTRL_ACCOUNT_ID"; then
2018
+ echo "AIRCTRL request failed" >&2
2019
+ exit 1
2020
+ fi
2021
+ ```
2022
+
2023
+ For an access denial, verify the selected account, project, and identity. Do not retry a permission failure with a broader ID. See [Errors and retries](https://docs.airctrl.dev/reference/errors) and the full [CLI command reference](https://docs.airctrl.dev/cli/commands).
2024
+ ## Use the CLI with PowerShell
2025
+
2026
+ Use this guide in PowerShell on Windows. It keeps record values in the child process memory instead of writing a `.env` file into your repository.
2027
+
2028
+ ### Install and sign in
2029
+
2030
+ Install the CLI once, then use `airctrl login` to save your human setup in your Windows user profile.
2031
+
2032
+ ```powershell
2033
+ npm install --global @airctrl/cli
2034
+ airctrl login
2035
+ ```
2036
+
2037
+ The login command asks for the AIRCTRL API URL, your personal access token, and an optional default project. It stores only the human configuration under your home directory in `.airctrl\config.json`.
2038
+
2039
+ Run a read-only command first to confirm the selected account:
2040
+
2041
+ ```powershell
2042
+ airctrl project list --account $env:AIRCTRL_ACCOUNT_ID
2043
+ ```
2044
+
2045
+ ### Run an application with record values
2046
+
2047
+ Pass a project ID and the command after `--`. The CLI reads only the records you can access, decrypts them locally, and starts the child process with those values in its environment.
2048
+
2049
+ ```powershell
2050
+ airctrl run --project $env:AIRCTRL_PROJECT_ID -- node server.js
2051
+ ```
2052
+
2053
+ The values exist only in the child process. AIRCTRL control values are removed before the process starts. The CLI does not create or modify a `.env` file.
2054
+
2055
+ ### Use a Service Account
2056
+
2057
+ For unattended work, load the active Service Account credential bundle through your CI or local secret mechanism. Keep all bundle fields together; partial or mixed credentials fail before AIRCTRL makes a request. The [CLI overview](https://docs.airctrl.dev/cli/overview) lists the configuration names used by the CLI.
2058
+
2059
+ ```powershell
2060
+ airctrl record list --project $env:AIRCTRL_PROJECT_ID
2061
+ ```
2062
+
2063
+ A Service Account can use only its assigned permissions and projects. It cannot become a human identity by adding a human configuration file.
2064
+
2065
+ ### Diagnose a failure
2066
+
2067
+ Check `$LASTEXITCODE` instead of parsing terminal prose. A non-zero result means the command did not complete.
2068
+
2069
+ ```powershell
2070
+ airctrl project list --account $env:AIRCTRL_ACCOUNT_ID
2071
+ if ($LASTEXITCODE -ne 0) {
2072
+ Write-Error 'AIRCTRL request failed'
2073
+ exit $LASTEXITCODE
2074
+ }
2075
+ ```
2076
+
2077
+ For an access denial, verify the selected account, project, and identity. Do not retry a permission failure with a broader ID. See [Errors and retries](https://docs.airctrl.dev/reference/errors) and the full [CLI command reference](https://docs.airctrl.dev/cli/commands).
2078
+
2079
+ ## License
2080
+
2081
+ Proprietary software. All rights reserved.