How do I install the OnlyDNS CLI tool?

You can install the OnlyDNS CLI globally using npm with 'npm install -g @onlydns/cli' (or via pnpm or bun). Alternatively, you can run commands instantly without installation using npx: 'npx @onlydns/cli domains list'.

How does authentication work with the CLI?

The CLI resolves your API key in order of priority: 1) the --api-key / -k command flag, 2) the ONLYDNS_API_KEY environment variable, or 3) stored credentials in ~/.config/onlydns/config.json configured via 'onlydns config login '.

Can I use the CLI in CI/CD pipelines and scripts with JSON output?

Yes. Every CLI command supports the global --json flag, producing clean, structured JSON output ready for parsing with jq, python, or piping into downstream deployment stages.

Where can I find the open-source repository and issue tracker for the CLI?

The OnlyDNS CLI is open source under the MIT License and hosted on GitHub at https://github.com/Onlydns/onlydns-cli.

Command-Line Interface (CLI Tool)

Terminal — onlydns-cli @onlydns/cli

# Run instantly with npx or install globally with npm:
$ npx @onlydns/cli records list example.com
Domain: example.com (Active, DNSSEC: Active)
--------------------------------------------------------------------------------

                        TYPENAMEVALUETTL
                    
--------------------------------------------------------------------------------

                        A@192.0.2.1300
                    
                        Aapi192.0.2.25300
                    
                        TXT_acme-challenge"qL7yP29_d0w9S..."60
                    
$ onlydns records add example.com --name staging --type A --value 192.0.2.99 --ttl 300
✓ Added A record staging.example.com -> 192.0.2.99 (TTL: 300) [Sync: Anycast 23 PoPs]

// Quick Installation

Installation & Execution

Deploy the CLI tool across local workstations, continuous integration runners, or containerized environments.

Global Installation (npm / pnpm / bun)

Recommended

Install globally to make the onlydns command available system-wide in any terminal shell:

# Install globally with npm
npm install -g @onlydns/cli

# Or with pnpm or Bun
pnpm add -g @onlydns/cli
bun add -g @onlydns/cli

After installation, verify with: onlydns --version

Instant Run via npx / bunx

Zero Install

Execute single commands on-demand without permanently installing packages to your system:

# Run any command directly via npx
npx @onlydns/cli domains list

# Filter records with bunx
bunx @onlydns/cli records find example.com --name api

Ideal for one-off tasks, Docker containers, and ephemeral CI/CD runners.

// Security & Credentials

Authentication & Configuration

Flexible credential resolution designed for secure workstations and automated deployment pipelines.

Resolution Priority Order

The CLI automatically checks for authentication tokens in the following order:

CLI Argument: --api-key <token> or -k <token>
Environment Variable: ONLYDNS_API_KEY or ONLYDNS_API_TOKEN
Encrypted Config: Stored profile in ~/.config/onlydns/config.json (permissions mode 0600)

1. Storing Your Token (Local Dev)

# Save your API token securely to ~/.config/onlydns/config.json (mode 0600)
onlydns config login <YOUR_API_KEY>

# Check authentication status
onlydns config show

# View configuration path
onlydns config path

# Clear stored credentials
onlydns config clear

2. Using Environment Variables (CI/CD & Docker)

# Export API key in shell session or CI pipeline secret
export ONLYDNS_API_KEY="odn_live_your_token_here"

# Execute commands directly
onlydns domains list

// Practical Usage

Command Reference & Examples

Real-world examples covering everyday DNS operations, DNSSEC management, and TSIG key provisioning.

1. Domain Management Zones

List and provision authoritative DNS zones:

# List all zones on your account
onlydns domains list

# List with pagination parameters
onlydns domains list --offset 0 --limit 50

# Create a new domain zone
onlydns domains create example.com

2. DNS Record Operations Records

Search, add, update, and remove DNS records:

# List all records for a domain
onlydns records list example.com

