hcloud-dns
npx machina-cli add skill danjdewhurst/hcloud-skills/hcloud-dns --openclawHetzner Cloud DNS
Zone Lifecycle
Create a Zone
hcloud zone create [options] --name <name>
Flags:
--name <name>- Zone name / domain (required)--ttl <seconds>- Default Time To Live (TTL) of the Zone--mode <mode>- Mode of the Zone: primary, secondary (default: primary)--zonefile <file>- Zone file in BIND (RFC 1034/1035) format (use-to read from stdin)--primary-nameservers-file <file>- JSON file containing primary nameservers (for secondary zones)--label <key=value>- User-defined labels (can be specified multiple times)--enable-protection <delete>- Enable protection (default: none)-o, --output json|yaml- Output format
List Zones
hcloud zone list [options]
Columns: id, name, name_idna, status, ttl, mode, authoritative_nameservers, primary_nameservers, registrar, record_count, age, created, labels, protection
Flags:
--mode <mode>- Filter by zone mode-l, --selector <label>- Filter by label selector-s, --sort <field>- Sort results-o, --output noheader|columns=...|json|yaml- Output options
Describe a Zone
hcloud zone describe [options] <zone>
Flags:
-o, --output json|yaml|format- Output format
Delete Zones
hcloud zone delete <zone>...
Accepts one or more zone IDs or names.
Zone Configuration
Change Default TTL
hcloud zone change-ttl --ttl <seconds> <zone>
Flags:
--ttl <seconds>- Default Time To Live (TTL) of the Zone (required, default: 3600)
Change Primary Nameservers
hcloud zone change-primary-nameservers --primary-nameservers-file <file> <zone>
Changes the primary nameservers of a secondary Zone.
Flags:
--primary-nameservers-file <file>- JSON file containing the new primary nameservers (use-to read from stdin)
The input file must be JSON. Example:
[
{ "address": "203.0.113.10" },
{ "address": "203.0.113.11", "port": 5353 },
{ "address": "203.0.113.12", "tsig_algorithm": "hmac-sha256", "tsig_key": "example-key" }
]
Export Zone File
hcloud zone export-zonefile [options] <zone>
Returns a generated zone file in BIND (RFC 1034/1035) format.
Flags:
-o, --output json|yaml- Output format
Import Zone File
hcloud zone import-zonefile --zonefile <file> <zone>
Imports a zone file, replacing all Zone RRSets.
Flags:
--zonefile <file>- Zone file in BIND (RFC 1034/1035) format (use-to read from stdin)-o, --output json|yaml- Output format
Zone Labels and Protection
Add Label
hcloud zone add-label [--overwrite] <zone> <label>...
Labels use key=value format.
Flags:
-o, --overwrite- Overwrite if label key already exists
Remove Label
hcloud zone remove-label <zone> (--all | <label>...)
Flags:
-a, --all- Remove all labels
Enable Protection
hcloud zone enable-protection <zone> delete
Protection type: delete.
Disable Protection
hcloud zone disable-protection <zone> delete
RRSets (DNS Records)
An RRSet is a set of DNS records sharing the same name and type within a zone. RRSets can be managed via the hcloud zone rrset subcommands or equivalent shortcut commands directly under hcloud zone.
Supported record types: A, AAAA, CAA, CNAME, DS, HINFO, HTTPS, MX, NS, PTR, RP, SOA, SRV, SVCB, TLSA, TXT
TXT records must consist of one or more quoted strings of up to 255 characters. Unquoted TXT values are automatically formatted.
Create an RRSet
hcloud zone rrset create [options] --name <name> --type <type> (--record <value>... | --records-file <file>) <zone>
Flags:
--name <name>- Name of the RRSet (required)--type <type>- Record type (required): A, AAAA, CAA, CNAME, DS, HINFO, HTTPS, MX, NS, PTR, RP, SOA, SRV, SVCB, TLSA, TXT--record <value>- Record value (can be specified multiple times, conflicts with--records-file)--records-file <file>- JSON file containing the records (conflicts with--record)--ttl <seconds>- Time To Live (TTL) of the RRSet--label <key=value>- User-defined labels (can be specified multiple times)-o, --output json|yaml- Output format
List RRSets
hcloud zone rrset list [options] <zone>
Columns: id, name, ttl, type, records, labels, protection
Flags:
--type <type>- Filter by record type (can be specified multiple times)-l, --selector <label>- Filter by label selector-s, --sort <field>- Sort results-o, --output noheader|columns=...|json|yaml- Output options
Describe an RRSet
hcloud zone rrset describe [options] <zone> <name> <type>
Flags:
-o, --output json|yaml|format- Output format
Delete an RRSet
hcloud zone rrset delete <zone> <name> <type>
Deletes the entire RRSet (all records with the given name and type).
Add Records to an RRSet
hcloud zone rrset add-records (--record <value>... | --records-file <file>) <zone> <name> <type>
If the RRSet does not exist, it will automatically be created.
Flags:
--record <value>- Record value (can be specified multiple times, conflicts with--records-file)--records-file <file>- JSON file containing the records (conflicts with--record)--ttl <seconds>- Time To Live (TTL) of the RRSet
Shortcut: hcloud zone add-records provides identical functionality.
Remove Records from an RRSet
hcloud zone rrset remove-records (--record <value>... | --records-file <file>) <zone> <name> <type>
If the RRSet has no remaining records, it will automatically be deleted.
Flags:
--record <value>- Record value (can be specified multiple times, conflicts with--records-file)--records-file <file>- JSON file containing the records (conflicts with--record)
Shortcut: hcloud zone remove-records provides identical functionality.
Set Records of an RRSet
hcloud zone rrset set-records (--record <value>... | --records-file <file>) <zone> <name> <type>
Replaces all records in the RRSet. If the RRSet does not exist, it will be created. If the provided records are empty, the RRSet will be deleted.
Flags:
--record <value>- Record value (can be specified multiple times, conflicts with--records-file)--records-file <file>- JSON file containing the records (conflicts with--record)
Shortcut: hcloud zone set-records provides identical functionality.
Change RRSet TTL
hcloud zone rrset change-ttl (--ttl <seconds> | --unset) <zone> <name> <type>
Flags:
--ttl <seconds>- Time To Live (TTL) of the RRSet (required unless--unset)--unset- Unset the TTL so the RRSet uses the Zone default TTL instead
RRSet Labels and Protection
Add Label
hcloud zone rrset add-label [--overwrite] <zone> <name> <type> <label>...
Flags:
-o, --overwrite- Overwrite if label key already exists
Remove Label
hcloud zone rrset remove-label <zone> <name> <type> (--all | <label>...)
Flags:
-a, --all- Remove all labels
Enable Protection
hcloud zone rrset enable-protection <zone> <name> <type> change
Protection type: change. Prevents modifications to the RRSet.
Disable Protection
hcloud zone rrset disable-protection <zone> <name> <type> change
Records File Format
The --records-file option (used with create, add-records, remove-records, set-records) accepts a JSON file:
[
{
"value": "198.51.100.1",
"comment": "My web server at Hetzner Cloud."
},
{
"value": "198.51.100.2",
"comment": "My other server at Hetzner Cloud."
}
]
Source
git clone https://github.com/danjdewhurst/hcloud-skills/blob/main/skills/hcloud-dns/SKILL.mdView on GitHub Overview
Manage Hetzner Cloud DNS zones, DNS records (RRSets), and zone files from the CLI. Create zones, configure TTLs, manage primary nameservers, and import/export zone files to support domain hosting and reliable name resolution.
How This Skill Works
Use the hcloud CLI to operate zones (create/list/describe/delete), manage RRsets (zone rrset create), and import/export zonefiles (zone import-zonefile/export-zonefile). Zones hold DNS records and have a default TTL; you can adjust it with change-ttl and set primary nameservers for secondary zones.
When to Use It
- Setting up a new domain in Hetzner DNS and associating it with hosting resources
- Adding or updating A, AAAA, CNAME, MX, TXT, and other RRSet records for a zone
- Backing up or migrating DNS data by exporting or importing zone files in BIND format
- Changing the default TTL for a zone to balance cache efficiency and freshness
- Organizing DNS assets with labels and applying protection to critical zones
Quick Start
- Step 1: Create a new zone with a name, TTL, and mode as needed
- Step 2: Add RRSet records (A/AAAA/CNAME/etc.) for your domain
- Step 3: Describe or export the zone to verify changes or back up
Best Practices
- Validate zonefiles before importing to avoid syntax errors in BIND format
- Back up existing zones by exporting zonefiles prior to large changes
- Use descriptive labels on zones to improve manageability in large environments
- Set a sensible default TTL and adjust per-record TTL only when necessary
- Enable protection for zones that should not be deleted or altered inadvertently
Example Use Cases
- Create a new zone for example.com with a primary mode and default TTL
- Add an A record for www.example.com pointing to 192.0.2.10 and an MX record for mail.example.com
- Change the zone TTL from 3600 to 7200 to reduce DNS query load during a transition
- Export the zonefile for example.com to back up before a migration
- Import a prepared zonefile to replace all existing RRsets in a migrated zone
