namecheap

name

namecheap

description

Manage Namecheap domains and DNS records from the terminal with the `namecheap` CLI. Use this skill whenever the user mentions Namecheap, or asks anything about their domains, DNS records, nameservers, domain availability, domain expiry or renewals, WHOIS contacts, domain privacy, or email forwarding — including indirect asks like "point my domain at this server", "add the TXT record Google gave me to verify the domain", "which of my domains expire soon", "is thisname.com available", "hook my domain up to Vercel", or "why isn't my site resolving". Also use it when some other task (a deploy, an SSL or SPF/DKIM setup, a domain verification step) requires reading or editing a zone the user hosts at Namecheap. Reach for this instead of hand-rolling curl calls against the Namecheap API.

Namecheap CLI

namecheap is a zero-dependency CLI over the Namecheap API. It is installed globally, so it runs from any directory.

Source: https://github.com/adnanakil/ncheap-cli

Before anything else

namecheap config test

This confirms the API key, account username and whitelisted IP all line up. If it fails, fix that before running anything else — every other command will fail the same way. See Troubleshooting below.

Never ask the user to paste their API key into the conversation. It would persist in the transcript. Direct them to namecheap config init, which prompts with the input masked and writes to ~/.config/namecheap/config.json at mode 0600.

The safety rule that matters most

These commands change live infrastructure or spend the user's money:

Spends money	Changes live DNS / registration
domains create	dns add, dns remove, dns set, dns clear
domains renew	dns set-nameservers, dns use-namecheap
domains reactivate	dns set-email-forwarding
transfer create	domains set-contacts, domains lock
whoisguard renew

Every one of them takes --yes to skip its confirmation prompt. Do not pass --yes until the user has seen the specific change and approved it. Since you are running non-interactively, the prompt cannot reach the user — the CLI fails closed rather than guessing, which is the behaviour you want. Use that as the handoff point: show the user the plan, get a yes, then re-run with --yes.

A wrong DNS edit takes a production site down, and a wrong domains create is a non-refundable charge. Treat these like rm -rf, not like a query.

Reads are free and safe — run them freely: domains list, domains check, domains info, domains contacts, dns list, dns export, dns nameservers, dns email-forwarding, pricing, balance, whoisguard list, ssl list, transfer list|status.

Editing DNS

Namecheap has no per-record API. Its setHosts endpoint replaces the entire zone, so the CLI reads the current records, applies your change, and writes everything back. That makes every edit a potential whole-zone wipe if the read half goes wrong, which is why the workflow is always two steps:

# 1. Preview. Reads the zone, prints a diff, sends nothing.
namecheap dns add example.com --type A --host @ --value 203.0.113.10 --dry-run

# 2. Show that diff to the user. Once they approve:
namecheap dns add example.com --type A --host @ --value 203.0.113.10 --yes

Skipping the dry run to save a round trip is a bad trade. Run it every time.

Common edits:

namecheap dns list example.com                       # always look first
namecheap dns add example.com --type CNAME --host www --value target.com --replace --dry-run
namecheap dns add example.com --type TXT --host @ --value "v=spf1 include:_spf.google.com ~all" --dry-run
namecheap dns remove example.com --type TXT --value "stale-token" --dry-run

Things worth knowing before you construct a record:

• --host @ is the apex. A fully-qualified --host www.example.com is accepted and reduced to www against the zone.
• --replace removes existing records with the same host and type first. This is how you change an A record's address — without it you get two A records and round-robin DNS, which is rarely what anyone wants.
• CNAME and ALIAS are refused when one already exists for that host, since only one is legal. --replace is the way through.
• Adding an MX record promotes the zone's EmailType automatically. That field is easy to lose in a full-zone rewrite, and losing it silently breaks mail delivery — if a dry run shows EmailType: FWD → MX, that is the guard working, not a bug.
• dns clear deletes every record. dns set-nameservers moves the domain off Namecheap DNS entirely and existing records stop being served. Both need a clear, explicit request from the user.

For bulk edits, or before anything risky, take a backup:

namecheap dns export example.com --file zone-backup.json   # restore: dns set --file

Reading data

--json works on every command and emits every field the API returned, not just the table columns. Parse that rather than scraping tables.

namecheap domains list --json | jq -r '.[].Name'
namecheap domains list --expiring-in 45 --json | jq -r '.[] | select(.AutoRenew=="false") | .Name'
namecheap dns list example.com --json | jq '.records[] | select(.type=="MX")'
namecheap domains check brand.com brand.io brand.dev --available-only

domains list --json fields include Name, Expires (MM/DD/YYYY), AutoRenew, IsLocked, WhoisGuard, IsOurDNS. Note IsOurDNS — if it is "false" the domain uses custom nameservers and DNS record edits will not take effect.

Exit codes let you branch without parsing output: 0 success, 1 runtime error, 2 usage error, 3 the API returned an error. domains check also exits 1 when nothing queried is available.

Discovering the rest

The CLI is self-documenting, and reading its help is more reliable than guessing flags:

namecheap --help              # all command groups
namecheap dns --help          # commands in one group
namecheap domains create --help

There is also namecheap raw <command> --param K=V for any API endpoint the CLI does not wrap, printing JSON (or --xml for the untouched response).

Troubleshooting

Add --verbose to any command to see the exact request; the API key is redacted.

Symptom	Cause and fix
1011150 / 1011105 invalid IP	The user's public IP is not whitelisted, or their ISP rotated it. Run namecheap config detect-ip --save, then have them add that address at https://ap.www.namecheap.com/settings/tools/apiaccess/
1011102 invalid API key	Key is wrong, or API access is off in the account.
1011101 invalid API user	Sandbox and production are separate accounts with separate keys. Check whether --sandbox belongs.
2019166 / 2030166	Domain is not in this account.
DNS edit reports success, nothing changes	Domain uses custom nameservers. Check namecheap dns nameservers <domain>.
Renewals fail with insufficient funds	Check namecheap balance — autorenew silently does nothing at $0.

Sandbox is available for testing destructive flows without spending money, but it is a separate Namecheap account with its own key: namecheap --profile sandbox domains list.