namecheap-cli

A full-coverage command line interface and Python client for the Namecheap API — domains, DNS, SSL certificates, transfers, domain privacy, account and address management.

• 100% API coverage. Every one of the 59 documented API methods is a first-class subcommand, enforced by a test that diffs the implementation against Namecheap's published method inventory. Anything Namecheap ships later is still reachable through the raw api passthrough.
• Zero dependencies. Pure Python standard library. pip install and go.
• Safe by default. Operations that charge money or overwrite state require confirmation (or an explicit --yes). The dns add/dns rm helpers wrap Namecheap's all-or-nothing setHosts with a read-modify-write cycle and a diff preview, so adding one record never nukes your zone.
• Sandbox aware. One flag (--sandbox) switches to Namecheap's test environment with its own credentials.
• Scriptable. JSON output everywhere, raw XML on request, and an importable NamecheapClient for Python use.

$ namecheap domains list
$ namecheap domains check coolidea.com,coolidea.io
$ namecheap dns add example.com --type A --name @ --value 76.76.21.21
$ namecheap dns get-hosts example.com
$ namecheap ssl list
$ namecheap users balances

Install

pipx install git+https://github.com/Pvragon/namecheap-cli   # recommended
# or:
pip install git+https://github.com/Pvragon/namecheap-cli
# or from a clone:
git clone https://github.com/Pvragon/namecheap-cli && cd namecheap-cli
pip install .

Requires Python 3.10+. No runtime dependencies.

Namecheap API prerequisites

1. Eligibility — Namecheap enables API access for accounts with 20+ domains, a $50+ balance, or $50+ spent in the last two years.
2. Enable API access — namecheap.com → Profile → Tools → Business & Dev Tools → Namecheap API Access.
3. Whitelist your IP — API calls only work from whitelisted IPv4 addresses (up to 10). Check yours with curl https://api.ipify.org.
4. Sandbox (optional but recommended) — create a free account at sandbox.namecheap.com, enable API access there too, and test with play money before touching production.

Credentials

The client resolves credentials in this order (first hit wins):

1. --api-user / --api-key flags (or NamecheapClient(...) arguments)
2. Environment variables
3. .env file at $NAMECHEAP_ENV_FILE
4. ~/.config/namecheap/.env (recommended)
5. ~/.namecheap.env
6. ./.env

mkdir -p ~/.config/namecheap
cat > ~/.config/namecheap/.env <<'EOF'
NAMECHEAP_API_USER=your_username          # your namecheap.com LOGIN USERNAME (not email)
NAMECHEAP_API_KEY=your_production_api_key
NAMECHEAP_SANDBOX_API_USER=your_sandbox_username
NAMECHEAP_SANDBOX_API_KEY=your_sandbox_api_key
EOF
chmod 600 ~/.config/namecheap/.env

Optional settings:

Variable	Purpose
NAMECHEAP_USERNAME / NAMECHEAP_SANDBOX_USERNAME	UserName API param when it differs from the API user (reseller setups)
NAMECHEAP_CLIENT_IP	Skip public-IP auto-detection and send this whitelisted IP
NAMECHEAP_SANDBOX=1	Default every invocation to the sandbox

Verify with namecheap config (prints resolution status, never secrets).

Usage

Run namecheap commands for the full surface, or see docs/commands.md for the complete generated reference.

Domains

namecheap domains list --search-term example --sort-by EXPIREDATE
namecheap domains check coolidea.com,coolidea.io,coolidea.dev
namecheap domains info example.com
namecheap domains renew example.com --years 1        # asks to confirm ($)
namecheap domains get-lock example.com

Registering a domain (domains create) takes the registrant/tech/admin/ aux-billing contact blocks required by the API — see namecheap domains create --help.

DNS

namecheap dns get-hosts example.com
namecheap dns add example.com --type TXT --name @ --value "v=spf1 -all"
namecheap dns add example.com --type A --name @ --value 9.9.9.9 --replace
namecheap dns rm  example.com --name www --type CNAME
namecheap dns export example.com -o zone.json
namecheap dns import example.com -f zone.json

dns add/rm/import show a +/- diff and ask before writing (--dry-run to preview, --yes to skip the prompt). The low-level dns set-hosts (replace the whole zone in one call) is also available.

Everything else

namecheap ssl list
namecheap ssl activate 1234567 --csr "$(cat server.csr)" --dnsdc-validation true
namecheap transfer create example.net --years 1 --epp-code ABC123
namecheap privacy list
namecheap address list
namecheap users pricing --product-type DOMAIN --product-name COM --action-name REGISTER

Raw passthrough

Any command, any parameter, no CLI mapping needed:

namecheap api namecheap.domains.getList PageSize=100
namecheap api some.future.command Foo=bar

Output modes

Flag	Output
(default)	Parsed CommandResponse as JSON
--full	Entire ApiResponse envelope as JSON
--raw	Untouched XML from the API
--debug	Request URL (API key masked) on stderr

Exit codes: 0 success, 1 API/network error, 2 configuration/usage error, 3 declined confirmation.

Python library

from namecheap_cli import NamecheapClient

client = NamecheapClient()            # or NamecheapClient(sandbox=True)
domains = client.call("namecheap.domains.getList", {"PageSize": 100})
for d in domains["DomainGetListResult"]["Domain"]:
    print(d["Name"], d["Expires"])

client.call() returns the parsed CommandResponse and raises ApiError (with the API's numbered errors) on failure. call_envelope() returns the full envelope; call_raw() returns XML text.

Development

pip install -e ".[dev]"
pytest                      # unit tests (no network)
pytest -m live tests/integration/   # opt-in, needs sandbox credentials
python scripts/gen_docs.py  # regenerate docs/commands.md from the spec

The command surface lives in one declarative table (src/namecheap_cli/spec.py); tests/test_spec.py fails if it ever drifts from Namecheap's documented method list.

Rate limits

Namecheap allows 50 requests/minute, 700/hour, 8000/day per key.

License

MIT © Pvragon