> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airctrl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI example catalog

> Copyable examples for every public AIRCTRL CLI command.

export function AirctrlWordmark() {
  return <span className="airctrl-wordmark" aria-label="AIRCTRL">
      <span aria-hidden="true" className="airctrl-wordmark-air">AIR</span>
      <span aria-hidden="true" className="airctrl-wordmark-ctrl">CTRL</span>
    </span>;
}

This page shows every public CLI command. Replace the environment variables with IDs from your <AirctrlWordmark /> 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:

```bash theme={}
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

### Sign in to <AirctrlWordmark />

<div className="section-help">
  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.
</div>

```bash theme={}
airctrl login
```

<div className="technical-reference">
  **CLI command:** `airctrl login`
</div>

### Read a complete record

<div className="section-help">
  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`.
</div>

```bash theme={}
airctrl get "$RECORD_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl get`
</div>

### Read selected record fields

<div className="section-help">
  Read only selected fields or one environment from a record. The result contains only the requested fields. <AirctrlWordmark /> never expands access beyond the record grant.
</div>

```bash theme={}
airctrl read "$RECORD_ID" --scope username,password --env production
```

<div className="technical-reference">
  **CLI command:** `airctrl read`
</div>

### Inject records into a process

<div className="section-help">
  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.
</div>

```bash theme={}
airctrl run --project "$PROJECT_ID" -- npm run dev
```

<div className="technical-reference">
  **CLI command:** `airctrl run`
</div>

### Generate a secret locally

<div className="section-help">
  Generate secret material locally without storing it. The generated fields are printed once. This command does not call the API.
</div>

```bash theme={}
airctrl generate password --length 32
```

<div className="technical-reference">
  **CLI command:** `airctrl generate`
</div>

### Create an encrypted record

<div className="section-help">
  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.
</div>

```bash theme={}
airctrl create password --project "$PROJECT_ID" --name "Database login" \
  --field username=app_user --field password="$DATABASE_PASSWORD"
```

<div className="technical-reference">
  **CLI command:** `airctrl create`
</div>

### Create or replace record fields

<div className="section-help">
  Update a matching record or create it when it does not exist. The result states whether <AirctrlWordmark /> created or updated the record.
</div>

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

<div className="technical-reference">
  **CLI command:** `airctrl set`
</div>

### Create a generated record

<div className="section-help">
  Generate, encrypt and store a new record. The command returns the record ID. The generated value is encrypted before it leaves the CLI.
</div>

```bash theme={}
airctrl new password --project "$PROJECT_ID" --name "Generated database password" --length 32
```

<div className="technical-reference">
  **CLI command:** `airctrl new`
</div>

### Import environment variables

<div className="section-help">
  Import an ENV file as one encrypted record. The source file stays unchanged. Review it before import so unrelated local variables are not stored.
</div>

```bash theme={}
airctrl import env ./.env.production --project "$PROJECT_ID" \
  --name "Production environment" --target-env production
```

<div className="technical-reference">
  **CLI command:** `airctrl import`
</div>

## Account and project commands

### List accessible accounts

<div className="section-help">
  Returns accounts available to the human PAT. Service Accounts cannot discover accounts.
</div>

```bash theme={}
airctrl project accounts
```

<div className="technical-reference">
  **CLI command:** `airctrl project accounts`
</div>

### List projects

<div className="section-help">
  Returns accessible projects in the selected account.
</div>

```bash theme={}
airctrl project list --account "$ACCOUNT_ID" --include-archived false
```

<div className="technical-reference">
  **CLI command:** `airctrl project list`
</div>

### View a project

<div className="section-help">
  Returns one project or a not-found result when it is unavailable.
</div>

```bash theme={}
airctrl project get "$PROJECT_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl project get`
</div>

### Create a project

<div className="section-help">
  Returns the new project ID. The caller becomes its Project Administrator.
</div>

```bash theme={}
airctrl project create --account "$ACCOUNT_ID" --name "Payments" \
  --description "Credentials used by the payments service"
```

<div className="technical-reference">
  **CLI command:** `airctrl project create`
</div>

### Update a project

<div className="section-help">
  This command replaces all three editable values, so pass the values you want to keep.
</div>

```bash theme={}
airctrl project update "$PROJECT_ID" --account "$ACCOUNT_ID" \
  --name "Payments production" --description "Production credentials" --active true
```

<div className="technical-reference">
  **CLI command:** `airctrl project update`
</div>

### Archive a project

<div className="section-help">
  Archived projects remain stored but leave normal active lists.
</div>

```bash theme={}
airctrl project archive "$PROJECT_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl project archive`
</div>

