CLI commands - AIRCTRL

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. For one copy-ready command example per command, continue to CLI examples.

Identity availability

A human PAT can use every API-backed command below when RBAC permits it. Local commands such as login and generate do not require API authorization. A Service Account can use only:

airctrl get <recordId> [--env development|staging|production]
airctrl read <recordId> [--scope a,b] [--env development|staging|production]
airctrl run --project <id> [--env development|staging|production] -- <command> [args]
airctrl generate <format> [--option value]            # local only
airctrl record list [--project <id>] [--tab shared]
airctrl gateway providers
airctrl gateway get <gatewayId>
airctrl gateway tokens <gatewayId>
airctrl gateway logs <gatewayId>
airctrl gateway log <gatewayId> <logId>
airctrl gateway key-access <gatewayId>

The CLI rejects every other command before making an SDK or API call. RBAC can still deny a command from this list when the Service Account lacks the required custom-role permission or project access.

Core record commands

airctrl login
airctrl get <recordId> [--env development|staging|production] [--profile <name>]
airctrl read <recordId> [--scope a,b] [--env development|staging|production] [--profile <name>]
airctrl run --project <id> [--env development|staging|production] [--profile <name>] -- <command> [args]
airctrl generate <format> [--option value]
airctrl create <format> --name <name> [--project <id>] [--field key=value]
  [--env development|staging|production] [--tags a,b|none] [--secret-due <iso|null>]
  [--rotation-days <n|null>] [--idempotency-key <key>]
airctrl set <format> --name <name> [--project <id>] [--field key=value]
  [--env development|staging|production] [--tags a,b|none] [--secret-due <iso|null>]
  [--rotation-days <n|null>] [--idempotency-key <key>]
airctrl new <format> --name <name> [--project <id>] [--option value]
  [--env development|staging|production] [--tags a,b|none] [--secret-due <iso|null>]
  [--rotation-days <n|null>] [--idempotency-key <key>]
airctrl import env <file> --name <name> [--project <id>] [--target-env <name>]
  [--env development|staging|production] [--tags a,b|none] [--secret-due <iso|null>]
  [--rotation-days <n|null>] [--idempotency-key <key>]

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.

Project commands

airctrl project accounts
airctrl project list --account <id> [--include-archived true|false]
airctrl project get <projectId> --account <id>
airctrl project create --account <id> --name <name> [--description <text>]
airctrl project update <projectId> --account <id> --name <name> --description <text|null> --active true|false
airctrl project archive <projectId> --account <id>
airctrl project restore <projectId> --account <id>

Group commands

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.

airctrl group list <projectId> --account <id>
airctrl group record-grants <recordId> --account <id>
airctrl group create <projectId> --account <id> --name <name> [--description <text>]
airctrl group update <groupId> --account <id> --name <name> [--description <text>]
airctrl group delete <groupId> --account <id>
airctrl group members <groupId> --account <id>
airctrl group add-member <groupId> <userId> --account <id>
airctrl group remove-member <groupId> <userId> --account <id>
airctrl group grant-project <projectId> <groupId> <roleId> --account <id>
airctrl group revoke-project <projectId> <groupId> <roleId> --account <id>
airctrl group reconcile --account <id> [--project <id>]

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. 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. 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.

Record management commands

airctrl record list [--account <id>] [--project <id>] [--tab owned|shared]
  [--include-archived true|false] [--limit <n>] [--offset <n>]
airctrl record versions <recordId>
airctrl record audit <recordId> [--limit <n>]
airctrl record audit-events <recordId> [--cursor <opaque>] [--action <name>] [--actor <text>]
  [--from <iso>] [--to <iso>] [--limit <n>] [--offset <legacy-n>]
