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

# Airscale CLI

> Install the Airscale CLI, preview a contact file for free, connect a workspace, and run bounded searches and enrichment.

`airscale` lets you search for people and companies, enrich work emails from CSV or JSONL, check credits, and follow durable runs from a terminal.

## Install

Requires **Node.js 20.3 or newer**. This guide covers CLI **0.2.1**. If you installed an earlier version, follow the [upgrade instructions](/cli/troubleshooting#upgrade-the-cli).

<Tabs>
  <Tab title="npx (no install)">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npx @airscale/cli --help
    ```

    Replace `airscale` with `npx @airscale/cli` in the examples below.
  </Tab>

  <Tab title="npm (global)">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npm install --global @airscale/cli
    airscale --help
    ```
  </Tab>
</Tabs>

## Preview a file for free

Create `contacts.csv` with two fictional contacts and reserved example domains:

```csv contacts.csv theme={"theme":{"light":"github-light","dark":"github-dark"}}
first_name,last_name,domain
Avery,Stone,northstar.example
Morgan,Lee,solstice.example
```

Validate both rows and calculate the maximum exposure locally:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
airscale enrich file contacts.csv \
  --dry-run --json --quiet
```

This dry run needs no `--output` or confirmation. It runs without credentials, HTTP requests, or credit spend. With `--json --quiet`, stdout contains only:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "rows": 2,
  "valid_rows": 2,
  "estimated_max_credits": 4,
  "field": "work_email",
  "format": "csv",
  "output": null,
  "dry_run": true
}
```

## Connect your workspace

Create a workspace key in the [Airscale dashboard](https://app.airscale.io/dashboard), under **Settings → API key**, then enter it through the hidden prompt:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
airscale auth login
airscale auth status --json
```

`auth login` stores the key locally and shows `airscale auth status` as the next step. The status command makes a free `/credits` request to verify the key and connectivity. It displays the credential source and a short fingerprint without printing the key.

For a guided first-time flow, run:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
airscale setup
```

`setup` points you to **Settings → API key**, checks for an existing credential, and uses the hidden prompt only when none exists. It finishes with the same free credit check. The command is interactive; scripts should configure `AIRSCALE_API_KEY` through a secret manager.

API keys cannot be passed as command-line arguments. `AIRSCALE_API_KEY` takes precedence over a saved credential.

## Enrich the sample

Replace the fictional rows with contacts you are authorized to enrich, then run the free preview again. Review any validation errors and the updated estimate before starting paid work.

For a validated two-row file, provide a real output path and approve a maximum of 4 credits:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
airscale enrich file contacts.csv \
  --output contacts-enriched.csv --max-credits 4 \
  --confirm-credit-spend --resume --json
```

Fresh paid execution requires `--output`. `--resume` saves credential-free state so the same command can continue an interrupted run without starting a replacement batch. Keep the input, output path, field, format, and API URL unchanged when resuming.

## More bounded examples

Find up to five people with a maximum exposure of 0.5 credit:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
airscale people search \
  --title CTO --company-domain northstar.example \
  --size 5 --max-credits 0.5 \
  --confirm-credit-spend --json
```

Export up to 20 companies as CSV:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
airscale companies search \
  --country France --industry Software \
  --size 20 --limit 20 --max-credits 2 \
  --confirm-credit-spend --format csv --output companies.csv
```

Searches cost **0.1 credit per returned result**. Before paid work starts, the CLI checks the maximum row budget and available credits. Interactive terminals can confirm at the prompt; scripts must pass `--confirm-credit-spend`.

Use the `exp_…` run ID from enrichment output or saved state for free status reads:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
airscale runs status exp_example --json
airscale runs wait exp_example --json
```

To download a completed enrichment file, rerun `enrich file` with `--resume`.

See the [command reference](/cli/commands) for every command, flag, input rule, and pagination behavior. See [Troubleshooting](/cli/troubleshooting) for installation, authentication, CSV, confirmation, and resume errors.

## Output and exit codes

All results, including interactive tables and `--output -`, go to stdout. Progress and errors go to stderr, so result pipelines stay clean. `--quiet` hides progress and informational messages, but never hides errors.

For `credits`, search, and run commands, choose `--json`, `--jsonl`, or `--format json|jsonl|csv|table`. A real `--output path` writes a file. When format flags are combined, `--json` takes precedence over `--jsonl`, then `--format`.

Search JSON includes the response envelope and continuation cursor. CSV and JSONL contain result records. Use JSON when you need pagination metadata.

| Exit code | Meaning                                                                   |
| --------- | ------------------------------------------------------------------------- |
| `0`       | Success.                                                                  |
| `2`       | Invalid command, option, input, state, or file access.                    |
| `3`       | Missing or invalid authentication or configuration.                       |
| `4`       | Credit ceiling, insufficient credits, confirmation, or admission failure. |
| `5`       | API or durable-run failure.                                               |
| `130`     | Interrupted with Ctrl-C; enrichment state is retained.                    |

## Configuration

| Setting                   | Configuration                               | Precedence or default                                                           |
| ------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------- |
| API key                   | `AIRSCALE_API_KEY` or `airscale auth login` | Environment variable before saved credentials. `auth set-key` remains an alias. |
| API URL                   | `--base-url` or `AIRSCALE_API_BASE_URL`     | Flag, then environment variable, then `https://api.airscale.io/v1`.             |
| Credential file directory | `XDG_CONFIG_HOME`                           | `$XDG_CONFIG_HOME/airscale`, otherwise `~/.config/airscale`.                    |

Saved credentials use the optional system keychain when available, under service `airscale` and account `default`. Otherwise they are stored in `config.json` inside the credential directory, with file permissions `0600` and directory permissions `0700`.

API URLs must use HTTPS, except for HTTP on loopback addresses such as `http://127.0.0.1:8787/v1`. URLs containing credentials, query parameters, or fragments are rejected.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
airscale --base-url http://127.0.0.1:8787/v1 auth status --json
```