@ideal-postcodes/cli

The official CLI for Ideal Postcodes — idpc.

Built for LLM agents (Claude Code, Cursor, Codex) and CI/CD pipelines; usable from a terminal too.

Install

npm install -g @ideal-postcodes/cli
idpc --version

Authenticate

Two credentials — api_key (public) and user_token (private; needed for key reads, usage, logs, and configs).

idpc auth login --api-key ak_xxx --user-token ut_xxx

Resolution order per credential: --api-key/--user-token flag → IDPC_API_KEY/IDPC_USER_TOKEN env var → active profile in ~/.config/ideal-postcodes/credentials.json.

Quickstart

# Inspect a key
idpc keys details

# Cleanse an address
idpc cleanse "10 downing street, london"

# Batch cleanse from a file
cat addresses.txt | idpc cleanse --stdin > cleaned.json

# Autocomplete then resolve
idpc find "10 downing" --resolve

# Manage allowed URLs
idpc keys configs create web --allowed-urls https://example.com,https://www.example.com

# Diagnose your setup
idpc doctor

Agent protocol

• Non-TTY (pipe, CI, agent run): output is always JSON; no prompts, no spinners.
• Exit 0 on success, 1 on error. Both success and error JSON go to stdout so a single pipe (idpc … | jq) parses uniformly; the exit code signals failure. Error shape: {"error":{"code":"...","message":"..."}}.
• Destructive commands require --yes in non-TTY.

The bundled skills/idpc-cli/ teaches agents the flag contract and common gotchas.

Commands

| Group | Subcommands | |---|---| | idpc auth | login, logout, whoami | | idpc keys | get, details, update, usage, logs, configs {list,get,create,update,delete} | | idpc cleanse | Cleanse one address, a file, or stdin | | idpc find | Autocomplete (interactive in TTY, JSON in non-TTY) | | idpc resolve | Resolve a suggestion id to a full address | | idpc doctor | Env + connectivity check |

Run idpc <command> --help for full flags.

Source

Built in the atlas monorepo.