https://docs.addresszen.com/assets/js/df7c001f.db7ab841.js

1"use strict";(globalThis.webpackChunk_atlas_docs_zen=globalThis.webpackChunk_atlas_docs_zen||[]).push([[5342],{4056(e,s,n){n.d(s,{R:()=>l,x:()=>c});var i=n(2155);const d={},r=i.createContext(d);function l(e){const s=i.useContext(r);return i.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function c(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(d):e.components||d:l(e.components),i.createElement(r.Provider,{value:s},e.children)}},4522(e,s,n){n.r(s),n.d(s,{assets:()=>t,contentTitle:()=>c,default:()=>h,frontMatter:()=>l,metadata:()=>i,toc:()=>o});const i=JSON.parse('{"id":"cli/cli","title":"AddressZen CLI","description":"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.","source":"@site/docs/cli/cli.mdx","sourceDirName":"cli","slug":"/cli","permalink":"/docs/cli","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"title":"AddressZen CLI","sidebar_label":"Overview","sidebar_position":1,"slug":"/cli"},"sidebar":"cli","next":{"title":"auth","permalink":"/docs/cli/auth"}}');var d=n(5723),r=n(4056);const l={title:"AddressZen CLI",sidebar_label:"Overview",sidebar_position:1,slug:"/cli"},c=void 0,t={},o=[{value:"Installation",id:"installation",level:2},{value:"Agent protocol",id:"agent-protocol",level:2},{value:"Authentication",id:"authentication",level:2},{value:"Global flags",id:"global-flags",level:2},{value:"Commands",id:"commands",level:2},{value:"Common pitfalls",id:"common-pitfalls",level:2},{value:"Quick examples",id:"quick-examples",level:2}];function a(e){const s={a:"a",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,d.jsxs)(d.Fragment,{children:[(0,d.jsxs)(s.p,{children:[(0,d.jsx)(s.code,{children:"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."]}),"\n",(0,d.jsx)(s.p,{children:"It is built for LLM agents (Claude Code, Cursor, Codex) and CI/CD pipelines, and works equally well from a terminal."}),"\n",(0,d.jsx)(s.h2,{id:"installation",children:"Installation"}),"\n",(0,d.jsx)(s.p,{children:"Requires Node.js 22 or later."}),"\n",(0,d.jsx)(s.pre,{children:(0,d.jsx)(s.code,{className:"language-bash",children:"npm install -g @addresszen/cli\nazn --version\n"})}),"\n",(0,d.jsx)(s.h2,{id:"agent-protocol",children:"Agent protocol"}),"\n",(0,d.jsxs)(s.p,{children:["The CLI auto-detects non-TTY environments and emits JSON; no ",(0,d.jsx)(s.code,{children:"--json"})," flag needed when piping or running headless."]}),"\n",(0,d.jsxs)(s.ul,{children:["\n",(0,d.jsx)(s.li,{children:"Supply ALL required flags. The CLI will NOT prompt when stdin is not a TTY."}),"\n",(0,d.jsxs)(s.li,{children:[(0,d.jsx)(s.code,{children:"-q, --quiet"})," suppresses status output and implies ",(0,d.jsx)(s.code,{children:"--json"}),"."]}),"\n",(0,d.jsxs)(s.li,{children:["Exit ",(0,d.jsx)(s.code,{children:"0"})," means success, ",(0,d.jsx)(s.code,{children:"1"})," means error."]}),"\n",(0,d.jsxs)(s.li,{children:["Both success and error JSON go to ",(0,d.jsx)(s.strong,{children:"stdout"}),", parse it uniformly, then check for an ",(0,d.jsx)(s.code,{children:"error"})," key and the exit code:","\n",(0,d.jsx)(s.pre,{children:(0,d.jsx)(s.code,{className:"language-json",children:'{"error":{"code":"...","message":"...","details":{}}}\n'})}),"\n"]}),"\n",(0,d.jsxs)(s.li,{children:["Destructive commands (e.g. ",(0,d.jsx)(s.code,{children:"keys configs delete"}),") require ",(0,d.jsx)(s.code,{children:"--yes"})," in non-TTY."]}),"\n",(0,d.jsxs)(s.li,{children:["Use env vars or flags in automation. Never rely on ",(0,d.jsx)(s.code,{children:"azn auth login"})," from an agent."]}),"\n"]}),"\n",(0,d.jsx)(s.h2,{id:"authentication",children:"Authentication"}),"\n",(0,d.jsxs)(s.p,{children:["Two credentials: ",(0,d.jsx)(s.code,{children:"api_key"})," (required) and ",(0,d.jsx)(s.code,{children:"user_token"})," (required for ",(0,d.jsx)(s.code,{children:"/keys/*"})," reads, configs, and updates). Each credential resolves independently, in this order:"]}),"\n",(0,d.jsxs)(s.table,{children:[(0,d.jsx)(s.thead,{children:(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.th,{children:"Priority"}),(0,d.jsx)(s.th,{children:"Source"})]})}),(0,d.jsxs)(s.tbody,{children:[(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:"1 (highest)"}),(0,d.jsxs)(s.td,{children:[(0,d.jsx)(s.code,{children:"--api-key <k>"})," / ",(0,d.jsx)(s.code,{children:"--user-token <t>"})]})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:"2"}),(0,d.jsxs)(s.td,{children:[(0,d.jsx)(s.code,{children:"AZN_API_KEY"})," / ",(0,d.jsx)(s.code,{children:"AZN_USER_TOKEN"})," env var"]})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:"3 (lowest)"}),(0,d.jsxs)(s.td,{children:[(0,d.jsx)(s.code,{children:"~/.config/addresszen/credentials.json"})," (written by ",(0,d.jsx)(s.code,{children:"azn auth login"}),")"]})]})]})]}),"\n",(0,d.jsxs)(s.p,{children:["A missing api_key returns error code ",(0,d.jsx)(s.code,{children:"missing_api_key"}),". A missing user_token on a command that needs it returns ",(0,d.jsx)(s.code,{children:"missing_user_token"}),"."]}),"\n",(0,d.jsx)(s.h2,{id:"global-flags",children:"Global flags"}),"\n",(0,d.jsxs)(s.table,{children:[(0,d.jsx)(s.thead,{children:(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.th,{children:"Flag"}),(0,d.jsx)(s.th,{children:"Description"})]})}),(0,d.jsxs)(s.tbody,{children:[(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"--api-key <k>"})}),(0,d.jsx)(s.td,{children:"Override API key for this invocation"})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"--user-token <t>"})}),(0,d.jsx)(s.td,{children:"Override user token"})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"--json"})}),(0,d.jsx)(s.td,{children:"Force JSON (automatic in non-TTY)"})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"-q, --quiet"})}),(0,d.jsxs)(s.td,{children:["Suppress status, implies ",(0,d.jsx)(s.code,{children:"--json"})]})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"--base-url <url>"})}),(0,d.jsx)(s.td,{children:"Override API base (diagnostics only)"})]})]})]}),"\n",(0,d.jsx)(s.h2,{id:"commands",children:"Commands"}),"\n",(0,d.jsxs)(s.table,{children:[(0,d.jsx)(s.thead,{children:(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.th,{children:"Group"}),(0,d.jsx)(s.th,{children:"Subcommands"})]})}),(0,d.jsxs)(s.tbody,{children:[(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.a,{href:"https://docs.addresszen.com/docs/cli/auth",children:(0,d.jsx)(s.code,{children:"azn auth"})})}),(0,d.jsxs)(s.td,{children:[(0,d.jsx)(s.code,{children:"login"}),", ",(0,d.jsx)(s.code,{children:"logout"}),", ",(0,d.jsx)(s.code,{children:"whoami"})]})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.a,{href:"https://docs.addresszen.com/docs/cli/keys",children:(0,d.jsx)(s.code,{children:"azn keys"})})}),(0,d.jsxs)(s.td,{children:[(0,d.jsx)(s.code,{children:"get"}),", ",(0,d.jsx)(s.code,{children:"details"}),", ",(0,d.jsx)(s.code,{children:"update"}),", ",(0,d.jsx)(s.code,{children:"usage"}),", ",(0,d.jsx)(s.code,{children:"logs"}),", ",(0,d.jsx)(s.code,{children:"configs {list,get,create,update,delete}"})]})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.a,{href:"https://docs.addresszen.com/docs/cli/verify",children:(0,d.jsx)(s.code,{children:"azn verify"})})}),(0,d.jsx)(s.td,{children:"Verify one US address, a file, or stdin"})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.a,{href:"https://docs.addresszen.com/docs/cli/email",children:(0,d.jsx)(s.code,{children:"azn email"})})}),(0,d.jsx)(s.td,{children:"Validate one email, a file, or stdin"})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.a,{href:"https://docs.addresszen.com/docs/cli/phone",children:(0,d.jsx)(s.code,{children:"azn ph

1one"})})}),(0,d.jsx)(s.td,{children:"Validate one phone number, a file, or stdin"})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsxs)(s.a,{href:"https://docs.addresszen.com/docs/cli/find",children:[(0,d.jsx)(s.code,{children:"azn find"})," / ",(0,d.jsx)(s.code,{children:"resolve"})]})}),(0,d.jsx)(s.td,{children:"Autocomplete then resolve a suggestion id to a full address"})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"azn doctor"})}),(0,d.jsx)(s.td,{children:"Print environment info, verify connectivity, and check key usability"})]})]})]}),"\n",(0,d.jsxs)(s.p,{children:["Run ",(0,d.jsx)(s.code,{children:"azn <command> --help"})," for full flags."]}),"\n",(0,d.jsx)(s.h2,{id:"common-pitfalls",children:"Common pitfalls"}),"\n",(0,d.jsxs)(s.ul,{children:["\n",(0,d.jsxs)(s.li,{children:[(0,d.jsxs)(s.strong,{children:[(0,d.jsx)(s.code,{children:"user_token"})," is separate from ",(0,d.jsx)(s.code,{children:"api_key"}),"."]})," ",(0,d.jsx)(s.code,{children:"keys details"}),", ",(0,d.jsx)(s.code,{children:"keys usage"}),", ",(0,d.jsx)(s.code,{children:"keys logs"}),", ",(0,d.jsx)(s.code,{children:"keys update"}),", and all ",(0,d.jsx)(s.code,{children:"configs"})," commands require both."]}),"\n",(0,d.jsx)(s.li,{children:(0,d.jsxs)(s.strong,{children:[(0,d.jsx)(s.code,{children:"verify"}),", ",(0,d.jsx)(s.code,{children:"email"}),", and ",(0,d.jsx)(s.code,{children:"phone"})," cost paid lookups."]})}),"\n",(0,d.jsxs)(s.li,{children:[(0,d.jsx)(s.strong,{children:"Batch mode emits CSV"})," unless ",(0,d.jsx)(s.code,{children:"--json"})," is passed; a single query always emits JSON."]}),"\n",(0,d.jsxs)(s.li,{children:[(0,d.jsxs)(s.strong,{children:[(0,d.jsx)(s.code,{children:"find"})," without a query in non-TTY errors."]})," Always pass a query when scripting."]}),"\n",(0,d.jsxs)(s.li,{children:[(0,d.jsxs)(s.strong,{children:[(0,d.jsx)(s.code,{children:"keys logs"})," emits raw CSV"]}),", not JSON, and rejects ",(0,d.jsx)(s.code,{children:"--json"})," / ",(0,d.jsx)(s.code,{children:"-q"})," with ",(0,d.jsx)(s.code,{children:"invalid_input"}),". Redirect to a file or pipe into your CSV tooling."]}),"\n",(0,d.jsxs)(s.li,{children:[(0,d.jsxs)(s.strong,{children:["The credentials file is ",(0,d.jsx)(s.code,{children:"0600"}),"."]})," If your umask is unusual, ",(0,d.jsx)(s.code,{children:"azn auth login"})," may fail with ",(0,d.jsx)(s.code,{children:"write_failed"}),"."]}),"\n"]}),"\n",(0,d.jsx)(s.h2,{id:"quick-examples",children:"Quick examples"}),"\n",(0,d.jsx)(s.pre,{children:(0,d.jsx)(s.code,{className:"language-bash",children:'# Verify a US address (JSON to stdout)\nazn verify "1600 Amphitheatre Pkwy, Mountain Vie

1w, CA 94043"\n\n# Batch verify\ncat addresses.txt | azn verify --stdin\n\n# Validate an email or phone number\nazn email "[email protected]"\nazn phone "+12025550173" --carrier\n\n# Batch validate emails to a CSV\ncat emails.txt | azn email --stdin > emails.csv\n\n# Find a specific address and resolve it\nID=$(azn find "1600 amphitheatre" | jq -r \'.suggestions[0].id\')\nazn resolve "$ID"\n\n# Inspect a key\nazn keys details\n'})})]})}function h(e={}){const{wrapper:s}={...(0,r.R)(),...e.components};return s?(0,d.jsx)(s,{...e,children:(0,d.jsx)(a,{...e})}):a(e)}}}]);