agent-safe ClouDNS CLI

DNS changes agents can inspect before apply.

cloudns-tools gives automation and operators a predictable CLI for ClouDNS zones, records, presets, and backups, with idempotent writes, dry-run previews, and clean JSON output.

Get started See commands
terminal

# install from GitHub until npm publish

$ npm install -g github:urbansheep/cloudns-tools

# verify credentials and transport

$ cloudns auth check
* Node 20+ - SSH or direct transport - .env based config
5+
command groups
8
first-pass record types
2
transport modes
0
duplicate idempotent writes
Features

Everything needed for careful DNS operations.

Built around predictable commands and inspectable output, so agents can reason about actions before they mutate ClouDNS.

Zone management

List, add, and remove zones with explicit confirmation for destructive commands.

$ cloudns zone list -f json

Record CRUD

Manage A, AAAA, MX, TXT, CNAME, NS, SRV, and CAA records from a consistent surface.

$ cloudns record add example.com -T A -N www -V 192.0.2.10

Provider presets

Preview and apply DNS templates for providers like Fastmail, Vercel, Cloudflare, and Google Workspace.

$ cloudns preset diff example.com fastmail

Backups and restore plans

Create JSON or BIND exports. Restore from JSON with dry-run planning before writes.

$ cloudns backup create example.com

Dry-run safety

Write commands can preview intended changes and exit distinctly when dry-run prevents mutation.

$ cloudns preset apply example.com fastmail -n

Agent-readable output

JSON mode keeps stdout clean while verbose diagnostics are routed to stderr.

$ cloudns record list example.com -f json
Commands

See the current CLI surface.

Switch between real command families. The examples mirror the current `cloudns-tools` grammar rather than future roadmap commands.

cloudns-tools - zones
cloudns auth check
$ cloudns auth check -v   - transport ssh - VPS: ops@example-vps - probe CloudNS API list-zones ok CloudNS auth check ok   $
ok auth check

Verify transport before mutation.

Run cloudns auth check before touching records. It validates the configured transport and credentials with a read-only CloudNS probe.

  • ok SSH or direct transport - choose a whitelisted VPS path or run locally on the VPS.
  • ok Secret-safe execution - credentials are sent in POST data, not placed in the SSH command line.
  • ok Clean automation contract - exit code `2` for config/auth usage failures, `1` for API or transport failures.

Ready to make DNS changes inspectable?

Start with a read-only auth check, then use dry-run JSON before writes.

Open GitHub repo Get ClouDNS API credentials