psylch Cloudflare DNS Skill
Language
Match user's language: Respond in the same language the user uses.
Overview
Manage Cloudflare DNS records via REST API. Covers record CRUD, proxy settings, troubleshooting, and Kubernetes External-DNS integration.
Script Directory
Determine this SKILL.md directory as SKILL_DIR, then use ${SKILL_DIR}/scripts/cloudflare-dns.sh.
Environment
Credentials are loaded automatically from .env files. The script checks in this order (highest priority first):
- Environment variables (already set in shell — always win)
- Project-level
<cwd>/.env(auto-loaded by script) - Skill-level
${SKILL_DIR}/.env(auto-loaded by script)
| Variable | Required | Description |
|---|---|---|
CF_API_TOKEN |
Yes | Cloudflare API Token (Zone:Read + DNS:Edit) |
CF_ZONE_ID |
No | Default zone ID (avoids passing it to every command) |
First-time Setup
When running preflight and credentials are missing, guide the user:
Cloudflare API credentials not found.
How to obtain:
1. Visit https://dash.cloudflare.com/profile/api-tokens
2. Create Custom Token with permissions: Zone:Read + DNS:Edit
3. Scope to specific zones (recommended)
4. Copy the token
Where to save?
A) Project-level: <cwd>/.env (this project only)
B) User-level: ${SKILL_DIR}/.env (all projects using this skill)
After the user chooses, check if a .env already exists at the target location:
- If it exists: show the current contents, ask the user — (A) Append CF_* keys to existing file, (B) Backup and replace (
cp .env .env.backup.$(date +%s)), or (C) Skip - If it does not exist: copy
.env.exampleto.env
Then fill in the values:
CF_API_TOKEN=<user_input>
CF_ZONE_ID=<user_input_optional>
Preflight Check-Fix Table
When preflight reports ready: false, use this table to resolve each failure:
| Check | Status | Fix |
|---|---|---|
curl |
missing | brew install curl (macOS) / apt install curl (Linux) |
jq |
missing | brew install jq (macOS) / apt install jq (Linux) |
dig |
missing | brew install bind (macOS) / apt install dnsutils (Linux) — optional, only for verify-dns |
kubectl |
missing | brew install kubectl — optional, only for External-DNS features |
CF_API_TOKEN |
not_configured | Follow First-time Setup above to create and save the token |
CF_API_TOKEN |
invalid | Token exists but live API check failed. Regenerate at https://dash.cloudflare.com/profile/api-tokens with Zone:Read + DNS:Edit permissions |
CF_ZONE_ID |
not_configured | Optional. Find in Cloudflare dashboard: select zone, copy Zone ID from right sidebar |
Workflow
- Preflight — Verify credentials and tools:
Ifbash ${SKILL_DIR}/scripts/cloudflare-dns.sh preflightready: false, consult the Check-Fix Table above for specific remediation. - List existing records — Understand current state before changes:
bash ${SKILL_DIR}/scripts/cloudflare-dns.sh list-records - Create / update / delete records as needed:
bash ${SKILL_DIR}/scripts/cloudflare-dns.sh create-cname $CF_ZONE_ID www target.example.com true bash ${SKILL_DIR}/scripts/cloudflare-dns.sh create-a $CF_ZONE_ID app 1.2.3.4 true - Verify DNS propagation:
bash ${SKILL_DIR}/scripts/cloudflare-dns.sh verify-dns app.example.com
For raw curl commands, read references/dns-operations.md.
Script Reference
Helper script: scripts/cloudflare-dns.sh
| Command | Description |
|---|---|
preflight |
Check env vars, tools, and token validity |
verify-token |
Verify API token |
list-zones |
List all zones |
list-records [zone_id] |
List DNS records |
get-record <zone_id> <name> |
Get specific record |
create-a <zone_id> <name> <ip> [proxied] |
Create A record |
create-cname <zone_id> <name> <target> [proxied] |
Create CNAME record |
delete-record <zone_id> <record_id> |
Delete record |
export <zone_id> |
Export zone to BIND format |
verify-dns <hostname> |
Verify DNS resolution |
Degradation
| Dependency | When missing | Behavior |
|---|---|---|
dig |
Not installed | Skip verify-dns command; suggest manual check with nslookup or online tools like https://dnschecker.org |
kubectl |
Not installed or no cluster access | Skip check-external-dns; Kubernetes integration features unavailable — user can still manage DNS records directly via API |
Core DNS record operations (list, create, update, delete) only require curl and jq.
Completion Report
After any mutation operation (create, update, delete), present a structured report:
DNS Record Updated!
Zone: [zone name] ([zone_id])
Operation: [create | update | delete]
Record: [type] [name] → [content]
Proxied: [yes | no]
TTL: [value]
Verification:
✓ API returned success
✓ dig @1.1.1.1 [name] [type] → [resolved value] (if dig available)
Next Steps:
→ Full propagation may take 1-5 minutes
→ Verify with: dig @1.1.1.1 [name] [type]
For delete operations, omit the content/proxied/TTL fields and adjust accordingly.
Proxy Decision Guide
| Use Case | Proxy (orange cloud) | Reason |
|---|---|---|
| Web apps, APIs, static sites | Yes | CDN, DDoS protection |
| Mail (MX), SSH, FTP, VPN | No | Non-HTTP protocols |
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
| 401 Unauthorized | Invalid token | Regenerate API token |
| 403 Forbidden | Insufficient permissions | Add Zone:Read, DNS:Edit |
| 429 Rate Limited | Too many requests | Increase interval, use pagination |
| "Record exists" | Duplicate | Delete or update existing record |
| DNS not resolving | Propagation delay | Wait 1-5 min, verify with dig @1.1.1.1 |
Security
- Scope tokens — Use specific zones, not "All zones"
- IP filtering — Restrict to known IPs when possible
- Rotate regularly — Every 90 days for production
- Store in
.env— Never hardcode tokens in scripts or SKILL.md
References
Read these on demand when the user's request needs deeper context. Do not load all at once.
| Topic | File | When to read |
|---|---|---|
| curl examples for all record ops | references/dns-operations.md |
User wants raw curl instead of script |
| Kubernetes External-DNS setup | references/kubernetes-integration.md |
User mentions k8s, External-DNS, AKS |
| Complete Cloudflare API docs | references/api-reference.md |
User needs advanced API features not in script |
| Azure integration patterns | references/azure-integration.md |
User mentions Azure, App Service, AKS |