Configuration

Configuration

ZoneKit supports multiple accounts, allowing you to manage domains across different DNS providers.

Configuration File

The tool searches for configuration files in this order:

1. ./configs/.zonekit.yaml - Project directory (development)
2. ~/.zonekit.yaml - Home directory (production)
3. Custom path via --config flag

The first file found is used. Project directory takes precedence.

Configuration Structure

accounts:
  default:
    provider: "namecheap"
    username: "your-username"
    api_user: "your-api-user"
    api_key: "your-api-key"
    client_ip: "your.public.ip.address"
    use_sandbox: false
    description: "Production 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"

current_account: "default"

Configuration Fields

Field	Required	Description
provider	No	DNS provider name (default: "namecheap")
username	Yes	Provider account username
api_user	Yes	API username (may differ from username)
api_key	Yes	API key from provider
client_ip	Yes	Public IP address (whitelisted in provider)
use_sandbox	No	Use sandbox environment (default: false)
description	No	Account description

Note: Requirements vary by provider. The fields above are for Namecheap.## Getting API Credentials

Namecheap

1. Log in to your Namecheap account
2. Navigate to Profile → Tools → API Access
3. Enable API access
4. Note your API username, API key, and whitelist your public IP

Other Providers

Refer to your provider's documentation for API credential setup.

Setup

Interactive (Recommended)

# Add account with prompts
zonekit account add

# Or specify account name
zonekit account add personal

Manual

# Initialize config file
zonekit config init

# Edit config file
vim ~/.zonekit.yaml

# Validate configuration
zonekit config validate

Account Management

# List accounts
zonekit account list

# Switch default account
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

• OS Keyring Integration: API keys and OAuth tokens are securely stored in the native OS keychain (Keychain Access on macOS, Secret Service on Linux, Credential Vault on Windows) when zonekit config set is used.
• Audit Logging: All mutating commands (Add, Update, Delete, BulkReplace, Register, Renew) are audited in standard JSON format in ~/.zonekit/audit.log.
• File Permissions: Config files use 600 (owner read/write only)
• API Keys: Masked in output (shows first 4 characters)
• Environment Fallbacks: Missing credentials fallback securely to ZONEKIT_{PROVIDER}_API_KEY style environment variables for CI/CD environments.

Sandbox Environment

For testing with Namecheap sandbox:

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 testing"

Troubleshooting

No config file found:

zonekit config init

Account not found:

zonekit account list

API connection errors:

• Verify API credentials are correct
• Check client IP is whitelisted
• Ensure not using sandbox credentials in production
• Verify IP address hasn't changed
• Confirm provider field matches intended provider

Migration

Existing single-account configurations are automatically migrated to the multi-account format. Your configuration will be preserved as the default account.