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

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:

  {"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	login, logout, whoami
azn keys	get, details, update, usage, logs, configs {list,get,create,update,delete}
azn verify	Verify one US address, a file, or stdin
azn email	Validate one email, a file, or stdin
azn phone	Validate one phone number, a file, or stdin
azn find / resolve	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

# 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