# Filter records by name, type, or IP/target value
onlydns records find example.com --name api
onlydns records find example.com --type A
onlydns records find example.com --value 192.0.2

# Add or append a record value
onlydns records add example.com --name www --type A --value 192.0.2.1 --ttl 300
onlydns records add example.com --name @ --type TXT --value "v=spf1 include:example.com ~all"

# Replace all values for a record
onlydns records update example.com --name www --type A --value 192.0.2.100 --ttl 600

# Remove an individual record or specific value
onlydns records remove example.com --name www --type A

3. Automated DNSSEC Signing DNSSEC

Inspect cryptographic status and toggle ECDSA P-256 signing:

# Inspect DNSSEC status and DS records
onlydns dnssec status example.com

# Enable 1-click DNSSEC signing
onlydns dnssec enable example.com

# Disable DNSSEC signing
onlydns dnssec disable example.com

Learn more about Automated DNSSEC →

4. TSIG Keys & Dynamic DNS RFC 2136

Generate TSIG keys and assign Dynamic DNS permissions (with subdomain scoping support):

# List all account TSIG keys
onlydns tsig list

# Generate a new TSIG key (key name is auto-generated)
onlydns tsig create --algo hmac-sha256

# Retrieve secret and details for a key
onlydns tsig get <key_name>

# View configured TSIG permissions for a domain
onlydns tsig get-domain example.com

# Authorize key for Dynamic DNS updates across whole zone
onlydns tsig set-permissions example.com <key_name> --transfer --update

# Restrict Dynamic DNS updates to specific subdomain(s) (e.g. ACME challenges)
onlydns tsig set-permissions example.com <key_name> --update --subdomain _acme-challenge

# Clear TSIG permissions for a domain
onlydns tsig clear example.com

💡 Subdomain Scoping: Use the --subdomain (or -s) flag to restrict TSIG keys to specific subdomains (e.g. _acme-challenge) for least-privilege ACME and dynamic host automation.

Explore Dynamic DNS RFC 2136 Guide →

// Automation & Scripting

Structured JSON Output & Global Flags

Every command outputs machine-readable JSON for integration into shell pipelines, jq filters, and autonomous agents.

Piping with jq & Shell Scripts

Use the --json flag to receive parseable JSON responses:

# Extract active A record IPs with jq
onlydns --json records list example.com | \
  jq -r '.[] | select(.type=="A") | .records[]'

# Check domain DNSSEC status programmatically
STATUS=$(onlydns --json dnssec status example.com | jq -r .enabled)
if [ "$STATUS" = "true" ]; then
  echo "DNSSEC verified!"
fi

Global Options

Flag	Description
`--json`	Output responses in structured JSON
`-k, --api-key`	Explicit API token override
`--base-url`	Custom API base URL endpoint
`--timeout`	HTTP request timeout in seconds (default: 30)
`-h, --help`	Display inline help and command syntax

Open Source

Explore the Source Code on GitHub

Inspect the implementation, read the full README, submit feature requests, report bugs, or contribute to @onlydns/cli on GitHub.

GitHub Repository →

// Frequently Asked Questions

CLI Tool FAQ

How do I generate an API token for the CLI?

Log into the OnlyDNS Portal > Developers > API Tokens and click Create API Token. You can then run onlydns config login <token> to save it locally.

Can I use the CLI in TypeScript / Node.js scripts programmatically?

Yes. You can import { runCli } directly from @onlydns/cli:
import { runCli } from '@onlydns/cli'; await runCli(['records', 'list', 'example.com', '--json']);

How quickly do changes made via CLI propagate?

All modifications executed through the CLI synchronize across all 23 global Anycast edge nodes in real time, typically completing within 0.2 to 5 seconds.

// Pure DNS Automation

Supercharge Your Terminal with OnlyDNS CLI

250,000 monthly DNS queries included on all free accounts. Start automating your DNS infrastructure today.

Create Free Account View GitHub Repository →

Official OnlyDNS CLI Tool