npm package: @soju06/cfdns
Description: Fast CLI for managing Cloudflare DNS records
Author: Soju06
Latest version: 0.1.0

# 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

```bash
# bun (recommended)
bun add -g cfdns

# or run without installing
bunx cfdns --help

# or compile to standalone binary
bun run compile
```

## Quick Start

```bash
# 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:

```bash
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

```bash
# 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

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

## License

MIT