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

> Install AIRCTRL CLI, authenticate, and run commands safely.

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

`@airctrl/cli` lets you work with <AirctrlWordmark /> from a terminal and inject records into a process without creating a local `.env` file.

## Install

```bash theme={}
npm install --global @airctrl/cli
```

You can also run it without a global installation:

```bash theme={}
npx @airctrl/cli --help
```

## Human login

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

The command asks for:

* API base URL.
* Personal Access Token.
* Optional default project ID.

It saves this human configuration in `~/.airctrl/config.json`.

For non-interactive jobs, use:

| Variable            | Purpose                                                         |
| ------------------- | --------------------------------------------------------------- |
| `AC_API_BASE_URL`   | <AirctrlWordmark /> API URL.                                    |
| `AC_TOKEN`          | Human PAT or the bearer from a complete Service Account bundle. |
| `AC_VAULT_PASSWORD` | Human vault passphrase for local record cryptography.           |

## Service Account execution

An active Service Account requires `AC_TOKEN`, `AC_API_BASE_URL`, `AC_SA_CREDENTIAL_ID`, and `AC_SA_CAP_PRIVATE_KEY_B64` from one credential bundle. `AC_SA_SERVICE_ACCOUNT_ID` carries the bundle identity when available.

Do not mix fields from different bundles. An incomplete Service Account environment fails instead of falling back to human mode.

Service Account mode exposes a smaller command set for unattended record and Gateway work. Human-only
commands fail before an SDK or API call. See [CLI commands](/cli/commands) for the exact list.

## Inject records

```bash theme={}
airctrl run --project "$PROJECT_ID" -- node server.js
```

The CLI:

1. Reads accessible records in that project.
2. Decrypts them locally.
3. Converts record names to uppercase environment keys.
4. Removes <AirctrlWordmark /> control variables from the child environment.
5. Starts the child process with the record values in memory.

It does not write a `.env` file.

The CLI login belongs only to the CLI. SDK applications and MCP servers must receive their own explicit configuration. See [Combine <AirctrlWordmark /> tools](/guides/tool-workflows) for safe mixed workflows.

## Output and errors

Read commands print JSON or the requested value to stdout. Operational messages and stable errors use stderr. A failed command returns a non-zero exit status.

See [CLI commands](/cli/commands) and [Errors and retries](/reference/errors).