# 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[​](#installation "Direct link to Installation")

```
npm install -g @addresszen/cli

azn --version
```

## Agent protocol[​](#agent-protocol "Direct link to 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:
  <!-- -->
  ```
  {"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[​](#authentication "Direct link to 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[​](#global-flags "Direct link to 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[​](#commands "Direct link to 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[​](#common-pitfalls "Direct link to 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[​](#quick-examples "Direct link to Quick examples")

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