### Restore a project

<div className="section-help">
  Returns the restored project state.
</div>

```bash theme={}
airctrl project restore "$PROJECT_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl project restore`
</div>

## Record metadata and history

### List record metadata

<div className="section-help">
  Returns safe metadata, not decrypted fields. Service Account results are limited by its grants and custom role.
</div>

```bash theme={}
airctrl record list --project "$PROJECT_ID" --tab owned --limit 50 --offset 0
```

<div className="technical-reference">
  **CLI command:** `airctrl record list`
</div>

### View record version history

<div className="section-help">
  Returns encrypted version metadata in newest-first order.
</div>

```bash theme={}
airctrl record versions "$RECORD_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record versions`
</div>

### Review one record's audit history

<div className="section-help">
  Returns recent audit events when the caller can view this record's audit history.
</div>

```bash theme={}
airctrl record audit "$RECORD_ID" --limit 25
```

<div className="technical-reference">
  **CLI command:** `airctrl record audit`
</div>

### Find unusual record activity

<div className="section-help">
  Returns unusual record events for the selected scope.
</div>

```bash theme={}
airctrl record anomalies --account "$ACCOUNT_ID" --scope-type project --scope-id "$PROJECT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record anomalies`
</div>

### Review daily record activity

<div className="section-help">
  The date is UTC and must use `YYYY-MM-DD`.
</div>

```bash theme={}
airctrl record activity 2026-09-10 --account "$ACCOUNT_ID" \
  --scope-type project --scope-id "$PROJECT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record activity`
</div>

### Review record alerts

<div className="section-help">
  Returns the paginated alert feed.
</div>

```bash theme={}
airctrl record alerts --account "$ACCOUNT_ID" --scope-type project \
  --scope-id "$PROJECT_ID" --limit 25 --offset 0
```

<div className="technical-reference">
  **CLI command:** `airctrl record alerts`
</div>

### Review secret access events

<div className="section-help">
  Returns matching record access events. Action names are exact strings.
</div>

```bash theme={}
airctrl record access --account "$ACCOUNT_ID" --scope-type project \
  --scope-id "$PROJECT_ID" --actions record.secret_access,record.read --limit 25
```

<div className="technical-reference">
  **CLI command:** `airctrl record access`
</div>

### Update record details

<div className="section-help">
  Only supplied fields change. Use the documented `null` or `none` value to clear optional fields.
</div>

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

<div className="technical-reference">
  **CLI command:** `airctrl record metadata`
</div>

### Archive a record

<div className="section-help">
  Archives the record without deleting encrypted history.
</div>

```bash theme={}
airctrl record archive "$RECORD_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record archive`
</div>

### Restore a record

<div className="section-help">
  Restores an archived record to active lists.
</div>

```bash theme={}
airctrl record restore "$RECORD_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record restore`
</div>

### Transfer record ownership

<div className="section-help">
  The new owner must be eligible. Confirm both IDs before transferring ownership.
</div>

```bash theme={}
airctrl record transfer "$RECORD_ID" --owner "$NEW_OWNER_USER_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record transfer`
</div>

### Restore a previous record version

<div className="section-help">
  <AirctrlWordmark /> saves the selected encrypted version as a new current version; it does not erase later history.
</div>

```bash theme={}
airctrl record rollback "$RECORD_ID" --version "$VERSION_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record rollback`
</div>

### Replace record fields by ID

<div className="section-help">
  Updates the encrypted value under the record's existing key.
</div>

```bash theme={}
airctrl record set "$RECORD_ID" --field username=app_user --field password="$NEW_PASSWORD"
```

<div className="technical-reference">
  **CLI command:** `airctrl record set`
</div>

### Rotate a record

<div className="section-help">
  Rotates the record data key locally and saves a new encrypted version.
</div>

```bash theme={}
airctrl record rotate "$RECORD_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record rotate`
</div>

## Record sharing

### Share a record with a user

<div className="section-help">
  The recipient must be onboarded and eligible for the project.
</div>

```bash theme={}
airctrl record share-user "$RECORD_ID" --user "$USER_ID" --permission read
```

<div className="technical-reference">
  **CLI command:** `airctrl record share-user`
</div>

### Share a record with a Service Account

<div className="section-help">
  Encrypts a wrapper for the Service Account. This does not change its custom role.
</div>

```bash theme={}
airctrl record share-sa "$RECORD_ID" --account "$ACCOUNT_ID" \
  --service-account "$SERVICE_ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record share-sa`
</div>

### Share a record with a group

<div className="section-help">
  The group must belong to the same account and project as the record.
</div>

