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