CLI example catalog

This page shows every public CLI command. Replace the environment variables with IDs from your account. Commands that read secret values should run only in a trusted terminal.

Prepare the examples

The examples assume these non-secret IDs are already available:

export AIRCTRL_ACCOUNT_ID="00000000-0000-4000-8000-000000000001"
export PROJECT_ID="00000000-0000-4000-8000-000000000010"
export RECORD_ID="00000000-0000-4000-8000-000000000020"
export GATEWAY_ID="00000000-0000-4000-8000-000000000030"

Use airctrl project accounts, airctrl project list, airctrl record list and airctrl gateway list to discover them. Never guess an ID or try nearby IDs after an authorization failure. Every flag takes a separate value. Booleans use true or false; lists use comma-separated values; repeatable inputs repeat the flag. Run airctrl project, airctrl record, airctrl gateway or airctrl sa to see the exact syntax installed on the machine.

Local setup and record access

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.

airctrl login

CLI command: airctrl login

Read a complete record

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.

airctrl get "$RECORD_ID"

CLI command: airctrl get

Read selected record fields

Read only selected fields or one environment from a record. The result contains only the requested fields. never expands access beyond the record grant.

airctrl read "$RECORD_ID" --scope username,password --env production

CLI command: airctrl read

Inject records into a process

Inject accessible project records into one child process. The values exist only in the child process environment. The command returns the child process exit status.

airctrl run --project "$PROJECT_ID" -- npm run dev

CLI command: airctrl run

Generate a secret locally

Generate secret material locally without storing it. The generated fields are printed once. This command does not call the API.

airctrl generate password --length 32

CLI command: airctrl generate

Create an encrypted record

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.

airctrl create password --project "$PROJECT_ID" --name "Database login" \
  --field username=app_user --field password="$DATABASE_PASSWORD"

CLI command: airctrl create

Create or replace record fields

Update a matching record or create it when it does not exist. The result states whether created or updated the record.

airctrl set env --project "$PROJECT_ID" --name "Payments environment" \
  --field API_URL=https://payments.example.com --field API_TOKEN="$PAYMENTS_TOKEN"

CLI command: airctrl set

Create a generated record

Generate, encrypt and store a new record. The command returns the record ID. The generated value is encrypted before it leaves the CLI.

airctrl new password --project "$PROJECT_ID" --name "Generated database password" --length 32

CLI command: airctrl new

Import environment variables

Import an ENV file as one encrypted record. The source file stays unchanged. Review it before import so unrelated local variables are not stored.

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

CLI command: airctrl import

Account and project commands

List accessible accounts

Returns accounts available to the human PAT. Service Accounts cannot discover accounts.

airctrl project accounts

CLI command: airctrl project accounts

List projects

Returns accessible projects in the selected account.

airctrl project list --account "$ACCOUNT_ID" --include-archived false

CLI command: airctrl project list

View a project

Returns one project or a not-found result when it is unavailable.

airctrl project get "$PROJECT_ID" --account "$ACCOUNT_ID"

CLI command: airctrl project get

Create a project

Returns the new project ID. The caller becomes its Project Administrator.

airctrl project create --account "$ACCOUNT_ID" --name "Payments" \
  --description "Credentials used by the payments service"

CLI command: airctrl project create

Update a project

This command replaces all three editable values, so pass the values you want to keep.

airctrl project update "$PROJECT_ID" --account "$ACCOUNT_ID" \
  --name "Payments production" --description "Production credentials" --active true

CLI command: airctrl project update

Archive a project

Archived projects remain stored but leave normal active lists.

airctrl project archive "$PROJECT_ID" --account "$ACCOUNT_ID"

CLI command: airctrl project archive

Restore a project

Returns the restored project state.

airctrl project restore "$PROJECT_ID" --account "$ACCOUNT_ID"

CLI command: airctrl project restore

Record metadata and history

List record metadata

Returns safe metadata, not decrypted fields. Service Account results are limited by its grants and custom role.

airctrl record list --project "$PROJECT_ID" --tab owned --limit 50 --offset 0

CLI command: airctrl record list

View record version history

Returns encrypted version metadata in newest-first order.

airctrl record versions "$RECORD_ID"

CLI command: airctrl record versions

Review one record’s audit history

