Namecheap CLI

A cli for managing Namecheap domains and DNS via the command line.

A powerful command-line interface for managing Namecheap domains, DNS records, nameservers, WhoisGuard privacy protection, and more. Built with Bun and TypeScript.

Installation

Global Install (Recommended)

# Using npm
npm install -g @helgesverre/namecheap-cli

# Using Yarn
yarn global add @helgesverre/namecheap-cli

# Using pnpm
pnpm add -g @helgesverre/namecheap-cli

# Using Bun
bun install -g @helgesverre/namecheap-cli

Run Without Installing

# Using npx
npx @helgesverre/namecheap-cli domains list

# Using bunx
bunx @helgesverre/namecheap-cli domains list

Requirements

• Node.js 18.0.0 or higher (or Bun runtime)

Quick Start

1. Get API Credentials

1. Log in to your Namecheap account
2. Go to Profile > Tools > API Access
3. Enable API access (requires account balance > $50 or domains > 20)
4. Whitelist your IP address
5. Copy your API key

2. Authenticate

namecheap auth login

You'll be prompted for:

• Username: Your Namecheap username
• API Key: From the API Access page
• Client IP: Your whitelisted IP address

3. Start Using

# List your domains
namecheap domains list

# Check domain availability
namecheap domains check example.com

# View DNS records
namecheap dns list example.com

Commands

Authentication

namecheap auth login     # Authenticate with API
namecheap auth logout    # Clear credentials
namecheap auth status    # Check auth status

Domains

namecheap domains list              # List all domains
namecheap domains info <domain>     # Get domain details
namecheap domains check <domain>    # Check availability
namecheap domains lock <domain>     # Enable registrar lock
namecheap domains unlock <domain>   # Disable registrar lock
namecheap domains register <domain> # Register new domain
namecheap domains renew <domain>    # Renew domain
namecheap domains contacts <domain> # Manage contacts

DNS Records

namecheap dns list <domain>    # List DNS records
namecheap dns add <domain>     # Add record (interactive)
namecheap dns set <domain>     # Update record
namecheap dns rm <domain>      # Delete record

# Email forwarding
namecheap dns email list <domain>        # List forwards
namecheap dns email add <domain>         # Add forward
namecheap dns email rm <domain> <mailbox># Remove forward

Nameservers

namecheap ns list <domain>           # List nameservers
namecheap ns set <domain> <ns1> <ns2># Set custom nameservers
namecheap ns reset <domain>          # Reset to Namecheap defaults

# Child nameservers (glue records)
namecheap ns create <domain> <ns> <ip>  # Create
namecheap ns delete <domain> <ns>       # Delete
namecheap ns info <domain> <ns>         # Get info
namecheap ns update <domain> <ns> <ip>  # Update IP

Account

namecheap users balances                 # Show account balance
namecheap users pricing register com     # Get pricing

WhoisGuard (Privacy)

namecheap whoisguard list                     # List subscriptions
namecheap whoisguard enable <domain>          # Enable privacy
namecheap whoisguard disable <domain>         # Disable privacy
namecheap whoisguard allot <id> <domain>      # Assign to domain
namecheap whoisguard unallot <id>             # Remove from domain
namecheap whoisguard renew <id>               # Renew subscription

Configuration

namecheap config list              # Show config
namecheap config get <key>         # Get value
namecheap config set <key> <value> # Set value
namecheap config path              # Show config file path

Config Options:

• sandbox - Use sandbox API (true/false)
• output - Default output format (table/json)

Sandbox Mode

For testing without affecting production:

# Enable sandbox mode
namecheap config set sandbox true

# Authenticate with sandbox credentials
namecheap auth login

# Test commands (uses sandbox API)
namecheap domains list

Get sandbox credentials at: https://www.sandbox.namecheap.com

Shell Completions

Enable tab completion for your shell:

# Automatic install (auto-detects your shell)
namecheap completions install

# Or install for a specific shell
namecheap completions install --shell bash
namecheap completions install --shell zsh
namecheap completions install --shell fish

