DNScale CLI reference

The official dnscale CLI brings zone and record management, DNSSEC inspection, and usage reporting to your terminal. Use the same commands interactively, in shell scripts, and in CI. For a complete walkthrough, start with the CLI quickstart.

Version 1.0.0 is available through Homebrew, platform downloads, and Go. Start with read-only commands and local dry-runs; verify record writes in a disposable zone before using them on production zones.

Repositories and releases

Install

Homebrew

On macOS or Linux:

brew install dnscaleou/tap/dnscale
dnscale --version

The official tap selects your platform's archive, verifies its checksum, and installs Bash, Zsh, and Fish completions. To update Homebrew and upgrade the CLI:

brew update
brew upgrade dnscale

Remove it with brew uninstall dnscale.

Binary downloads

Download the matching archive and checksums.txt from the 1.0.0 release. No Go installation is needed.

Compare the archive's SHA-256 hash with checksums.txt before extracting. On macOS, use shasum -a 256 ARCHIVE; on Linux, use sha256sum ARCHIVE; on Windows, use PowerShell's Get-FileHash ARCHIVE -Algorithm SHA256.

Extract the archive and add the directory containing dnscale or dnscale.exe to PATH. Run dnscale --version to check the installation. The archives include the quickstart and example record files; the README includes installation commands for each operating system.

Install from source

With Go 1.25 or newer:

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

The binary reports dnscale version 1.0.0. Add GOBIN, or the bin directory under go env GOPATH when GOBIN is unset, to your PATH.

You can also build from the public repository:

git clone --branch v1.0.0 https://github.com/dnscaleou/dnscale-cli.git
cd dnscale-cli
make build
bin/dnscale --version

The Makefile selects Go 1.25.14. On Windows, use go build -o bin/dnscale.exe ./cmd/dnscale from the repository root, or the versioned go install command above.

Authentication and profiles

Create an API key in the dashboard with the scopes your commands need. Supply DNSCALE_API_KEY through your shell, secret manager, or CI secret. The CLI uses that key directly, or saves it in the operating system's keychain:

dnscale auth login --profile work
dnscale auth status --profile work
dnscale auth profiles
dnscale auth use work
dnscale auth logout --profile work

Login also accepts --key-stdin for a key supplied over stdin. It never prompts or accepts a key flag. The CLI does not load .env files. On a headless system without a supported keychain, use DNSCALE_API_KEY directly and omit --profile. There is no plaintext credential fallback.

auth status reports local configuration, without contacting the API to check the key. Logout removes local credentials; it does not revoke the server key.

For a provisioned sandbox, bind a separate profile to its actual API endpoint:

dnscale auth login --profile sandbox --base-url https://YOUR_SANDBOX_HOST/v1

A profile name is a label. Calling a profile sandbox does not simulate writes. The default endpoint is https://api.dnscale.eu/v1.

Credential selection

1. --profile, then DNSCALE_PROFILE, selects a stored profile and ignores ambient API key and base URL variables.
2. Otherwise, DNSCALE_API_KEY selects environment authentication. The endpoint comes from --base-url, then DNSCALE_BASE_URL, then the default.
3. Otherwise, the default saved profile is used.

Saved credentials stay bound to their endpoint; an incompatible --base-url is rejected. Profile metadata is stored under the OS user configuration directory in dnscale/config.json, or under DNSCALE_CONFIG_DIR. Tokens are stored separately in the OS keychain. Endpoints require HTTPS and a /v1 path; HTTP is accepted only for loopback development.

Commands

ZONE accepts a UUID or an exact domain name, ignoring case and a terminal dot. Names are resolved across all accessible zone pages; ambiguous matches fail. UUIDs avoid the name-resolution request. Record IDs are opaque, and an update can change them: retain the returned data.id for the next get or delete.

dnscale zones list --all --profile work --json
dnscale zones get example.com --profile work
dnscale records list example.com --all --profile work --json
dnscale dnssec status example.com --profile work
dnscale dnssec ds example.com --profile work
dnscale usage current --profile work
dnscale usage summary --month 2026-10 --profile work

DNSSEC inspection is read-only. A successfully retrieved disabled status exits 0; empty DS records are []. These commands do not verify registrar delegation or public propagation. Zone deletion, BIND imports, whole-RRset deletion, and DNSSEC changes are outside this command set.

Record input and dry-run

Create and update accept record flags or one UTF-8 JSON object, up to 1 MiB. Save this example as record.json:

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

Validate it without credentials or an API request:

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

Dry-run returns submitted: false and validation: "local_only". It validates input locally without checking ownership, permissions, quota, or server DNS rules. File input cannot be combined with record field flags. Unknown fields, trailing JSON documents, and missing name/type/content are rejected.

After checking your sandbox profile and zone:

dnscale records create ZONE_ID --file record.json --profile sandbox --json
dnscale records update ZONE_ID RECORD_ID --name _cli --type TXT --content replacement-value --ttl 300 --profile sandbox --json
dnscale records delete ZONE_ID UPDATED_RECORD_ID --yes --profile sandbox

Create/update flags include --name, --type, --content, --ttl, --priority, --disabled, and --comment. Explicit false, zero, and empty strings are preserved; JSON accepts null for nullable comment/priority fields.

Update semantics

Update uses a complete PUT body. Name, type, and content are required, and name/type must match the selected record. Omitted TTL or zero selects the server's default of 3600; omitted disabled means false. Omitted/null comment preserves the existing comment, while an empty string clears the DNScale-owned comment. The CLI does not fetch and merge old fields for you.

TTL and comments apply to the entire name/type RRset. Sibling values keep their own content and disabled state. Use the documented TTL range of 300–86400 seconds; the CLI also accepts the API's existing lower compatibility values and zero/default form. Use the quickstart to exercise a two-value TXT workflow in a disposable zone.

JSON and pagination

Output is indented JSON by default; --json produces compact JSON. Success goes to stdout, errors to stderr. Help, version, and completion are text.

{
  "data": [],
  "context": {
    "profile": "work",
    "base_url": "https://api.dnscale.eu/v1",
    "credential_source": "keychain"
  },
  "pagination": {
    "offset": 0, "limit": 50, "returned": 0, "total": 0, "has_more": false
  },
  "request_id": "server-request-id"
}

Offline results omit credential context. Lists include pagination and next_offset when there are more results. --all collects every page before printing, checks page consistency, and rejects repeated IDs. It is not an atomic snapshot of a changing zone. There are no server-side name/type list filters; filter locally after collecting the necessary pages.

When supplied by the API, request_id identifies the final request, including when name resolution preceded the operation. Errors expose error.code, error.message, and available HTTP status, request ID, and retry delay.

--timeout defaults to 30 seconds for the entire command, including resolution, pages, and retry waits. --retries defaults to 2 for safe reads. Writes are never automatically retried. If a write times out, inspect current state before repeating it. A PARTIAL_RECORD_UPDATE error requires checking each affected region; updates across regions are separate operations.

API scopes

Zone and record-name restrictions still apply. A denied command never switches credentials or broadens permissions automatically. See API authentication for key management.

Completion, upgrades, and removal

Use dnscale completion SHELL to generate completion for Bash, Zsh, Fish, or PowerShell, and install the output in your shell's completion directory. For example, Bash can load it for the current session:

source <(dnscale completion bash)

Upgrade with brew upgrade dnscale, install a newer Go version tag, or replace the binary with a verified newer download, then check dnscale --version. Use brew uninstall dnscale for a Homebrew installation, or remove the binary and completion files for a manual installation. Run auth logout --profile NAME for each saved profile before removing profile metadata. Revoke API keys separately in the dashboard when they are no longer needed.