CLI commands - AIRCTRL

Use --profile <name> on supported commands when you have a stored Service Account profile. 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>
airctrl read <recordId> [--scope a,b] [--env <name>]
airctrl run --project <id> -- <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> [--profile <name>]
airctrl read <recordId> [--scope a,b] [--env <name>] [--profile <name>]
airctrl run --project <id> [--profile <name>] -- <command> [args]
airctrl generate <format> [--option value]
airctrl create <format> --name <name> [--project <id>] [--field key=value]
airctrl set <format> --name <name> [--project <id>] [--field key=value]
airctrl new <format> --name <name> [--project <id>] [--option value]
airctrl import env <file> --name <name> [--project <id>] [--target-env <name>]

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>

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 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>]
  [--limit <n>] [--offset <n>]
airctrl record access [--account <id>] [--scope-type user|project] [--scope-id <id>]
  [--actions a,b] [--limit <n>] [--offset <n>]
airctrl record metadata <recordId> [--name <name>] [--tags a,b|none]
  [--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> ...]
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>] [--provider <id|null>] [--model <name|null>] [--credential <id>]
airctrl gateway update <gatewayId> --account <id>
  [--name <name>] [--provider <id|null>] [--model <name|null>] [--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] [--cache true|false]
  [--cache-ttl <seconds>] [--allowed-models a,b|none]
airctrl gateway credential-attach <gatewayId> <credentialId> --account <id> --model <name>
airctrl gateway credential-detach <gatewayId> <credentialId> --account <id>
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>

Observability:

airctrl gateway logs <gatewayId> [--since <iso>] [--provider <id>] [--model <name>]
  [--status <code>] [--limit <n>] [--offset <n>]
airctrl gateway log <gatewayId> <logId>
airctrl gateway key-access <gatewayId> [--outcome granted|denied|error]
  [--since <iso>] [--limit <n>] [--offset <n>]
airctrl gateway usage-logs --project <id> [--since <iso>] [--provider <id>]
  [--model <name>] [--status <code>] [--gateway <id>] [--limit <n>] [--offset <n>]
airctrl gateway usage-log <logId> --project <id>
airctrl gateway usage-spend --project <id>
airctrl gateway usage-metrics --project <id> [--since <iso>] [--bucket hour|day]
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] [--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.
Repeat --field key=value and --credential <id> when you need more than one value.
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

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

​Record management commands

​Gateway commands

​Service Account metadata commands

​Argument rules

​Output

​Complete workflow examples

​CLI failures