# macOS with Homebrew: install to Homebrew's completion directories
namecheap completions install --homebrew

# Manual setup (alternative)
# Bash - Add to ~/.bashrc
eval "$(namecheap completions bash)"

# Zsh - Add to ~/.zshrc
eval "$(namecheap completions zsh)"

# Fish - Add to ~/.config/fish/config.fish
namecheap completions fish | source

To uninstall completions:

namecheap completions uninstall

Output Formats

All commands support JSON output:

# Table output (default)
namecheap domains list

# JSON output
namecheap domains list --json

# Set default format
namecheap config set output json

Troubleshooting

Common Errors

| Error | Solution | |-----------------------|----------------------------------------------------| | "Not authenticated" | Run namecheap auth login | | "IP not whitelisted" | Add your IP at Namecheap > Profile > API Access | | "API access disabled" | Enable at Namecheap > Profile > Tools > API Access | | "Invalid API Key" | Re-run namecheap auth login with correct key | | "Domain not found" | Check domain name and ownership |

Check Status

# Verify authentication
namecheap auth status

# Check current config
namecheap config list

API Requirements

Before using this CLI, ensure:

1. API Access Enabled - Go to your Namecheap account → Profile → Tools → API Access
2. IP Whitelisted - Add your current IP address to the whitelist
3. Account Balance - Maintain balance > $50 OR own 20+ domains
4. API Key - Copy your API key from the API Access page

Development

Setup

# Clone the repository
git clone https://github.com/HelgeSverre/namecheap-cli.git
cd namecheap-cli

# Install dependencies
bun install

# Run in development
bun run dev

# Build for production
bun run build

Project Structure

namecheap-cli/
├── src/
│   ├── commands/       # Command implementations
│   │   ├── auth/       # Authentication commands
│   │   ├── config/     # Configuration commands
│   │   ├── dns/        # DNS management
│   │   ├── domains/    # Domain management
│   │   ├── ns/         # Nameserver management
│   │   ├── users/      # Account info
│   │   └── whoisguard/ # Privacy protection
│   ├── lib/            # Core libraries
│   │   ├── api/        # API client and parsers
│   │   ├── config.ts   # Configuration management
│   │   └── output.ts   # Output formatting
│   └── utils/          # Utility functions
├── tests/              # Test suite
└── docs/               # Documentation

Testing

This project uses Bun's built-in test runner for testing.

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run tests with coverage
bun test --coverage

# Run specific test file
bun test tests/lib/api/client.test.ts

# Run tests matching a pattern
bun test --filter "domains"

Test Structure

tests/
├── commands/           # Command handler tests
│   ├── auth.test.ts
│   ├── config.test.ts
│   ├── dns.test.ts
│   ├── domains.test.ts
│   ├── ns.test.ts
│   ├── users.test.ts
│   └── whoisguard.test.ts
├── lib/               # Library/utility tests
│   ├── api/
│   │   ├── client.test.ts
│   │   ├── dns.test.ts
│   │   ├── domains.test.ts
│   │   └── parser.test.ts
│   ├── config.test.ts
│   └── output.test.ts
├── utils/
│   └── errors.test.ts
├── fixtures/          # XML test fixtures
│   └── *.xml
└── helpers/           # Test utilities
    └── command-test-utils.ts

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Code Quality

This project uses strict TypeScript, ESLint, and Prettier for code quality.

# Run all checks
bun run check

# Auto-fix issues
bun run fix

# Individual commands
bun run typecheck     # TypeScript type check
bun run lint          # ESLint
bun run lint:fix      # ESLint with auto-fix
bun run format        # Prettier format
bun run format:check  # Prettier check

Pull Request Process

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests for new functionality
5. Run checks: bun run check && bun test
6. Commit your changes with descriptive messages
7. Push to your fork and submit a pull request

See CLAUDE.md for detailed development guidelines.

Changelog

See CHANGELOG.md for release history and changes.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Acknowledgments

• Built with Commander.js
• Powered by Bun runtime
• Uses Namecheap API

License

MIT