Returns recent audit events when the caller can view this record’s audit history.

airctrl record audit "$RECORD_ID" --limit 25

CLI command: airctrl record audit

Find unusual record activity

Returns unusual record events for the selected scope.

airctrl record anomalies --account "$ACCOUNT_ID" --scope-type project --scope-id "$PROJECT_ID"

CLI command: airctrl record anomalies

Review daily record activity

The date is UTC and must use YYYY-MM-DD.

airctrl record activity 2026-09-10 --account "$ACCOUNT_ID" \
  --scope-type project --scope-id "$PROJECT_ID"

CLI command: airctrl record activity

Review record alerts

Returns the paginated alert feed.

airctrl record alerts --account "$ACCOUNT_ID" --scope-type project \
  --scope-id "$PROJECT_ID" --limit 25 --offset 0

CLI command: airctrl record alerts

Review secret access events

Returns matching record access events. Action names are exact strings.

airctrl record access --account "$ACCOUNT_ID" --scope-type project \
  --scope-id "$PROJECT_ID" --actions record.secret_access,record.read --limit 25

CLI command: airctrl record access

Update record details

Only supplied fields change. Use the documented null or none value to clear optional fields.

airctrl record metadata "$RECORD_ID" --tags payments,production \
  --secret-due 2026-12-01T00:00:00Z --rotation-days 90

CLI command: airctrl record metadata

Archive a record

Archives the record without deleting encrypted history.

airctrl record archive "$RECORD_ID"

CLI command: airctrl record archive

Restore a record

Restores an archived record to active lists.

airctrl record restore "$RECORD_ID"

CLI command: airctrl record restore

Transfer record ownership

The new owner must be eligible. Confirm both IDs before transferring ownership.

airctrl record transfer "$RECORD_ID" --owner "$NEW_OWNER_USER_ID"

CLI command: airctrl record transfer

Restore a previous record version

saves the selected encrypted version as a new current version; it does not erase later history.

airctrl record rollback "$RECORD_ID" --version "$VERSION_ID"

CLI command: airctrl record rollback

Replace record fields by ID

Updates the encrypted value under the record’s existing key.

airctrl record set "$RECORD_ID" --field username=app_user --field password="$NEW_PASSWORD"

CLI command: airctrl record set

Rotate a record

Rotates the record data key locally and saves a new encrypted version.

airctrl record rotate "$RECORD_ID"

CLI command: airctrl record rotate

The recipient must be onboarded and eligible for the project.

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

CLI command: airctrl record share-user

Encrypts a wrapper for the Service Account. This does not change its custom role.

airctrl record share-sa "$RECORD_ID" --account "$ACCOUNT_ID" \
  --service-account "$SERVICE_ACCOUNT_ID"

CLI command: airctrl record share-sa

The group must belong to the same account and project as the record.

airctrl record share-group "$RECORD_ID" --group "$GROUP_ID"

CLI command: airctrl record share-group

Remove a user’s record access

Removes the user’s direct grant and wrapper immediately.

airctrl record revoke-user "$RECORD_ID" --user "$USER_ID"

CLI command: airctrl record revoke-user

Remove a Service Account’s record access

Removes only this record grant. Other Service Account grants remain unchanged.

airctrl record revoke-sa "$RECORD_ID" --service-account "$SERVICE_ACCOUNT_ID"

CLI command: airctrl record revoke-sa

Remove a group’s record access

Removes the group grant and wrappers created through that grant.

airctrl record revoke-group "$RECORD_ID" --group "$GROUP_ID"

CLI command: airctrl record revoke-group

Gateway discovery and lifecycle

List supported AI providers

Returns enabled providers. This command is available to both human and Service Account identities.

airctrl gateway providers

CLI command: airctrl gateway providers

List gateways

Returns gateways in one project. This command requires a human PAT.

airctrl gateway list --project "$PROJECT_ID"

CLI command: airctrl gateway list

View a gateway

Returns one accessible gateway and safe settings. Service Accounts may use this read.

airctrl gateway get "$GATEWAY_ID"

CLI command: airctrl gateway get

Create a gateway

Returns the gateway ID. Each provider credential must belong to the same account, and --model must exist in that credential’s live catalog.

