# 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 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

# Transfers
domains transfer     example.com --auth-code ABC123
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

# 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
```

## 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 mutation auto-generates an `Idempotency-Key` (override with
`--idempotency-key`), so re-running an identical command is safe. 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).