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

> Complete command reference for the AIRCTRL CLI.

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>;
}

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](/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:

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

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

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

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

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

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

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

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

```text theme={}
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 <AirctrlWordmark /> 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:

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

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

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

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

```bash theme={}
airctrl record list --project "$PROJECT_ID" --limit 50
airctrl run --project "$PROJECT_ID" -- npm run dev
```

Change safe metadata and review immutable history:

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

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

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

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

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

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