Airscale CLI - Airscale API

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.

npx (no install)
npm (global)

npx @airscale/cli --help

Replace airscale with npx @airscale/cli in the examples below.

npm install --global @airscale/cli
airscale --help

Preview a file for free

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

contacts.csv

first_name,last_name,domain
Avery,Stone,northstar.example
Morgan,Lee,solstice.example

Validate both rows and calculate the maximum exposure locally:

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:

{
  "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, under Settings → API key, then enter it through the hidden prompt:

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:

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:

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:

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:

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:

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 for every command, flag, input rule, and pagination behavior. See 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.

airscale --base-url http://127.0.0.1:8787/v1 auth status --json

​Install

​Preview a file for free

​Connect your workspace

​Enrich the sample

​More bounded examples

​Output and exit codes

​Configuration