```bash theme={}
airctrl record share-group "$RECORD_ID" --group "$GROUP_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record share-group`
</div>

### Remove a user's record access

<div className="section-help">
  Removes the user's direct grant and wrapper immediately.
</div>

```bash theme={}
airctrl record revoke-user "$RECORD_ID" --user "$USER_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record revoke-user`
</div>

### Remove a Service Account's record access

<div className="section-help">
  Removes only this record grant. Other Service Account grants remain unchanged.
</div>

```bash theme={}
airctrl record revoke-sa "$RECORD_ID" --service-account "$SERVICE_ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record revoke-sa`
</div>

### Remove a group's record access

<div className="section-help">
  Removes the group grant and wrappers created through that grant.
</div>

```bash theme={}
airctrl record revoke-group "$RECORD_ID" --group "$GROUP_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl record revoke-group`
</div>

## Gateway discovery and lifecycle

### List supported AI providers

<div className="section-help">
  Returns enabled providers. This command is available to both human and Service Account identities.
</div>

```bash theme={}
airctrl gateway providers
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway providers`
</div>

### List gateways

<div className="section-help">
  Returns gateways in one project. This command requires a human PAT.
</div>

```bash theme={}
airctrl gateway list --project "$PROJECT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway list`
</div>

### View a gateway

<div className="section-help">
  Returns one accessible gateway and safe settings. Service Accounts may use this read.
</div>

```bash theme={}
airctrl gateway get "$GATEWAY_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway get`
</div>

### Create a gateway

<div className="section-help">
  Returns the gateway ID. Each provider credential must belong to the same account, and `--model` must exist in that credential's live catalog.
</div>

```bash theme={}
airctrl gateway create --account "$ACCOUNT_ID" --project "$PROJECT_ID" \
  --name "Payments AI" --provider "$PROVIDER_ID" --model gpt-5 \
  --credential "$PROVIDER_CREDENTIAL_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway create`
</div>

### Update a gateway

<div className="section-help">
  Only supplied fields change.
</div>

```bash theme={}
airctrl gateway update "$GATEWAY_ID" --account "$ACCOUNT_ID" \
  --name "Payments AI production" --model gpt-5 --active true
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway update`
</div>

### Delete a gateway

<div className="section-help">
  This disables the gateway and revokes its gateway tokens. Confirm the gateway ID first.
</div>

```bash theme={}
airctrl gateway delete "$GATEWAY_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway delete`
</div>

## Provider credentials

### List provider credentials

<div className="section-help">
  Returns safe credential metadata; provider secret values never appear.
</div>

```bash theme={}
airctrl gateway provider-credentials --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway provider-credentials`
</div>

### Add a provider credential

<div className="section-help">
  The CLI reads the secret from the named environment variable and never places it in the command arguments.
</div>

```bash theme={}
airctrl gateway provider-credential-create --account "$ACCOUNT_ID" \
  --provider "$PROVIDER_ID" --label "Production OpenAI" \
  --api-key-env OPENAI_PRODUCTION_KEY --kind api_key
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway provider-credential-create`
</div>

### List models for a credential

<div className="section-help">
  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.
</div>

```bash theme={}
airctrl gateway provider-models "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway provider-models`
</div>

### Replace a provider key

<div className="section-help">
  The old provider key stops being used after the replacement validates.
</div>

```bash theme={}
airctrl gateway provider-credential-rotate "$PROVIDER_CREDENTIAL_ID" \
  --account "$ACCOUNT_ID" --api-key-env OPENAI_REPLACEMENT_KEY
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway provider-credential-rotate`
</div>

### Rename a provider credential

<div className="section-help">
  Changes only the display label.
</div>

```bash theme={}
airctrl gateway provider-credential-update "$PROVIDER_CREDENTIAL_ID" \
  --account "$ACCOUNT_ID" --label "Primary OpenAI"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway provider-credential-update`
</div>

### Revoke a provider credential

<div className="section-help">
  Revocation prevents future provider use. Confirm dependent gateways first.
</div>

```bash theme={}
airctrl gateway provider-credential-revoke "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway provider-credential-revoke`
</div>

### Attach a provider credential

<div className="section-help">
  Validates `--model` against the existing credential's live catalog, then attaches that exact key/model binding to the gateway.
</div>

```bash theme={}
airctrl gateway credential-attach "$GATEWAY_ID" "$PROVIDER_CREDENTIAL_ID" \
  --account "$ACCOUNT_ID" --model gpt-5
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway credential-attach`
</div>

### Detach a provider credential

<div className="section-help">
  Detaches the credential from this gateway without revoking the credential itself.
