Configuration

Configuration

Overview

ZoneKit supports multiple accounts, allowing you to manage domains across different DNS provider 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/.zonekit.yaml	Development (project directory)
2	~/.zonekit.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:
    provider: "namecheap"  # DNS provider: "namecheap", "cloudflare", etc.
    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:
    provider: "namecheap"
    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:
    provider: "namecheap"
    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"

  # Example: Cloudflare account (when Cloudflare provider is implemented)
  # cloudflare:
  #   provider: "cloudflare"
  #   api_key: "your-cloudflare-api-key"
  #   email: "your-email@example.com"
  #   description: "Cloudflare account"

current_account: "default"

Configuration Fields

Field	Required	Description	Example
provider	No	DNS provider name (defaults to "namecheap")	"namecheap", "cloudflare"
username	Yes*	Provider account username	"myusername"
api_user	Yes*	API username (may differ from username)	"myapiuser"
api_key	Yes*	API key from provider	"abc123..."
client_ip	Yes*	Your public IP address (required for Namecheap)	"203.0.113.1"
use_sandbox	No	Use sandbox environment (default: false)	true or false
description	No	Account description	"My main account"

Note: Fields marked with * are required for Namecheap provider. Other providers may have different required fields.

Getting Your API Credentials

Namecheap Provider

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

Other Providers

Different DNS providers have different authentication methods. Refer to each provider's documentation for their specific API credential requirements.

Setting Up Your First Account

Interactive Setup

# Add an account interactively
zonekit account add

# Or add with a specific name
zonekit account add personal

Manual Setup

1. Create the config file:

   zonekit config init

2. Edit the config file:

   # Edit ~/.zonekit.yaml or ./configs/.zonekit.yaml
   vim ~/.zonekit.yaml

3. Validate your configuration:

   zonekit config validate

Managing Multiple Accounts

List All Accounts

zonekit account list

Switch Accounts

zonekit account switch work

Use Specific Account for One Command

zonekit --account work domain list

Edit Account

zonekit account edit work

Remove Account

zonekit 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 the provider's sandbox environment (currently supported for Namecheap):

accounts:
  test:
    provider: "namecheap"
    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:

zonekit config init

"Account not found"

Check available accounts:

zonekit account list

API Connection Errors

• Verify your API key is correct
• Check that your client IP is whitelisted (for Namecheap provider)
• Ensure you're not using sandbox credentials in production
• Verify your IP hasn't changed (update if needed)
• Confirm the provider field matches the provider you're trying to use

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.