cfdns

Fast CLI for managing Cloudflare DNS records.

Features

• Record management — list, create, update, delete, upsert DNS records
• Proxy control — enable/disable Cloudflare proxy per record
• Multi-profile — switch between multiple API tokens and default zones
• Safe defaults — confirmation prompts, dry-run mode, multi-match protection
• JSON output — machine-readable output for scripting
• Retry logic — automatic retry with backoff for rate limits and server errors

Install

# bun (recommended)
bun add -g cfdns

# or run without installing
bunx cfdns --help

# or compile to standalone binary
bun run compile

Quick Start

# 1. Login with your Cloudflare API token
cfdns auth login --profile personal

# 2. Set a default zone
cfdns zone use example.com

# 3. List records
cfdns record list

# 4. Create a record
cfdns record create www A 203.0.113.10 --proxied

# 5. Update with upsert
cfdns record set home A 192.168.0.10

Commands

Auth

cfdns auth login       save or update an API token
cfdns auth test        validate token and DNS permissions
cfdns auth whoami      show active profile and account access
cfdns auth logout      remove stored credentials

Profile

cfdns profile list     list saved profiles
cfdns profile get      show profile settings
cfdns profile use      set the active profile
cfdns profile delete   delete a profile

Zone

cfdns zone list        list accessible zones
cfdns zone get         show zone details
cfdns zone use         set default zone for active profile

Record

cfdns record list           list records in a zone
cfdns record get            show records by name or id
cfdns record create         create a DNS record
cfdns record set            create or update (upsert)
cfdns record update         update fields on existing record
cfdns record delete         delete matching records
cfdns record enable-proxy   enable Cloudflare proxy
cfdns record disable-proxy  disable Cloudflare proxy

Configuration

Config is stored at ~/.config/cfdns/config.json (permissions set to 0600).

Override with --config <path> or environment variables:

CLOUDFLARE_API_TOKEN   API token (overrides stored token)
CFDNS_ZONE             default zone (overrides profile default)
CFDNS_PROFILE          active profile name
NO_COLOR               disable colored output

Profiles

Profiles let you manage multiple Cloudflare accounts or token scopes:

cfdns auth login --profile work
cfdns auth login --profile personal
cfdns profile use work

Each profile stores a token and default zone independently.

Global Flags

--config <path>    config file path
--token <token>    API token (overrides profile)
--profile <name>   profile to use
--zone <name|id>   zone to use
--json             JSON output
--no-color         disable colors
--verbose          debug output
--quiet            minimal output
--dry-run          preview without changes
--yes              skip confirmations

Examples

# List all A records
cfdns record list --type A

# Update TTL for a specific record
cfdns record update www --type A --ttl 300

# Upsert — creates if missing, updates if exists
cfdns record set home A 192.168.0.10

# Delete with confirmation
cfdns record delete old --type CNAME

# Preview what would happen
cfdns record set test TXT "hello" --dry-run

# JSON output for scripting
cfdns record list --json | jq '.records[].name'

# Compile standalone binary
bun run compile
./cfdns --help

Safety

• Destructive commands require confirmation (bypass with --yes)
• Multi-match never auto-selects — shows candidates and suggests next steps
• --dry-run supported on all mutating commands
• Delete refuses to remove multiple records without --type or --yes
• Errors include actionable suggestions

Development

bun install
bun run dev -- --help
bun run check
bun run build

License

MIT