</div>

```bash theme={}
airctrl gateway credential-detach "$GATEWAY_ID" "$PROVIDER_CREDENTIAL_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway credential-detach`
</div>

## Gateway tokens

### List gateway tokens

<div className="section-help">
  Returns safe token metadata. Token plaintext is never listed again.
</div>

```bash theme={}
airctrl gateway tokens "$GATEWAY_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway tokens`
</div>

### Create a gateway token

<div className="section-help">
  The token value appears once. Save it immediately in an approved destination.
</div>

```bash theme={}
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
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway token-create`
</div>

### Rename a gateway token

<div className="section-help">
  Changes the label, not the token value.
</div>

```bash theme={}
airctrl gateway token-rename "$GATEWAY_ID" "$TOKEN_ID" \
  --account "$ACCOUNT_ID" --name "CI production"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway token-rename`
</div>

### Revoke a gateway token

<div className="section-help">
  Authentication stops immediately. The token row remains available for audit.
</div>

```bash theme={}
airctrl gateway token-revoke "$GATEWAY_ID" "$TOKEN_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway token-revoke`
</div>

### Delete a gateway token

<div className="section-help">
  Deletes token metadata. Revoke first when you need a clear audit transition.
</div>

```bash theme={}
airctrl gateway token-delete "$GATEWAY_ID" "$TOKEN_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway token-delete`
</div>

## Routing, limits and telemetry

### Change gateway limits and behavior

<div className="section-help">
  Only supplied settings change. Body logging can store sensitive request content, so keep it disabled unless required.
</div>

```bash theme={}
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
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway settings`
</div>

### Review gateway requests

<div className="section-help">
  Returns request metadata. Service Accounts may use this read when their role permits it.
</div>

```bash theme={}
airctrl gateway logs "$GATEWAY_ID" --since 2026-09-01T00:00:00Z \
  --status 200 --limit 50 --offset 0
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway logs`
</div>

### Inspect one gateway request

<div className="section-help">
  Returns stored bodies only when body logging and the required permission are both present.
</div>

```bash theme={}
airctrl gateway log "$GATEWAY_ID" "$LOG_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway log`
</div>

### Review provider-key access

<div className="section-help">
  Returns provider-key access decisions without returning provider keys.
</div>

```bash theme={}
airctrl gateway key-access "$GATEWAY_ID" --outcome denied \
  --since 2026-09-01T00:00:00Z --limit 50 --offset 0
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway key-access`
</div>

### Review project usage logs

<div className="section-help">
  Returns usage metadata across the selected project.
</div>

```bash theme={}
airctrl gateway usage-logs --project "$PROJECT_ID" --gateway "$GATEWAY_ID" \
  --since 2026-09-01T00:00:00Z --limit 50 --offset 0
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway usage-logs`
</div>

### Inspect one project usage log

<div className="section-help">
  Returns one project log and any stored bodies allowed by RBAC.
</div>

```bash theme={}
airctrl gateway usage-log "$LOG_ID" --project "$PROJECT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway usage-log`
</div>

### Review project spend

<div className="section-help">
  Returns current spend and the effective project or account limit.
</div>

```bash theme={}
airctrl gateway usage-spend --project "$PROJECT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway usage-spend`
</div>

### Review project usage metrics

<div className="section-help">
  Returns request, error, token, latency and spend aggregates.
</div>

```bash theme={}
airctrl gateway usage-metrics --project "$PROJECT_ID" \
  --since 2026-09-01T00:00:00Z --bucket day
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway usage-metrics`
</div>

### View OpenTelemetry settings

<div className="section-help">
  Returns safe OpenTelemetry settings. Secret header values are never returned.
</div>

```bash theme={}
airctrl gateway otel "$GATEWAY_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway otel`
</div>

### Change OpenTelemetry settings

<div className="section-help">
  The CLI reads header values from the named environment variable. Use `--clear-headers true` to remove stored headers.
</div>

```bash theme={}
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
```

<div className="technical-reference">
  **CLI command:** `airctrl gateway otel-update`
</div>

## Service Account metadata

### List Service Accounts

<div className="section-help">
  Returns safe Service Account metadata to a human PAT.
</div>

```bash theme={}
airctrl sa list --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl sa list`
</div>

### View a Service Account

<div className="section-help">
  Returns one Service Account from the safe metadata list. Lifecycle and credential actions remain dashboard-only.
</div>

```bash theme={}
airctrl sa get "$SERVICE_ACCOUNT_ID" --account "$ACCOUNT_ID"
```

<div className="technical-reference">
  **CLI command:** `airctrl sa get`
</div>

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