@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 +2080 -2
- package/dist/cli-error.js +29 -0
- package/dist/cli.js +502 -0
- package/dist/config.js +102 -0
- package/dist/deadline.js +13 -0
- package/dist/gateway-commands.js +487 -0
- package/dist/group-commands.js +92 -0
- package/dist/identity-rotation.js +550 -0
- package/dist/index.js +21 -0
- package/dist/migrate.js +232 -0
- package/dist/parser.js +120 -0
- package/dist/pat-expired.js +31 -0
- package/dist/project-commands.js +121 -0
- package/dist/prompt.js +45 -0
- package/dist/record-commands.js +330 -0
- package/dist/resolve-client.js +160 -0
- package/dist/resolve-status-principal.js +69 -0
- package/dist/sa-commands.js +1485 -0
- package/dist/service-account-read-commands.js +38 -0
- package/dist/store/atomic-write.js +344 -0
- package/dist/store/base-url.js +71 -0
- package/dist/store/canonical.js +45 -0
- package/dist/store/durable-delete.js +86 -0
- package/dist/store/errors.js +25 -0
- package/dist/store/fsops.js +94 -0
- package/dist/store/handoff-store.js +183 -0
- package/dist/store/identity-rotation-journal.js +396 -0
- package/dist/store/index.js +20 -0
- package/dist/store/lock.js +294 -0
- package/dist/store/names.js +52 -0
- package/dist/store/paths.js +219 -0
- package/dist/store/profile-store.js +262 -0
- package/dist/store/receipt-store.js +75 -0
- package/dist/store/resolve-principal.js +125 -0
- package/dist/store/rotation-store.js +66 -0
- package/dist/store/schema.js +554 -0
- package/package.json +42 -4
package/README.md
CHANGED
|
@@ -1,3 +1,2081 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @airctrl/cli
|
|
2
2
|
|
|
3
|
-
|
|
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.
|