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

# Use the CLI with Bash

> Install and use AIRCTRL CLI from Bash on macOS or Linux.

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 this guide in Bash on macOS or Linux. It keeps record values in the child process memory instead of writing a `.env` file into your repository.

## Install and sign in

Install the CLI once, then use `airctrl login` to save your human setup in your user profile.

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

The login command asks for the <AirctrlWordmark /> API URL, your personal access token, and an optional default project. It stores only the human configuration in `~/.airctrl/config.json`.

Run a read-only command first to confirm the selected account:

```bash theme={}
airctrl project list --account "$AIRCTRL_ACCOUNT_ID"
```

## Run an application with record values

Pass a project ID and the command after `--`. The CLI reads only the records you can access, decrypts them locally, and starts the child process with those values in its environment.

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

The values exist only in the child process. <AirctrlWordmark /> control values are removed before the process starts. The CLI does not create or modify a `.env` file.

## Use a Service Account

For unattended work, load the active Service Account credential bundle through your CI or local secret mechanism. Keep all bundle fields together; partial or mixed credentials fail before <AirctrlWordmark /> makes a request. The [CLI overview](/cli/overview) lists the configuration names used by the CLI.

```bash theme={}
airctrl record list --project "$AIRCTRL_PROJECT_ID"
```

A Service Account can use only its assigned permissions and projects. It cannot become a human identity by adding a human configuration file.

## Diagnose a failure

Check the exit code instead of parsing terminal prose. A non-zero result means the command did not complete.

```bash theme={}
if ! airctrl project list --account "$AIRCTRL_ACCOUNT_ID"; then
  echo "AIRCTRL request failed" >&2
  exit 1
fi
```

For an access denial, verify the selected account, project, and identity. Do not retry a permission failure with a broader ID. See [Errors and retries](/reference/errors) and the full [CLI command reference](/cli/commands).