Cloudflare DNS Migration & Management

End-to-end automation for moving domains from Namecheap to Cloudflare, plus ongoing record management. Designed to be reusable across many domains.

Required environment

Cloudflare auth needs two credentials:

🔴 Security note. CLOUDFLARE_GLOBAL_API_KEY grants full account access (billing, members, everything). Treat it carefully:

• Use Bearer auth (Authorization: Bearer ...) for CLOUDFLARE_API_KEY
• Use header-pair auth (X-Auth-Key: + X-Auth-Email:) for the global key
• Never write either to disk, configs, URLs, or git
• Always pass via env var; never log values

For the registrar side (Namecheap), see the namecheap-dns skill — it shares its IP-allowlist + setHosts conventions with this one.

The hard rule: zone creation needs Global Key

Account API Tokens (the safer, narrower kind) cannot create zones. Cloudflare's POST /zones endpoint always rejects them with:

Requires permission "com.cloudflare.api.account.zone.create"

This is a Cloudflare API limitation, not a missing permission. Solution: use the Global API Key for the single zone-create call, then switch back to the account token for everything else.

The migration scripts handle this split automatically.

Endpoints reference

Record body shape

{
  "type": "A | AAAA | CNAME | MX | TXT | CAA | SRV | NS",
  "name": "subdomain.example.com",   // FQDN, NOT just "subdomain"
  "content": "1.2.3.4",              // for MX/SRV use specific shapes
  "ttl": 300,                        // 1 = "auto" (300s)
  "proxied": false,                   // grey cloud (DNS only) by default
  "priority": 10,                    // MX records only
  "comment": "..."                   // optional, helpful for audit
}

Cloudflare auto-strips the trailing dot on CNAME/MX targets, but be consistent — pass your-app.fly.dev. (with dot) the same way the registrar stored it.

Proxy default: OFF (grey cloud)

Set proxied: false for everything by default. Reasons:

• WebSockets / SSE often break with default proxy settings
• Fly.io, Vercel, Netlify already terminate TLS — proxying adds cert-renewal complications (_acme-challenge flow)
• Easier rollback if something is wrong

Enable per-record manually after migration is verified (/zones/{id}/dns_records/{id} PATCH {proxied: true}).

Workflow: full migration (Namecheap → Cloudflare)

1. Audit current DNS at Namecheap        → scripts/audit.sh <domain>
2. Create zone in Cloudflare              → scripts/migrate.sh <domain> create
3. Import all records to Cloudflare       → scripts/migrate.sh <domain> import
4. Verify resolution via DoH against
   Cloudflare's NS (BEFORE flipping)      → scripts/migrate.sh <domain> verify
5. Flip nameservers at Namecheap          → scripts/migrate.sh <domain> flip
6. Watch propagation                      → scripts/migrate.sh <domain> watch

Pause for confirmation between steps 3 and 5 — the flip is the only step that affects live traffic.

Verifying against Cloudflare's NS BEFORE flipping

Cloudflare's nameservers serve the new zone immediately, even though public DNS still points to Namecheap. Query CF's NS directly to confirm records are correct:

# DoH query AGAINST Cloudflare's authoritative NS:
NS=emerson.ns.cloudflare.com  # one of the assigned NS for this zone
NS_IP=$(curl -s "https://1.1.1.1/dns-query?name=$NS&type=A" \
  -H "accept: application/dns-json" | python3 -c "import json,sys; print(json.load(sys.stdin)['Answer'][0]['data'])")

# Direct UDP DNS via dig — but sandbox lacks dig. Use a public DoT/DoH proxy
# OR run kdig if available, OR use python:
python3 -c "
import socket, struct
# (truncated — see scripts/dns-direct-query.py for full impl)
"

In practice the migrate.sh verify step uses a Python helper that sends a UDP DNS query directly to the Cloudflare NS IP and parses the response, so we know the zone is right BEFORE switching.

Per-domain state

Each migration writes state to .dns-state/<domain>/:

.dns-state/example.com/
├── audit-pre.json           # records before migration
├── cloudflare-zone.json     # zone metadata + NS
├── records-imported.json    # what was sent to Cloudflare
├── verify.log               # NS-direct query results
├── flip.log                 # registrar response when flipping NS
├── post-cutover.json        # records after migration
└── report.md                # human-readable summary

This lets us re-run any step idempotently and roll back precisely.

Rollback

scripts/rollback.sh <domain>

Sets nameservers back to the pre-migration values (saved in audit-pre.json). The Cloudflare zone is left intact — re-running migrate.sh <domain> flip will redo the cutover without re-importing.

Common gotchas

File: scripts/migrate.sh

The main migration driver. Takes a domain + step, runs that step, saves state to .dns-state/<domain>/. Designed for re-runs.

scripts/migrate.sh example.com full       # create+import+verify, then STOPS and prints
                                          # the flip/watch commands (flip touches live
                                          # traffic, so it is never run implicitly)
scripts/migrate.sh example.com create     # create zone only
scripts/migrate.sh example.com import     # import records only
scripts/migrate.sh example.com verify     # query CF's NS to confirm
scripts/migrate.sh example.com flip       # update NS at Namecheap
scripts/migrate.sh example.com watch      # poll propagation

File: scripts/audit.sh

Read-only state check — current registrar, current NS, current records, whether zone exists in Cloudflare yet, what's missing. Safe to run anytime.

scripts/audit.sh example.com

File: scripts/rollback.sh

Sets nameservers at Namecheap back to dns1/2.registrar-servers.com (or the original NS saved in audit-pre.json).

scripts/rollback.sh example.com

Progressive disclosure — load only when needed

Keep this SKILL.md for auth, migration workflow, endpoints, and gotchas. Deep script docs live under references/:

Run the scripts from scripts/; the reference files are the human/agent deep-dive for each.

Script index (quick)

scripts/audit.sh <domain>
scripts/migrate.sh <domain> full|create|import|verify|flip|watch
scripts/rollback.sh <domain>
scripts/harden.sh <domain> [--enable-proxy=false] [...]
scripts/dnssec-instructions.sh <domain>
scripts/origin-ca.sh <domain>
scripts/dns-export.sh <domain> [--format=yaml|json|zonefile|terraform]
scripts/cf-ips-fetch.sh
scripts/dns-direct-query.py   # UDP query against a specific NS IP