DNScale CLI quickstart

The DNScale CLI puts zone inventory, DNS records, DNSSEC inspection, and usage in your terminal. This guide starts with read-only inspection and an offline record check, then walks through a disposable sandbox workflow.

Version 1.0.0 is available through Homebrew, platform downloads, and Go. The CLI repository hosts source and issues; the Homebrew tap maintains the package formula. Use a provisioned sandbox and a disposable zone for the write steps.

Install the CLI

On macOS or Linux:

brew install dnscaleou/tap/dnscale
dnscale --version

For Windows or a manual installation, download the matching archive from GitHub Releases, compare its SHA-256 hash with checksums.txt, extract it, and add the binary's directory to PATH.

With Go 1.25 or newer, you can also install the versioned source:

go install github.com/dnscaleou/dnscale-cli/cmd/dnscale@v1.0.0
dnscale --version

The binary reports version 1.0.0. For a Go installation, add GOBIN or the bin directory under your Go workspace to PATH. See installation details for platform archives and source builds.

Inspect zones with a read-only key

Create an API key with zones:read and records:read. Supply it through DNSCALE_API_KEY using your secret manager, then save a named profile:

dnscale auth login --profile work
dnscale auth status --profile work
dnscale zones list --all --profile work --json

auth status checks local configuration only. Credentials are saved in the OS keychain. In CI or a headless shell, use DNSCALE_API_KEY directly and omit --profile work instead.

Choose an accessible zone and inspect it, replacing example.com:

dnscale zones get example.com --profile work
dnscale records list example.com --all --profile work --json

The CLI resolves a domain across accessible zone pages. You can also pass the zone UUID returned as data.id to avoid this lookup.

Validate a record offline

Save the following JSON as record.json:

{"name":"_cli","type":"TXT","content":"first-value","ttl":300}

dnscale records create example.com --file record.json --dry-run --json

No credentials, zone resolution, or network access are needed. The result contains submitted: false and validation: "local_only". It checks the input format, without proving zone access or server acceptance.

Prepare a disposable sandbox zone

For the remaining steps, supply a sandbox key with zone and record read/write scopes. Optional DNSSEC and usage inspection also need dnssec:read and usage:read. Zone creation and account usage require a customer-wide key.

Save that key under a separate profile, using the sandbox's actual endpoint:

dnscale auth login --profile sandbox --base-url https://YOUR_SANDBOX_HOST/v1
dnscale auth status --profile sandbox
dnscale zones create YOUR_TEST_ZONE --region EU --profile sandbox --json

Replace YOUR_TEST_ZONE with a disposable zone you control, then keep the returned data.id as ZONE_ID. Creating the zone does not change registrar delegation. A profile named sandbox is only a label; submitted commands change data at its configured endpoint.

Create two TXT values

Submit your JSON file, then add a second value at the same name:

dnscale records create ZONE_ID --file record.json --profile sandbox --json
dnscale records create ZONE_ID --name _cli --type TXT --content sibling-value --ttl 300 --profile sandbox --json
dnscale records list ZONE_ID --limit 1 --all --profile sandbox --json

Save each creation response's data.id. Call the first RECORD_ID and the second SIBLING_RECORD_ID. Treat these as opaque strings; do not construct them from record names or contents.

Update the selected value

dnscale records get ZONE_ID RECORD_ID --profile sandbox
dnscale records update ZONE_ID RECORD_ID --name _cli --type TXT --content replacement-value --ttl 300 --profile sandbox --json

Keep this response's data.id as UPDATED_RECORD_ID. Changing content can change the record ID, so use the new one for subsequent commands.

Update supplies a complete request: name, type, and content are required. Optional fields use the documented defaults. TTL and comments affect the shared name/type record set. The other TXT value keeps its content and disabled state.

Delete one value and verify the sibling

dnscale records get ZONE_ID UPDATED_RECORD_ID --profile sandbox
dnscale records delete ZONE_ID UPDATED_RECORD_ID --yes --profile sandbox
dnscale records list ZONE_ID --all --profile sandbox --json

Confirm sibling-value remains. Deletion requires --yes and never prompts. The command selects one record ID; whole-record-set deletion is not exposed.

Inspect signing and usage

With the additional scopes described above:

dnscale dnssec status ZONE_ID --profile sandbox
dnscale dnssec ds ZONE_ID --profile sandbox
dnscale usage current --profile sandbox
dnscale usage zone ZONE_ID --profile sandbox

A retrieved disabled DNSSEC status is a successful inspection. An empty DS list does not certify registrar configuration or delegation.

Clean up and automate

Remove the sibling by its saved ID, then remove the disposable zone in the dashboard. Zone deletion is not a CLI command.

dnscale records delete ZONE_ID SIBLING_RECORD_ID --yes --profile sandbox

For scripts and terminal agents, use --json, check the exit code, and retain IDs from write responses. Supply generated JSON over stdin with --file -. Set a command budget with --timeout 60s if needed; the budget covers zone resolution, pagination, and retry waits.

Writes are never automatically retried. If a timeout leaves an outcome uncertain, inspect current records before repeating the command. See the CLI reference for scopes, profiles, pagination, and error codes.