Manage DNS with the CLI

The zcp CLI manages your DNS zones and records from the terminal. This page covers each step: create a zone, read the name servers to delegate to, add and remove records, and verify the result.

Before You Start

The zcp CLI installed and authenticated. See the CLI installation guide and CLI Quickstart.
A domain you control at its registrar.

Create a Zone

Add your domain to ZCP. This creates the DNS zone ZSoftly serves.

zcp dns create --name example.com --project default-9

Output:

FIELD    VALUE
Slug     examplecom
Name     example.com
Status   false
Created  2026-07-18T21:08:26.000000Z

ZCP generates a slug from the domain name. Every later command addresses the zone by this slug, not by the domain name. Copy it from this output or from zcp dns list. The Status value turns active shortly after creation.

Read Your Name Servers

When you create a zone, ZCP adds its SOA and NS records for you. The NS record set holds the two name servers you point your registrar at.

zcp dns show examplecom

Output:

FIELD    VALUE
Slug     examplecom
Name     example.com
Status   true
Created  2026-07-18T21:08:26.000000Z
Updated  2026-07-18T21:08:26.000000Z

Records (2):
NAME          TYPE  CONTENT                                                                   TTL
example.com.  SOA   ns1.zsoftly.ca. hostmaster.zsoftly.ca. 2026071801 10800 3600 604800 3600  3600
example.com.  NS    ns1.zsoftly.ca., ns2.zsoftly.ca.                                          3600

Point your registrar at both name servers before you send live traffic. See Domains for the per-registrar steps and the Cloudflare Registrar exception.

Add Records

Use zcp dns record-create with the zone slug, a relative name, a type, and the content.

# Apex A record (use @ for the zone root)
zcp dns record-create --domain examplecom --name @ --type A --content 203.0.113.10

# Subdomain A record
zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.10

# IPv6 address
zcp dns record-create --domain examplecom --name ipv6 --type AAAA --content 2001:db8::10

# Alias one name to another
zcp dns record-create --domain examplecom --name blog --type CNAME --content www.example.com.

# Text record for SPF or domain verification
zcp dns record-create --domain examplecom --name @ --type TXT --content '"v=spf1 -all"'

# Mail server (MX needs a priority)
zcp dns record-create --domain examplecom --name @ --type MX --content mail.example.com. --priority 10

Record rules:

The default TTL is 14400 seconds (4 hours). Override it with --ttl, for example --ttl 3600.
Wrap TXT content in escaped quotes, for example '"v=spf1 -all"', so the quotes reach the record.
A CAA value includes a quoted value. Pass the complete value in shell quotes, for example --content '0 issue "letsencrypt.org"'. The CLI rejects a CAA value without its required quotes.
End a CNAME target with a trailing dot (www.example.com.) to keep it fully qualified.
An MX record needs --priority. Put the mail server in --content and the preference number in --priority, for example --priority 10. The CLI stops with an error if you leave it off.
Creating a record at a name and type with existing values adds the new value to the set.
Supported types are A, AAAA, CAA, CNAME, MX, TXT, and NS. The CLI does not create SRV or LOC records yet. Create them in the DNS section of the console or with the API.

By default, record-create prints one row for the value it created. The result includes the name, type, content, TTL, and, for an MX record, its priority. A priority of 0 is shown as 0.

NAME          TYPE  CONTENT            TTL    PRIORITY
example.com.  MX    mail.example.com.  14400  0

Add --show-zone when you need the resulting full zone instead.

zcp dns record-create --domain examplecom --name @ --type MX --content mail.example.com. --priority 0 --show-zone

--output json and --output yaml return the same one-record list by default. Use --show-zone with either format when a script needs the resulting full zone.

List and Show Records

zcp dns show prints the zone and every record it holds.

zcp dns show examplecom

Records (6):
NAME                  TYPE   CONTENT                                                                   TTL
www.example.com.      A      203.0.113.10                                                              14400
ipv6.example.com.     AAAA   2001:db8::10                                                              14400
blog.example.com.     CNAME  www.example.com.                                                          14400
example.com.          TXT    "v=spf1 -all"                                                             14400
example.com.          SOA    ns1.zsoftly.ca. hostmaster.zsoftly.ca. 2026071807 10800 3600 604800 3600  3600
example.com.          NS     ns1.zsoftly.ca., ns2.zsoftly.ca.                                          3600

For scripting, add --output json and pipe to jq.

zcp dns list --output json
zcp dns show examplecom --output json

Update a Record

There is no update command. To change a record, delete it and create it again with the new value.

zcp dns record-delete --domain examplecom --name www --type A --yes
zcp dns record-create --domain examplecom --name www --type A --content 203.0.113.20

Delete a Record

Address the record set by name and type. The command reads the matching values first, then deletes each value from that initial snapshot.

zcp dns record-delete --domain examplecom --name www --type A

Add --yes to skip the confirmation prompt in scripts. Output:

NAME              TYPE  CONTENT       TTL    PRIORITY  SOURCE
www.example.com.  A     203.0.113.10  14400  -         Pre-delete snapshot

By default, the CLI reads the selected record set before deleting it, then lists every value from that pre-delete snapshot. The SOURCE column identifies this output as Pre-delete snapshot. The CLI only targets the values from this initial snapshot. A value added after the read is not deleted. This snapshot is not an authoritative list of values the command removed. If a matching value changes before deletion, the snapshot can differ from the values removed. The CLI also writes this warning to standard error.

In JSON and YAML output, each snapshot record has source: pre_delete_snapshot.

[
  {
    "name": "www.example.com.",
    "type": "A",
    "content": "203.0.113.10",
    "ttl": "14400",
    "priority": "-",
    "source": "pre_delete_snapshot"
  }
]

If the initial read finds no matching values, the command succeeds with an empty result. With --show-zone, it prints the remaining zone instead.

If one value deletion fails, the command exits with an error and prints no successful deletion result. Values deleted before the failure remain deleted. Run zcp dns show before retrying so you can see the remaining values.

If deletion succeeds but the CLI could not read record details beforehand, it returns an empty result and a warning. --show-zone returns the resulting full zone and does not add snapshot metadata.

Use relative names or @ for normal record deletion. If a temporary lookup failure prevents the snapshot, an explicit fully qualified --name ending in a dot, such as www.example.ca., allows a name-and-type fallback request. This fallback cannot delete values individually and may fail for a multi-value record set. Authentication and authorization errors still stop the command. Add --show-zone to print the resulting full zone after deletion instead.

zcp dns record-delete --domain examplecom --name www --type A --show-zone

Delete a Zone

This removes the zone and all of its records.

zcp dns delete examplecom

Add --yes to skip the confirmation prompt.

Verify

Query the ZSoftly name servers directly to confirm a record before global propagation finishes.

# Ask a ZSoftly name server for the record
dig A www.example.com @ns1.zsoftly.ca +short

# After you delegate at your registrar, query any public resolver
dig A www.example.com @1.1.1.1 +short