Configuration

Configuration

Overview

Namecheap DNS Manager supports multiple accounts, allowing you to manage domains across different Namecheap accounts from a single tool.

💡 Tip: You can switch between accounts easily or use a specific account for individual commands.

---

Configuration File Locations

The tool automatically detects configuration files in this priority order:

Priority	Location	Use Case
1	./configs/.namecheap-dns.yaml	🛠️ Development (project directory)
2	~/.namecheap-dns.yaml	🏠 Production (home directory)
3	--config /path/to/config.yaml	🎯 Custom location (via flag)

Note: The first found config file is used. Project directory config takes precedence.

Configuration File Structure

View complete configuration example

accounts:
  default:
    username: "your-namecheap-username"
    api_user: "your-api-username"
    api_key: "your-api-key-here"
    client_ip: "your.public.ip.address"
    use_sandbox: false
    description: "My main account"

  work:
    username: "work-username"
    api_user: "work-api-username"
    api_key: "work-api-key"
    client_ip: "your.public.ip.address"
    use_sandbox: false
    description: "Work account"

  sandbox:
    username: "sandbox-username"
    api_user: "sandbox-api-user"
    api_key: "sandbox-api-key"
    client_ip: "your.public.ip.address"
    use_sandbox: true
    description: "Testing environment"

current_account: "default"

Configuration Fields

Field	Required	Description	Example
username	✅ Yes	Namecheap account username	"myusername"
api_user	✅ Yes	API username (may differ from username)	"myapiuser"
api_key	✅ Yes	API key from Namecheap	"abc123..."
client_ip	✅ Yes	Your public IP address	"203.0.113.1"
use_sandbox	❌ No	Use sandbox environment (default: false)	true or false
description	❌ No	Account description	"My main account"

Getting Your API Credentials

1. Log in to your Namecheap account
2. Go to Profile → Tools → API Access
3. Enable API access
4. Note your:
   • API User: Your API username
   • API Key: Your API key
   • Whitelisted IP: Your public IP address

Setting Up Your First Account

Interactive Setup

# Add an account interactively
namecheap-dns account add

# Or add with a specific name
namecheap-dns account add personal

Manual Setup

1. Create the config file:

   namecheap-dns config init

2. Edit the config file:

   # Edit ~/.namecheap-dns.yaml or ./configs/.namecheap-dns.yaml
   vim ~/.namecheap-dns.yaml

3. Validate your configuration:

   namecheap-dns config validate

Managing Multiple Accounts

List All Accounts

namecheap-dns account list

Switch Accounts

namecheap-dns account switch work

Use Specific Account for One Command

namecheap-dns --account work domain list

Edit Account

namecheap-dns account edit work

Remove Account

namecheap-dns account remove work

Security Best Practices

• File Permissions: Configuration files use 600 permissions (owner read/write only)
• API Keys: Are masked in output (shows only first 4 and last 4 characters)
• Git Ignore: Configuration files are excluded from git by default
• Sandbox Mode: Use use_sandbox: true for testing

Sandbox Environment

For testing, you can use Namecheap's sandbox environment:

accounts:
  test:
    username: "sandbox-username"
    api_user: "sandbox-api-user"
    api_key: "sandbox-api-key"
    client_ip: "your.public.ip.address"
    use_sandbox: true
    description: "Sandbox for testing"

Troubleshooting Configuration

"No config file found"

Run:

namecheap-dns config init

"Account not found"

Check available accounts:

namecheap-dns account list

API Connection Errors

• Verify your API key is correct
• Check that your client IP is whitelisted in Namecheap
• Ensure you're not using sandbox credentials in production
• Verify your IP hasn't changed (update if needed)

Migration from Legacy Config

If you have an existing single-account configuration, the tool will automatically migrate it to the new multi-account format. Your existing configuration will be preserved as the default account.