@ingram-tech/domains

Command-line client for Ingram Domains — the domain registrar built for AI agents.

npm i -g @ingram-tech/domains

Authentication

Mint an API token at https://domains.ingram.tech/settings/tokens, then:

domains login --token ingram_live_…
# or
INGRAM_API_TOKEN=ingram_live_… domains ls

Credentials are stored at ~/.config/domains/credentials.toml with mode 0600.

Quick reference

# Read (free)
domains check example                    # availability across popular TLDs
domains check example.com                # one specific domain
domains ls                               # your portfolio
domains info example.com                 # registry detail
domains dns ls example.com               # zone records

# Write — spending (always agent-safe)
domains register example.com --confirm-price 9.20    # exact total price
domains register example.com --max-price 10.00       # ceiling, fetches live price
domains renew    example.com --confirm-price 9.20

# Write — transfers
domains transfer    example.com --auth-code ABC123   # inbound
domains transfer-out example.com                     # request EPP code (emailed to registrant)

# Write — destructive (always two-flag confirm)
domains rm example.com --confirm example.com --yes              # END_OF_PERIOD (default)
domains rm example.com --confirm example.com --yes --now        # immediate

# DNS
domains dns add example.com A     www 1.2.3.4
domains dns add example.com TXT   @   "v=spf1 …"  --ttl 3600
domains dns rm  example.com A     www 1.2.3.4

# Auth
domains login   --token ingram_live_…         # paste a token
domains login   --token-stdin < /run/secrets/token
domains whoami
domains logout

Output format

Auto-detects TTY: pretty tables when interactive, JSON to stdout when piped. Force JSON with --json. Stderr is reserved for human-facing logs (success ✓, errors ✗, hints); stdout is the machine-readable channel.

Exit codes

| Code | Meaning | |------|---------| | 0 | success | | 1 | generic runtime error | | 2 | usage error (missing/invalid flag) — agents should not retry | | 3 | authentication problem — re-auth | | 4 | not found | | 5 | price changed (confirm_price mismatch, HTTP 409) — re-quote | | 6 | rate limited — back off | | 7 | registry-side failure |

Idempotency

Every mutation auto-generates an Idempotency-Key UUIDv4. Re-running the exact same command (with the same key) is safe — the server replays the cached response with Idempotent-Replay: true for ~24h. Override with --idempotency-key <value> if you want to manage keys yourself.

Profiles

Multiple credential profiles via --profile <name> or INGRAM_PROFILE=<name>. Each profile has its own token and (optionally) api_base for self-hosted instances.

Environment

• INGRAM_API_TOKEN — token (highest precedence after --token)
• INGRAM_API_BASE — override the API base URL
• INGRAM_PROFILE — pick a non-default profile
• INGRAM_AGENT=1 / CLAUDECODE=1 / CI=true — force non-interactive mode
• XDG_CONFIG_HOME — alternative config root
• NO_COLOR — disable ANSI colors

License

MIT