airctrl record anomalies [--account <id>] [--scope-type user|project] [--scope-id <id>]
airctrl record activity <YYYY-MM-DD> [--account <id>] [--scope-type user|project] [--scope-id <id>]
airctrl record alerts [--account <id>] [--scope-type user|project] [--scope-id <id>]
  [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
airctrl record access [--account <id>] [--scope-type user|project] [--scope-id <id>]
  [--actions a,b] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
airctrl record metadata <recordId> [--name <name>] [--tags a,b|none]
  [--env development|staging|production] [--secret-due <iso|null>] [--rotation-days <n|null>]
airctrl record archive <recordId>
airctrl record restore <recordId>
airctrl record transfer <recordId> --owner <userId>
airctrl record rollback <recordId> --version <versionId>
airctrl record set <recordId> --field <key=value> [--field <key=value> ...]
  [--env development|staging|production] [--idempotency-key <key>]
airctrl record rotate <recordId>
airctrl record share-user <recordId> --user <id> [--permission view|read]
airctrl record share-sa <recordId> --account <id> --service-account <id>
airctrl record share-group <recordId> --group <id>
airctrl record revoke-user <recordId> --user <id>
airctrl record revoke-sa <recordId> --service-account <id>
airctrl record revoke-group <recordId> --group <id>

Project audit scope requires both --scope-type project and --scope-id.

Gateway commands

Discovery and lifecycle:

airctrl gateway providers
airctrl gateway list --project <id>
airctrl gateway get <gatewayId>
airctrl gateway create --account <id> --project <id> --name <name>
  [--slug <slug>] [--credential-binding <credentialId=modelId>]
airctrl gateway update <gatewayId> --account <id>
  [--name <name>] [--active true|false]
airctrl gateway delete <gatewayId> --account <id>

Gateway tokens:

airctrl gateway tokens <gatewayId>
airctrl gateway token-create <gatewayId> --account <id> --name <name>
  [--expires-days <n>] [--scopes run,read_logs,manage]
  [--principal-type user|service_account --principal-id <id>]
  [--allowed-models a,b] [--spend-limit <amount>]
  [--spend-window daily|weekly|monthly] [--rate-limit <n>]
airctrl gateway token-rename <gatewayId> <tokenId> --account <id> --name <name>
airctrl gateway token-revoke <gatewayId> <tokenId> --account <id>
airctrl gateway token-delete <gatewayId> <tokenId> --account <id>

Settings and credentials:

airctrl gateway settings <gatewayId> --account <id>
  [--spend-limit <amount|null>] [--spend-window daily|weekly|monthly]
  [--rate-limit <n|null>] [--logging true|false] [--log-bodies true|false]
  [--guardrail off|flag|redact|block] [--allowed-models a,b|none]
airctrl gateway credential-attach <gatewayId> <credentialId> --account <id>
  --model <name> [--model <name> ...]
airctrl gateway credential-detach <gatewayId> <credentialId> --account <id> [--model <name>]
airctrl gateway provider-credentials --account <id>
airctrl gateway provider-credential-create --account <id> --provider <id>
  --label <name> --api-key-env <variable> [--base-url <url|null>]
  [--kind api_key|oauth|aws_sigv4|gcp_sa]
airctrl gateway provider-models <credentialId> --account <id>
airctrl gateway provider-credential-rotate <credentialId> --account <id> --api-key-env <variable>
airctrl gateway provider-credential-update <credentialId> --account <id> --label <name>
airctrl gateway provider-credential-revoke <credentialId> --account <id>

gateway provider-models includes current official pricing for each discovered model. Numeric token rates use USD per one million tokens; displayText and rateCard preserve provider-published zero and context-tiered policies. Observability:

airctrl gateway logs <gatewayId> [--since <iso>] [--until <iso>] [--provider <id>] [--model <name>]
  [--status <code>] [--status-class 2xx|4xx|5xx|other] [--search <keywords>]
  [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
airctrl gateway log <gatewayId> <logId>
airctrl gateway key-access <gatewayId> [--outcome granted|denied|error]
  [--since <iso>] [--until <iso>] [--cursor <opaque>] [--limit <n>] [--offset <legacy-n>]
airctrl gateway usage-logs --project <id> [--since <iso>] [--until <iso>] [--provider <id>]
  [--model <name>] [--status <code>] [--gateway <id>] [--cursor <opaque>]
  [--limit <n>] [--offset <legacy-n>]
airctrl gateway usage-log <logId> --project <id>
airctrl gateway usage-spend --project <id> [--gateway <id>]
airctrl gateway usage-metrics --project <id> [--since <iso>] [--until <iso>] [--bucket hour|day]
  [--gateway <id>] [--provider <slug>] [--model <name>]
  [--status-class 2xx|4xx|5xx|other] [--search <keywords>]
airctrl gateway otel <gatewayId> --account <id>
airctrl gateway otel-update <gatewayId> --account <id>
  [--enabled true|false] [--endpoint <url|null>] [--metrics true|false]
  [--traces true|false] [--bodies true|false]
  [--headers-env <variable>] [--clear-headers true|false]

Provider credentials and OpenTelemetry headers are read from named environment variables. Their values do not belong in command arguments.

Service Account metadata commands

airctrl sa list --account <id>
airctrl sa get <serviceAccountId> --account <id>

The public CLI does not create, pause, reactivate, delete, provision, rotate or revoke Service Account credentials.

Argument rules

Values in angle brackets are required. Values in square brackets are optional.
UUID arguments must be complete IDs. Names are not accepted where an ID is required.
--account selects account context. It does not add permissions.
--project limits an operation to one project.
--profile selects a stored Service Account profile for commands that support machine identity.
--scope on airctrl read selects record sections: fields, meta, owner, access, or full. It does not select individual field names.
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.
--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.
Repeat --field key=value, --model <name>, or --credential-binding <credentialId=modelId> when you need more than one value.
--tags none, --secret-due null, and --rotation-days null clear those optional values. A positive integer is required for --rotation-days.
--idempotency-key identifies one intended record write. Reuse it only when retrying the same input.
Use null only where the command syntax explicitly accepts it. It clears the stored optional value.
Use none only where documented. It replaces a list with an empty list.
Boolean flags accept only true or false.

Run a command family without a subcommand to see the installed version’s exact syntax:

airctrl project
airctrl record
airctrl gateway
airctrl sa

Output

Normal commands write formatted JSON to stdout. Scripts should read stdout as JSON and use the process exit status to decide whether the operation completed. Diagnostic text and stable error codes go to stderr. Commands that return no resource print { "ok": true }.

if result="$(airctrl project get "$PROJECT_ID" --account "$AIRCTRL_ACCOUNT_ID")"; then
  printf '%s\n' "$result"
else
  status=$?
  printf 'AIRCTRL failed with exit status %s\n' "$status" >&2
  exit "$status"
fi

One-time values, including newly created gateway tokens, are printed once. Redirect them only into an approved custody process. Do not write them to a shared terminal log.

Complete workflow examples

Create and inspect a project:

airctrl project create \
  --account "$AIRCTRL_ACCOUNT_ID" \
  --name "Payments" \
  --description "Credentials for the payments service"

airctrl project list --account "$AIRCTRL_ACCOUNT_ID"

Create a record without putting its secret value in command history:

airctrl import env ./payments.env \
  --project "$PROJECT_ID" \
  --name "Payments environment" \
  --target-env production

Read metadata, then inject decrypted values only into a child process:

airctrl record list --project "$PROJECT_ID" --limit 50
airctrl run --project "$PROJECT_ID" -- npm run dev

Change safe metadata and review immutable history:

airctrl record metadata "$RECORD_ID" --tags payments,production --rotation-days 90
airctrl record versions "$RECORD_ID"
airctrl record audit "$RECORD_ID" --limit 25

Share a record, then revoke the same grant:

airctrl record share-user "$RECORD_ID" --user "$USER_ID" --permission read
airctrl record revoke-user "$RECORD_ID" --user "$USER_ID"

Create a provider credential from an environment variable, then create a gateway:

export OPENAI_PRODUCTION_KEY="<loaded-by-your-runtime>"

airctrl gateway provider-credential-create \
  --account "$AIRCTRL_ACCOUNT_ID" \
  --provider "$PROVIDER_ID" \
  --label "Production OpenAI" \
  --api-key-env OPENAI_PRODUCTION_KEY

airctrl gateway create \
  --account "$AIRCTRL_ACCOUNT_ID" \
  --project "$PROJECT_ID" \
  --name "Payments AI" \
  --provider "$PROVIDER_ID" \
  --credential "$PROVIDER_CREDENTIAL_ID"

Create a short-lived gateway token and inspect usage without reading stored bodies:

airctrl gateway token-create "$GATEWAY_ID" \
  --account "$AIRCTRL_ACCOUNT_ID" \
  --name "Local development" \
  --expires-days 30 \
  --scopes run,read_logs \
  --rate-limit 60

airctrl gateway logs "$GATEWAY_ID" --limit 25
airctrl gateway usage-metrics --project "$PROJECT_ID" --bucket day
airctrl gateway usage-spend --project "$PROJECT_ID"

Read safe Service Account metadata as a human:

airctrl sa list --account "$AIRCTRL_ACCOUNT_ID"
airctrl sa get "$SERVICE_ACCOUNT_ID" --account "$AIRCTRL_ACCOUNT_ID"

Run the supported read-only subset with an active Service Account profile:

airctrl record list --project "$PROJECT_ID" --profile ci
airctrl get "$RECORD_ID" --profile ci
airctrl gateway logs "$GATEWAY_ID" --profile ci

OAuth partner Apps

The CLI has no OAuth App profile, authorization-code flow, or connection/protection lifecycle commands. Do not place OAuth client secrets, authorization codes, access tokens, or refresh tokens in its PAT/Service Account profiles or shell history. Those values belong in a confidential partner backend. Implement OAuth partner flows through the standards-based direct HTTP contract or OAuthPartnerClient. See OAuth partner integrations, OAuth protocol, and OAuth protection API. The CLI may still manage ordinary gateways with a separately authorized human PAT; that is not the OAuth installation identity.

CLI failures

Code or condition	Meaning	What to do
`cli_unknown_command`	The command or subcommand is not supported.	Run the command family without a subcommand.
`cli_flag_missing_value`	A required positional value or flag is missing.	Compare the call with the syntax above.
`cli_flag_invalid_value`	A number, boolean, enum, date or list has an invalid value.	Correct the local input; no API call was made.
`service_account_not_supported`	The selected profile tried a human-only operation.	Use a human PAT or choose an operation listed in Identity availability.
`not_authorized` or `insufficient_permission`	The identity lacks RBAC or resource access.	Request the required role or project grant. Do not retry unchanged.
`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.
`rate_limited`	The request limit was exceeded.	Wait and retry with bounded backoff.

The CLI never treats an incomplete Service Account profile as a human login. Fix the profile instead of adding a human PAT to the same machine configuration.

​Identity availability

​Core record commands

​Project commands

​Group commands

​Record management commands

​Gateway commands

​Service Account metadata commands

​Argument rules

​Output

​Complete workflow examples

​OAuth partner Apps

​CLI failures