cfdns · Cloudflare DNS Recorder

Install

Run the one-liner above on a Debian or Ubuntu server as root. It installs jq and curl, installs the cfdns command, then asks for two things:

API tokenCreate one at dash.cloudflare.com/profile/api-tokens with the Edit zone DNS template, limited to your domain.

Zone IDOn your domain's Overview page in Cloudflare, in the right sidebar under API.

Both are saved only on your server in /root/.cfdns.env (permissions 600), never in the repository. Then try:

cfdns verify
cfdns list

Commands

Command	What it does
`cfdns verify`	Check the token and show the zone
`cfdns list`	List all records with type, value, proxy status, priority
`cfdns add NAME [VALUE]`	Create a record
`cfdns update NAME NEWVALUE`	Change a record (asks to confirm)
`cfdns proxy NAME [on\|off]`	Show or switch the orange/grey cloud
`cfdns delete NAME`	Remove a record (asks to confirm)
`cfdns site NAME PORT`	DNS record + Caddy config, go live in one step
`cfdns site list` / `site remove NAME`	Show or take down sites managed by cfdns

Flags

Flag	Meaning
`--type T`	Record type: A, AAAA, CNAME, TXT, MX… (default A)
`--priority N`	MX priority (default 10)
`--match TEXT`	Pick one record when a name has several
`--proxy` / `--dns-only`	Orange cloud / grey cloud
`--keep-dns`	With `site remove`: keep the DNS record

NAME can be short (api), full (api.yourdomain.com) or @ for the root domain.

Examples

A and CNAME records

cfdns add myapp                    # this server's IP, proxied
cfdns add myapp --dns-only         # grey cloud
cfdns add myapp 1.2.3.4 --proxy
cfdns add www yourdomain.com --type CNAME

TXT and MX records

cfdns add @ "v=spf1 include:mailgun.org ~all" --type TXT
cfdns add _dmarc "v=DMARC1; p=none" --type TXT
cfdns add @ mx.example.com --type MX --priority 10

Proxy

cfdns proxy myapp          # show state
cfdns proxy myapp on       # orange cloud
cfdns proxy myapp off      # grey cloud

One of several records

A name like @ can hold many records. Say which one you mean:

cfdns update @ "v=spf1 -all" --type TXT --match spf1
cfdns delete @ --type MX --match mx2

Go live

One command makes an app reachable on its own subdomain:

cfdns site myapp 3001

1 · CaddyAdds a reverse-proxy block for myapp.yourdomain.com to your port.

2 · CheckBacks up the Caddyfile and validates it. Rolls back if Caddy rejects it.

3 · ReloadReloads Caddy, which gets the HTTPS certificate on its own.

4 · DNSCreates the A record to your server (proxied unless --dns-only).

cfdns site list
cfdns site remove myapp
cfdns site remove myapp --keep-dns

Needs Caddy installed (apt install -y caddy) and ports 80 and 443 open.

Cloudflare SSL/TLS

These are set in the Cloudflare dashboard under SSL/TLS → Overview. They matter for proxied (orange cloud) records.

Mode	Behavior	Use it?
Off	No encryption	No
Flexible	Plain HTTP to your server; causes redirect loops with Caddy	No
Full	Encrypted, any certificate accepted	Temporary fallback
Full (strict)	Encrypted, certificate must be valid	Yes, recommended

Under Edge Certificates, also turn on Always Use HTTPS and Automatic HTTPS Rewrites, and set Minimum TLS Version to 1.2.

Safety

Zone guardNames outside your domain are refused.

ConfirmationUpdate, delete and site changes show what will change and wait for yes.

No guessingIf a name matches several records, nothing is changed.

Private tokenStored only on your server, never sent anywhere but Cloudflare.

Found a vulnerability? Read the security policy.

Troubleshooting

Problem	Fix
`Could not read your zone`	Re-run the installer with a valid token and Zone ID
`outside your zone`	Use a short name or one ending in your domain
`has N matching records`	Add `--type` and/or `--match`
`Authentication error`	Create a new token with the Edit zone DNS template
502	The app isn't running on that port. Check `pm2 status`
521	Cloudflare can't reach the server. Check Caddy and ports 80/443
525 / 526	Certificate problem. Use Full (strict) and wait for Caddy's certificate
Too many redirects	SSL mode is Flexible. Switch to Full (strict)