# AddressZen CLI

`azn` is the official command line interface for AddressZen. It manages API keys, verifies US addresses, validates emails and phone numbers, and resolves specific addresses from partial queries.

It is built for LLM agents (Claude Code, Cursor, Codex) and CI/CD pipelines, and works equally well from a terminal.

## Installation

Requires Node.js 22 or later.

```bash
npm install -g @addresszen/cli
azn --version
```

## Agent protocol

The CLI auto-detects non-TTY environments and emits JSON; no `--json` flag needed when piping or running headless.

* Supply ALL required flags. The CLI will NOT prompt when stdin is not a TTY.
* `-q, --quiet` suppresses status output and implies `--json`.
* Exit `0` means success, `1` means error.
* Both success and error JSON go to **stdout**, parse it uniformly, then check for an `error` key and the exit code:
  ```json
  {"error":{"code":"...","message":"...","details":{}}}
  ```
* Destructive commands (e.g. `keys configs delete`) require `--yes` in non-TTY.
* Use env vars or flags in automation. Never rely on `azn auth login` from an agent.

## Authentication

Two credentials: `api_key` (required) and `user_token` (required for `/keys/*` reads, configs, and updates). Each credential resolves independently, in this order:

| Priority    | Source                                                                |
| ----------- | --------------------------------------------------------------------- |
| 1 (highest) | `--api-key <k>` / `--user-token <t>`                                  |
| 2           | `AZN_API_KEY` / `AZN_USER_TOKEN` env var                              |
| 3 (lowest)  | `~/.config/addresszen/credentials.json` (written by `azn auth login`) |

A missing api\_key returns error code `missing_api_key`. A missing user\_token on a command that needs it returns `missing_user_token`.

## Global flags

| Flag               | Description                          |
| ------------------ | ------------------------------------ |
| `--api-key <k>`    | Override API key for this invocation |
| `--user-token <t>` | Override user token                  |
| `--json`           | Force JSON (automatic in non-TTY)    |
| `-q, --quiet`      | Suppress status, implies `--json`    |
| `--base-url <url>` | Override API base (diagnostics only) |

## Commands

| Group                                                               | Subcommands                                                                            |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [`azn auth`](https://docs.addresszen.com/docs/cli/auth)             | `login`, `logout`, `whoami`                                                            |
| [`azn keys`](https://docs.addresszen.com/docs/cli/keys)             | `get`, `details`, `update`, `usage`, `logs`, `configs {list,get,create,update,delete}` |
| [`azn verify`](https://docs.addresszen.com/docs/cli/verify)         | Verify one US address, a file, or stdin                                                |
| [`azn email`](https://docs.addresszen.com/docs/cli/email)           | Validate one email, a file, or stdin                                                   |
| [`azn phone`](https://docs.addresszen.com/docs/cli/phone)           | Validate one phone number, a file, or stdin                                            |
| [`azn find` / `resolve`](https://docs.addresszen.com/docs/cli/find) | Autocomplete then resolve a suggestion id to a full address                            |
| `azn doctor`                                                        | Print environment info, verify connectivity, and check key usability                   |

Run `azn <command> --help` for full flags.

## Common pitfalls

* **`user_token` is separate from `api_key`.** `keys details`, `keys usage`, `keys logs`, `keys update`, and all `configs` commands require both.
* **`verify`, `email`, and `phone` cost paid lookups.**
* **Batch mode emits CSV** unless `--json` is passed; a single query always emits JSON.
* **`find` without a query in non-TTY errors.** Always pass a query when scripting.
* **`keys logs` emits raw CSV**, not JSON, and rejects `--json` / `-q` with `invalid_input`. Redirect to a file or pipe into your CSV tooling.
* **The credentials file is `0600`.** If your umask is unusual, `azn auth login` may fail with `write_failed`.

## Quick examples

```bash
# Verify a US address (JSON to stdout)
azn verify "1600 Amphitheatre Pkwy, Mountain View, CA 94043"

# Batch verify
cat addresses.txt | azn verify --stdin

# Validate an email or phone number
azn email "support@example.com"
azn phone "+12025550173" --carrier

# Batch validate emails to a CSV
cat emails.txt | azn email --stdin > emails.csv

# Find a specific address and resolve it
ID=$(azn find "1600 amphitheatre" | jq -r '.suggestions[0].id')
azn resolve "$ID"

# Inspect a key
azn keys details
```