Cloudflare DNS management

Purpose

Give an AI agent the ability to manage DNS records in a Cloudflare account from the terminal. Covers list, create, modify, and delete operations across multiple zones, plus zone surveys and automated survey scheduling.

All operations use a Python wrapper around

flarectl

(the official Cloudflare CLI). No browser or Cloudflare UI is required.

When to use

• User asks to add, update, or remove a DNS record.
• User asks to list or inspect DNS records for a domain.
• User asks to run a DNS zone survey or snapshot.
• User asks to schedule automated DNS refreshes.
• Natural follow-on after creating an NPM proxy host (to create the matching A/CNAME record).

Do not use for Cloudflare Pages, Workers, or any Cloudflare service beyond DNS.

Tooling (framework standard)

The framework default is Python 3.10+. The wrapper script (

cf_dns.py

) is written in Python and replicates all behaviors described in the PRD: token loading, binary resolution, argument pass-through, error surfacing. Shell scripts referenced in the PRD (cf-dns.sh) are replaced by this Python implementation; functionality is identical.

Dependencies:

requests

(for survey),

pyyaml

(for YAML survey output, optional). Install with

pip3 install requests pyyaml

.

External binary:

flarectl

(Go binary). The Python wrapper locates it alongside itself or on PATH. See references/flarectl-install.md for install methods.

Inputs required

• Cloudflare API token with "Edit zone DNS" permission stored in

  <TOOLS_DIR>/cf-dns/cf-dns.conf

  as

  CF_API_TOKEN=<value>

  (or set in environment).
• For all operations: zone (domain name).
• For create: record name, type, content; optionally proxied flag.
• For modify/delete: record ID (fetched via list at operation time, never reused from memory).

Directory layout

<TOOLS_DIR>/cf-dns/
    cf_dns.py              # Python wrapper (primary tool)
    cf-dns.conf            # API token config (gitignored)
    cf-dns.conf.example    # Example/template (safe to commit)
    flarectl               # Binary (local copy, OR resolved from PATH)
    survey_dns_zones.py    # Zone survey script
    setup_survey_schedule.py  # Scheduling wrapper
    README.md

Default

<TOOLS_DIR>

:

~/.localsetup/tools

. Adapt to environment as needed.

Workflow

1. Setup (first time)

1. Install flarectl (see

   references/flarectl-install.md

   ).
2. Create

   <TOOLS_DIR>/cf-dns/cf-dns.conf

   with

   CF_API_TOKEN=<your_token>

   . Set permissions

   600

   . Gitignore this file.
3. Create the optional convenience symlink:

   <TOOLS_DIR>/bin/cf-dns

   pointing to

   cf_dns.py

   .
4. Verify:

   python3 cf_dns.py dns list --zone=example.com

2. List records

# Equivalent shell call:
# python3 cf_dns.py dns list --zone=<domain>

• Do not assume a default zone. Always ask the user which domain to list or infer from context.
• Present output as a table: name, type, content, proxied, ID.
• Record IDs are required for modify and delete; capture from this output.

3. Create record

Parameters to gather:

zone

,

name

(subdomain or

@

for apex),

type

(A/AAAA/CNAME/MX/TXT),

content

, and whether proxied.

python3 cf_dns.py dns create --zone=<domain> --name=<name> --type=<type> --content=<content> [--proxy]

After creation: confirm by showing output or re-listing the zone.

4. Modify record (destructive, double confirmation required)

Safety gates (mandatory):

1. User states intent.
2. Agent lists the record(s) that will change (zone, name, type, current content, proposed new content, record ID). Waits.
3. User must confirm with a phrase containing the word "modify" (e.g. "confirm modify"). Vague replies ("yes", "ok") are not accepted.

Steps:

1. List zone to get live record ID.
2. Show details and wait for second confirmation.
3. Apply update:

   python3 cf_dns.py dns update --zone=<domain> --id=<record_id> --content=<new_content> [--proxy|--no-proxy]

4. Re-list to confirm.

Note: run

flarectl dns --help

to verify exact flags for the installed version.

5. Delete record (destructive, double confirmation required)

Safety gates (mandatory):

1. User states intent.
2. Agent shows exactly what will be deleted (zone, name, type, content, record ID). Waits.
3. User must confirm with a phrase containing the word "delete" (e.g. "confirm delete").

Steps:

1. List zone to get live record ID.
2. Show full record detail and wait for second confirmation.
3. Delete:

   python3 cf_dns.py dns delete --zone=<domain> <record_id>

4. Confirm removal (re-list optional).

6. Zone survey

Runs

survey_dns_zones.py

to snapshot all zones and their DNS records via the Cloudflare REST API. Marks each A record

points_to_this_host: true

if it points to this machine's public IP.

Output files (default:

~/.localsetup/context/dns/

):

• cloudflare_dns_survey.json

  (always written)

• cloudflare_dns_survey.yaml

  (written if PyYAML is installed)

Usage:

python3 survey_dns_zones.py [output_dir]

The agent may read the survey for read-only context (e.g. "what records point to this host"), but must always use a live

dns list

call for any modify or delete to get current record IDs.

7. Schedule survey

setup_survey_schedule.py

schedules

survey_dns_zones.py

daily (default 03:15 local time). Prefers cron; falls back to systemd user timer. Idempotent.

Usage:

python3 setup_survey_schedule.py

Agent behavior rules

Multi-zone (mandatory):

• Never assume a single domain. Always ask for or infer the zone before running any command.
• Always pass

  --zone=<domain>

  explicitly.
• When the account has multiple zones, do not default to any one of them.

Record IDs:

• Always fetch the current record list before modify or delete. Do not guess or reuse IDs from a previous session.

Error handling:

• Surface non-zero flarectl exits to the user with the full error output.
• If the token is missing or authentication fails, direct the user to check

  cf-dns.conf

  and the token's IP restrictions.

Security:

• cf-dns.conf

  must be gitignored and permissions set to

  600

  .
• Token should have only "Edit zone DNS" permission and an IP restriction for the machine's public IP.
• Survey output files contain record IDs and content; store in a gitignored location.

Reference

• references/flarectl-install.md - flarectl install methods (Go, Homebrew, manual build)
• references/api-token-setup.md - Cloudflare API token creation guide
• references/survey-schema.md - Zone survey output schema