# CLI

```bash
npm i -g @ingram-tech/domains
domains login --token ingram_live_…      # or INGRAM_API_TOKEN=…
```

The CLI wraps the [REST API](/docs/api) 1:1 — same contract, same
[error semantics](/docs/errors) — with agent-safe defaults: spending verbs
refuse to run without `--confirm-price <total>` or `--max-price <ceiling>`,
destructive verbs require `--confirm <domain> --yes`, and it never prompts in
non-TTY contexts.

## Commands

```bash
# Read (free)
domains check example              # availability across popular TLDs
domains check example.com          # one domain
domains ls                         # portfolio
domains info example.com           # registry detail
domains settings example.com       # toggles + renewal state (next charge, price)
domains dns ls example.com         # zone records

# Spend (always explicit)
domains register example.com --confirm-price 18.00
domains register example.com --max-price 20.00     # fetches live price, refuses above ceiling
domains renew    example.com --confirm-price 18.00
domains renew    example.com --max-price 60.00 --duration 3

# Transfers (paid: same price guard)
domains transfer     example.com --auth-code ABC123 --confirm-price 18.00   # --dns auto|keep|ingram (DNS records carry over)
domains transfer-out example.com                   # emails the EPP code to the registrant

# Destructive (two-flag confirm)
domains rm example.com --confirm example.com --yes         # end of period
domains rm example.com --confirm example.com --yes --now   # immediate

# Settings (on|off per toggle)
domains settings example.com --registrar-lock on
domains settings example.com --whois-privacy off --dnssec on
domains settings example.com --auto-renew on --yes   # --yes only needed when it charges now

# DNS
domains dns add example.com A   www 203.0.113.10
domains dns add example.com TXT @  "v=spf1 …" --ttl 3600
domains dns rm  example.com A   www 203.0.113.10
domains dns import example.com example.com.zone   # BIND zone file export; --move-here, --replace
```

## Output

TTY → pretty tables; piped → JSON on stdout (`--json` forces it). Stderr
carries the human log; stdout is the machine channel — safe to parse.

## Exit codes

| Code | Meaning | Agent behaviour |
|---|---|---|
| 0 | success | — |
| 1 | generic runtime error | inspect |
| 2 | usage error | don't retry |
| 3 | authentication problem | re-auth |
| 4 | not found | — |
| 5 | price changed | re-quote, re-confirm |
| 6 | rate limited | back off |
| 7 | registry-side failure | inspect message |

## Idempotency & environment

Every mutating command sends an `Idempotency-Key`, freshly generated per run
— so re-running a command is a **new operation**. To make a retry safe, pass
`--idempotency-key <value>` and reuse it: the same key with the same request
replays the first successful response for ~24h, the same key with a different
request is a `409 idempotency_key_reused`, and failed requests aren't cached
(see [errors](/docs/errors)). Relevant
environment: `INGRAM_API_TOKEN`, `INGRAM_API_BASE`, `INGRAM_PROFILE`
(multiple credential profiles), `NO_COLOR`, and `INGRAM_AGENT=1` /
`CI=true` to force non-interactive mode. Credentials live at
`~/.config/domains/credentials.toml` (mode 0600).