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"
export IDEMPOTENCY_KEY="00000000-0000-4000-8000-000000000090"

Use airctrl project accounts, airctrl project list, airctrl record list and airctrl gateway list 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. 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"

For a By Environment record, select exactly one value:

airctrl get "$RECORD_ID" --env staging

CLI command: airctrl get

Read selected record sections

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; never expands access beyond the record grant.

airctrl read "$RECORD_ID" --scope meta,fields

To read the Staging value of an Environment record:

airctrl read "$RECORD_ID" --scope meta,fields --env staging

CLI command: airctrl read

Inject records into a process

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.

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

airctrl run --project "$PROJECT_ID" --env staging -- 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 service_name=Database --field username=app_user --field password="$DATABASE_PASSWORD" \
  --tags database,production --rotation-days 90 \
  --idempotency-key "$IDEMPOTENCY_KEY"

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 plain --project "$PROJECT_ID" --name "Payments token" \
  --field body="$PAYMENTS_TOKEN" \
  --idempotency-key "$IDEMPOTENCY_KEY"

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. This certificate generator fills the format’s required fields; other formats may need additional non-secret fields supplied through the SDK or Web app.

airctrl new certificate --project "$PROJECT_ID" --name "Generated TLS certificate" --cn api.example.invalid

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. --target-env names a field inside the ENV-format record; --env separately selects the record’s encrypted Development, Staging, or Production value.

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

Page and filter one record’s audit history

airctrl record audit-events "$RECORD_ID" --action record.update --actor david --limit 25
# Continue with pagination.next_cursor from the previous JSON response.
airctrl record audit-events "$RECORD_ID" --action record.update --actor david \
  --limit 25 --cursor "$NEXT_CURSOR"

CLI command: airctrl record audit-events

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

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.

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. This replaces the complete field map; include unchanged fields you need to retain.

airctrl record set "$RECORD_ID" --field service_name=Database \
  --field username=app_user --field password="$NEW_PASSWORD" \
  --idempotency-key "$IDEMPOTENCY_KEY"

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

Groups

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.

List context groups

airctrl group list "$PROJECT_ID" --account "$AIRCTRL_ACCOUNT_ID"

CLI command: airctrl group list

Read a record’s group grants

airctrl group record-grants "$RECORD_ID" --account "$AIRCTRL_ACCOUNT_ID"

CLI command: airctrl group record-grants

Create a group

Creation does not grant a project role.

airctrl group create "$PROJECT_ID" --account "$AIRCTRL_ACCOUNT_ID" --name "Payments team" --description "Payments operators"

CLI command: airctrl group create

Rename a group

Omitting description clears it.

airctrl group update "$GROUP_ID" --account "$AIRCTRL_ACCOUNT_ID" --name "Payments operators" --description "Payments access"

CLI command: airctrl group update

Delete a group

Deletes only this group’s access paths. Review remaining sources and pending re-keying.

airctrl group delete "$GROUP_ID" --account "$AIRCTRL_ACCOUNT_ID"

CLI command: airctrl group delete

List group members

airctrl group members "$GROUP_ID" --account "$AIRCTRL_ACCOUNT_ID"

CLI command: airctrl group members

Add a group member

The person must be an onboarded account member. The result can report pending encrypted material.

airctrl group add-member "$GROUP_ID" "$USER_ID" --account "$AIRCTRL_ACCOUNT_ID"

CLI command: airctrl group add-member

Remove a group member

Preserves access through other groups, project membership or direct record shares.

airctrl group remove-member "$GROUP_ID" "$USER_ID" --account "$AIRCTRL_ACCOUNT_ID"

CLI command: airctrl group remove-member

Grant a project role to a group

Use a delegable role ID from the SDK catalog or API reference; do not guess IDs.

airctrl group grant-project "$PROJECT_ID" "$GROUP_ID" "$ROLE_ID" --account "$AIRCTRL_ACCOUNT_ID"

CLI command: airctrl group grant-project

Revoke one project role from a group

Removes only this project/group/role assignment.

airctrl group revoke-project "$PROJECT_ID" "$GROUP_ID" "$ROLE_ID" --account "$AIRCTRL_ACCOUNT_ID"

CLI command: airctrl group revoke-project

Complete pending encrypted access

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.

airctrl group reconcile --account "$AIRCTRL_ACCOUNT_ID" --project "$PROJECT_ID"

CLI command: airctrl group reconcile

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 record’s account. A direct record share does not grant project access.

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. Other authorized paths remain; wrappers are removed only where effective access is lost.

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. Other authorized paths remain; wrappers are removed only where effective access is lost.

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-binding "$PROVIDER_CREDENTIAL_ID=gpt-5"

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 every repeated --model against one live catalog, then attaches all exact key/model bindings to the gateway.

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

CLI command: airctrl gateway credential-attach

Detach a provider credential

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.

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

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

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 --until 2026-10-01T00:00:00Z \
  --status 200 --limit 50

# Continue with pagination.next_cursor from the previous JSON response.
airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z --until 2026-10-01T00:00:00Z \
  --status 200 --limit 50 --cursor "$NEXT_CURSOR"

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 --until 2026-10-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 --until 2026-10-01T00:00:00Z --limit 50

# Keep the exact same filters when continuing a cursor.
airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
  --since 2026-09-01T00:00:00Z --until 2026-10-01T00:00:00Z --limit 50 --cursor "$NEXT_CURSOR"

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 --until 2026-10-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 \
  --metrics true --traces true --bodies 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 AIRCTRL

​Read a complete record

​Read selected record sections

​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

​Page and filter 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

​Groups

​List context groups

​Read a record’s group grants

​Create a group

​Rename a group

​Delete a group

​List group members

​Add a group member

​Remove a group member

​Grant a project role to a group

​Revoke one project role from a group

​Complete pending encrypted access

​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