airctrl gateway create --account "$ACCOUNT_ID" --project "$PROJECT_ID" \
  --name "Payments AI" --provider "$PROVIDER_ID" --model gpt-5 \
  --credential "$PROVIDER_CREDENTIAL_ID"

CLI command: airctrl gateway create

Update a gateway

Only supplied fields change.

airctrl gateway update "$GATEWAY_ID" --account "$ACCOUNT_ID" \
  --name "Payments AI production" --model gpt-5 --active true

CLI command: airctrl gateway update

Delete a gateway

This disables the gateway and revokes its gateway tokens. Confirm the gateway ID first.

airctrl gateway delete "$GATEWAY_ID" --account "$ACCOUNT_ID"

CLI command: airctrl gateway delete

Provider credentials

List provider credentials

Returns safe credential metadata; provider secret values never appear.

airctrl gateway provider-credentials --account "$ACCOUNT_ID"

CLI command: airctrl gateway provider-credentials

Add a provider credential

The CLI reads the secret from the named environment variable and never places it in the command arguments.

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

CLI command: airctrl gateway provider-credential-create

List models for a credential

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.

airctrl gateway provider-models "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"

CLI command: airctrl gateway provider-models

Replace a provider key

The old provider key stops being used after the replacement validates.

airctrl gateway provider-credential-rotate "$PROVIDER_CREDENTIAL_ID" \
  --account "$ACCOUNT_ID" --api-key-env OPENAI_REPLACEMENT_KEY

CLI command: airctrl gateway provider-credential-rotate

Rename a provider credential

Changes only the display label.

airctrl gateway provider-credential-update "$PROVIDER_CREDENTIAL_ID" \
  --account "$ACCOUNT_ID" --label "Primary OpenAI"

CLI command: airctrl gateway provider-credential-update

Revoke a provider credential

Revocation prevents future provider use. Confirm dependent gateways first.

airctrl gateway provider-credential-revoke "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"

CLI command: airctrl gateway provider-credential-revoke

Attach a provider credential

Validates --model against the existing credential’s live catalog, then attaches that exact key/model binding to the gateway.

airctrl gateway credential-attach "$GATEWAY_ID" "$PROVIDER_CREDENTIAL_ID" \
  --account "$ACCOUNT_ID" --model gpt-5

CLI command: airctrl gateway credential-attach

Detach a provider credential

Detaches the credential from this gateway without revoking the credential itself.

airctrl gateway credential-detach "$GATEWAY_ID" "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"

CLI command: airctrl gateway credential-detach

Gateway tokens

List gateway tokens

Returns safe token metadata. Token plaintext is never listed again.

airctrl gateway tokens "$GATEWAY_ID"

CLI command: airctrl gateway tokens

Create a gateway token

The token value appears once. Save it immediately in an approved destination.

airctrl gateway token-create "$GATEWAY_ID" --account "$ACCOUNT_ID" \
  --name "Local development" --expires-days 30 --scopes run,read_logs \
  --allowed-models gpt-5,gpt-5-mini --rate-limit 60

CLI command: airctrl gateway token-create

Rename a gateway token

Changes the label, not the token value.

airctrl gateway token-rename "$GATEWAY_ID" "$TOKEN_ID" \
  --account "$ACCOUNT_ID" --name "CI production"

CLI command: airctrl gateway token-rename

Revoke a gateway token

Authentication stops immediately. The token row remains available for audit.

airctrl gateway token-revoke "$GATEWAY_ID" "$TOKEN_ID" --account "$ACCOUNT_ID"

CLI command: airctrl gateway token-revoke

Delete a gateway token

Deletes token metadata. Revoke first when you need a clear audit transition.

airctrl gateway token-delete "$GATEWAY_ID" "$TOKEN_ID" --account "$ACCOUNT_ID"

CLI command: airctrl gateway token-delete

Routing, limits and telemetry

Change gateway limits and behavior

Only supplied settings change. Body logging can store sensitive request content, so keep it disabled unless required.

airctrl gateway settings "$GATEWAY_ID" --account "$ACCOUNT_ID" \
  --spend-limit 100 --spend-window monthly --rate-limit 120 \
  --logging true --log-bodies false --guardrail flag --cache true --cache-ttl 300

CLI command: airctrl gateway settings

Review gateway requests

Returns request metadata. Service Accounts may use this read when their role permits it.

airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z \
  --status 200 --limit 50 --offset 0

CLI command: airctrl gateway logs

Inspect one gateway request

Returns stored bodies only when body logging and the required permission are both present.

airctrl gateway log "$GATEWAY_ID" "$LOG_ID"

CLI command: airctrl gateway log

Review provider-key access

Returns provider-key access decisions without returning provider keys.

airctrl gateway key-access "$GATEWAY_ID" --outcome denied \
  --since 2026-09-01T00:00:00Z --limit 50 --offset 0

CLI command: airctrl gateway key-access

Review project usage logs

Returns usage metadata across the selected project.

airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
  --since 2026-09-01T00:00:00Z --limit 50 --offset 0

CLI command: airctrl gateway usage-logs

Inspect one project usage log

Returns one project log and any stored bodies allowed by RBAC.

airctrl gateway usage-log "$LOG_ID" --project "$PROJECT_ID"

CLI command: airctrl gateway usage-log

Review project spend

Returns current spend and the effective project or account limit.

airctrl gateway usage-spend --project "$PROJECT_ID"

CLI command: airctrl gateway usage-spend

Review project usage metrics

Returns request, error, token, latency and spend aggregates.

airctrl gateway usage-metrics --project "$PROJECT_ID" \
  --since 2026-09-01T00:00:00Z --bucket day

CLI command: airctrl gateway usage-metrics

View OpenTelemetry settings

Returns safe OpenTelemetry settings. Secret header values are never returned.

airctrl gateway otel "$GATEWAY_ID" --account "$ACCOUNT_ID"

CLI command: airctrl gateway otel

Change OpenTelemetry settings

The CLI reads header values from the named environment variable. Use --clear-headers true to remove stored headers.

airctrl gateway otel-update "$GATEWAY_ID" --account "$ACCOUNT_ID" \
  --enabled true --endpoint https://otel.example.com/v1/traces \
  --metrics true --traces true --headers-env OTEL_EXPORT_HEADERS

CLI command: airctrl gateway otel-update

Service Account metadata

List Service Accounts

Returns safe Service Account metadata to a human PAT.

airctrl sa list --account "$ACCOUNT_ID"

CLI command: airctrl sa list

View a Service Account

Returns one Service Account from the safe metadata list. Lifecycle and credential actions remain dashboard-only.

airctrl sa get "$SERVICE_ACCOUNT_ID" --account "$ACCOUNT_ID"

CLI command: airctrl sa get

Common exit behavior

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.

​Prepare the examples

​Local setup and record access

​Sign in to

​Read a complete record

​Read selected record fields

​Inject records into a process

​Generate a secret locally

​Create an encrypted record

​Create or replace record fields

​Create a generated record

​Import environment variables

​Account and project commands

​List accessible accounts

​List projects

​View a project

​Create a project

​Update a project

​Archive a project

​Restore a project

​Record metadata and history

​List record metadata

​View record version history

​Review one record’s audit history

​Find unusual record activity

​Review daily record activity

​Review record alerts

​Review secret access events

​Update record details

​Archive a record

​Restore a record

​Transfer record ownership

​Restore a previous record version

​Replace record fields by ID

​Rotate a record

​Record sharing

​Share a record with a user

​Share a record with a Service Account

​Share a record with a group

​Remove a user’s record access

​Remove a Service Account’s record access

​Remove a group’s record access

​Gateway discovery and lifecycle

​List supported AI providers

​List gateways

​View a gateway

​Create a gateway

​Update a gateway

​Delete a gateway

​Provider credentials

​List provider credentials

​Add a provider credential

​List models for a credential

​Replace a provider key

​Rename a provider credential

​Revoke a provider credential

​Attach a provider credential

​Detach a provider credential

​Gateway tokens

​List gateway tokens

​Create a gateway token

​Rename a gateway token

​Revoke a gateway token

​Delete a gateway token

​Routing, limits and telemetry

​Change gateway limits and behavior

​Review gateway requests

​Inspect one gateway request

​Review provider-key access

​Review project usage logs

​Inspect one project usage log

​Review project spend

​Review project usage metrics

​View OpenTelemetry settings

​Change OpenTelemetry settings

​Service Account metadata

​List Service Accounts

​View a Service Account

​Common exit behavior