CLI and tools

CLI command reference

Use every DNSMigrator CLI command with documented inputs, options, output, exit codes, and examples for check, translate, diff, lint, export, and DNSSEC.

6 min read

On this page

The CLI command reference covers check, translate, diff, lint, export, propagation, dnssec, and providers, including every implemented option and output mode. The key point is that --strict changes only the exit status for documented findings; it does not change the records or report a command produces.

Global behavior#

text

Usage: dnsmigrator <command> [options]

Option	Short	Value	Effect
`--json`	—	boolean	Emit the command’s JSON result on stdout.
`--no-color`	—	boolean	Disable ANSI color; a non-empty `NO_COLOR` does the same.
`--strict`	—	boolean	Exit 1 when the command-specific findings condition is true.
`--help`	`-h`	boolean	Print command help and exit 0 without running it.
`--version`	`-v`	boolean	Print the package version; with `--json`, emit a version object.

The four process exit codes are 0 for completion, 1 for strict findings, 2 for usage errors, and 3 for runtime errors. A JSON error always has this shape and is written to stdout:

json

{
  "error": {
    "type": "usage",
    "message": "Missing required option --to."
  }
}

Runtime failures use "type": "runtime". See the CLI overview for shell-integration guidance.

check#

Inspect a live domain over public DNS and RDAP, then translate the records that public discovery found for one or more destinations.

text

Usage: dnsmigrator check <domain> [--to <provider>] [--all] [options]

Option	Short	Value	Effect
`--to`	`-t`	provider	Show one destination and include a record-level translation object in JSON.
`--all`	—	boolean	Compare with every DNS destination instead of the featured set.
`--verbose`	—	boolean	With `--to`, show every discovered record rather than only summary and attention rows.
`--json`	—	boolean	Emit the probe, selected compatibility entries, links, and optional translation.
`--strict`	—	boolean	Exit 1 if the domain appears unregistered, DNSSEC is broken, or a selected destination has warning or unsupported records.

A URL or hostname input is normalized by removing its scheme, path, port, trailing dot, and leading www; the probe then discovers the authoritative zone apex. Public discovery reports whether AXFR succeeded; otherwise it is explicitly partial.

bash

npx dnsmigrator check example.com --to route53 --verbose

text

  example.com

  DNS host    Cloudflare DNS
  Registrar   Example Registrar, Inc. · expires 2027-08-13
  Nameservers ada.ns.cloudflare.com, bob.ns.cloudflare.com
  DNSSEC      ✓ signed · Signed, and the resolver validated
  Records     7 record sets discovered · partial: found by querying common names

  Cloudflare → Route 53

  Name  Type  TTL  Value  Notes
  …

  ✓ exact          …
  ↻ translated     …
  ! review          …
  ✗ unsupported     …
  – managed         …
    total            …

  Full report: https://dnsmigrator.com/check/example.com?to=route53
  Migrate with a reviewed plan, verification and rollback: https://dnsmigrator.com/migrate/cloudflare-to-route53

JSON adds these CLI fields to the probe result:

json

{
  "domain": "example.com",
  "apex": "example.com",
  "registered": true,
  "nameservers": ["ada.ns.cloudflare.com.", "bob.ns.cloudflare.com."],
  "provider": { "id": "cloudflare", "name": "Cloudflare DNS" },
  "registrar": {},
  "dnssec": {},
  "discovery": { "records": [] },
  "compatibility": [],
  "translation": {},
  "reportUrl": "https://dnsmigrator.com/check/example.com?to=route53",
  "migrateUrl": "https://dnsmigrator.com/migrate/cloudflare-to-route53"
}

translation and migrateUrl are conditional. The exact provider, registrar, DNSSEC, discovery and compatibility fields come from the probe report. Use the DNS migration checker for the browser version.

translate#

Translate every parsed record in a BIND zone file against one destination’s capabilities and emit a destination-shaped zone.

text

Usage: dnsmigrator translate <zonefile> --to <provider> [options]

Option	Short	Value	Effect
`--to`	`-t`	provider	Required destination provider.
`--from`	`-f`	provider	Source semantics for proxy, automatic TTL and provider features; defaults to `zonefile`.
`--out`	`-o`	file	Write translated BIND text to a file instead of stdout.
`--origin`	—	domain	Supply the zone name when input has no `$ORIGIN`.
`--report`	—	file	Write a JSON record-by-record translation report.
`--verbose`	—	boolean	Show every record row, not only the summary and attention list.
`--json`	—	boolean	Emit metadata, all translated rows, parse errors and generated zone text.
`--strict`	—	boolean	Exit 1 for warning or unsupported rows, or for partial parse errors.

Use - as the input path to read stdin. Unsupported records are omitted from active zone data and appended as comments with their reason.

bash

npx dnsmigrator translate example.com.zone --to cloudflare --out cloudflare.zone

text

  example.com. Zone file → Cloudflare

  ✓ exact          11
  ↻ translated      3
  ! review           0
  ✗ unsupported      0
  – managed          2
    total            16

  Wrote cloudflare.zone
  Apply it with a reviewed plan, verification and rollback: https://dnsmigrator.com/migrate/zone-file-to-cloudflare

Without --out, BIND text is stdout and the summary is stderr:

text

; Translated for Cloudflare DNS by dnsmigrator 0.1.0
; Source: example.com.zone (Zone file)
$ORIGIN example.com.
$TTL 3600

@          300 IN A      192.0.2.10
www       3600 IN CNAME  example.com.

The --json result has stable top-level keys:

json

{
  "zone": "example.com.",
  "from": "zonefile",
  "to": "cloudflare",
  "input": "example.com.zone",
  "output": null,
  "report": null,
  "summary": {
    "total": 16,
    "exact": 11,
    "translated": 3,
    "warning": 0,
    "unsupported": 0,
    "skipped": 2
  },
  "records": [],
  "parseErrors": [],
  "zoneFile": "$ORIGIN example.com.\n…",
  "migrateUrl": "https://dnsmigrator.com/migrate/zone-file-to-cloudflare"
}

A file written by --report contains generator, input, the complete translation result, and parseErrors. See Translation rules.

diff#

Compare two files for the same zone as record sets. The first file is “before”; the second is “after.” SOA, DNSKEY and apex NS are ignored because DNS hosts manage them.

text

Usage: dnsmigrator diff <a.zone> <b.zone> [options]

Option	Short	Value	Effect
`--origin`	—	domain	Supply one origin for files without `$ORIGIN`.
`--json`	—	boolean	Emit both input names, summary, changed records and parse errors.
`--strict`	—	boolean	Exit 1 if any record set was added, removed or changed.

bash

npx dnsmigrator diff before.zone after.zone

text

  before.zone → after.zone  example.com.

    Name    Type   TTL   Value
  + blog    CNAME  3600  blog.example-hosting.net.
  - legacy  SPF    3600  v=spf1 -all
  ~ @       A       300  192.0.2.10
                             192.0.2.11

  1 added, 3 removed, 3 changed, 8 unchanged record sets

JSON preserves full record objects:

json

{
  "zone": "example.com.",
  "a": "before.zone",
  "b": "after.zone",
  "summary": { "added": 1, "removed": 3, "changed": 3, "unchanged": 8 },
  "added": [],
  "removed": [],
  "changed": [{ "before": {}, "after": {} }],
  "parseErrors": { "a": [], "b": [] }
}

Files with different origins are a usage error. Use the zone diff for the in-browser equivalent.

lint#

Parse a BIND file and run generic DNS checks, then optionally apply one provider’s capability limits.

text

Usage: dnsmigrator lint <zonefile> [--provider <id>] [options]

Option	Short	Value	Effect
`--provider`	`-p`	provider	Check destination record types, TTL range and TXT limits.
`--origin`	—	domain	Supply the zone name when input has no `$ORIGIN`.
`--json`	—	boolean	Emit findings with code, severity, message and available record location.
`--strict`	—	boolean	Exit 1 if at least one error or warning exists; informational findings alone do not fail.

Checks include parse errors, duplicates, CNAME coexistence and multiplicity, apex CNAMEs, MX/SRV/NS targets that are CNAMEs, SPF conflicts, TXT chunking, and invalid or unusual TTLs. A provider adds catalog-specific constraints.

bash

npx dnsmigrator lint problems.zone

text

  problems.zone  problems.example. · 16 record sets

  Line  Severity   Name  Type   Message
     6  i info     @     CNAME  …
    10  ✗ error    www   CNAME  www.problems.example. has a CNAME and A records…
    14  ! warning  dup   A      Duplicate of line 13…

  8 errors, 3 warnings, 2 info
  Validate in the browser: https://dnsmigrator.com/tools/zone-file-validator

JSON shape:

json

{
  "file": "problems.zone",
  "zone": "problems.example.",
  "provider": "godaddy",
  "records": 16,
  "findings": [
    {
      "severity": "warning",
      "code": "duplicate-record",
      "message": "Duplicate of line 13. Providers store it once or reject the import.",
      "name": "dup",
      "type": "A",
      "line": 14
    }
  ],
  "summary": { "error": 8, "warning": 3, "info": 2 }
}

The browser zone file validator checks parseability and normalization, not this full lint rule set.

export#

Re-emit a BIND zone as normalized BIND, canonical JSON, or generated DNSControl dnsconfig.js.

text

Usage: dnsmigrator export <zonefile> --format bind|json|dnsconfig [options]

--format is optional in practice and defaults to bind.

Option	Short	Value	Effect
`--format`	`-F`	`bind`, `json`, `dnsconfig`	Select output format; defaults to `bind`.
`--out`	`-o`	file	Write content to a file rather than stdout.
`--provider`	`-p`	provider	Set the generated `NewDnsProvider` type for `dnsconfig`; defaults to BIND.
`--origin`	—	domain	Supply the zone name when input has no `$ORIGIN`.
`--json`	—	boolean	Wrap generated content and metadata in one JSON result, regardless of `--format`.
`--strict`	—	boolean	Exit 1 if the input had parse errors.

bash

npx dnsmigrator export example.com.zone --format dnsconfig --provider cloudflare

dnsconfig.js

// Generated by dnsmigrator 0.1.0 from example.com.zone. Review before running dnscontrol push.

var REG_NONE = NewRegistrar("none");
var DSP_CLOUDFLARE = NewDnsProvider("cloudflare", "CLOUDFLAREAPI");

D("example.com", REG_NONE,
  DnsProvider(DSP_CLOUDFLARE),
  A("@", "192.0.2.10"),
  CNAME("www", "example.com.", TTL(3600))
);

Canonical JSON is a zone object with name, source, and records. When global --json is also present, the wrapper is:

json

{
  "format": "dnsconfig",
  "zone": "example.com.",
  "records": 16,
  "output": null,
  "content": "// Generated by…",
  "parseErrors": []
}

Read Coming from DNSControl before running generated JavaScript with DNSControl.

propagation#

Query the configured public resolver set for one owner name and record type, compare answers, and optionally match an expected set.

text

Usage: dnsmigrator propagation <name> [--type A] [--expect <value>...] [options]

Option	Short	Value	Effect
`--type`	`-t`	record type	Query type; defaults to `A`.
`--expect`	`-e`	value, repeatable	Compare each resolver’s normalized answer with the complete expected set.
`--json`	—	boolean	Emit the propagation report plus browser URL.
`--strict`	—	boolean	Exit 1 if answers differ, any resolver fails to answer, or any answer misses `--expect`.

Accepted query types are A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, SOA, PTR, DS, DNSKEY, HTTPS, SVCB, TLSA, SSHFP, NAPTR, SPF, LOC, CERT, and URI.

bash

npx dnsmigrator propagation example.com --type A --expect 192.0.2.10 --strict

text

  example.com A

    Resolver           Location  Answer       TTL  Time
  ✓ Cloudflare         Anycast   192.0.2.10   300  12ms
  ✓ Google Public DNS  Anycast   192.0.2.10   120  20ms

  2/2 resolvers answered · consistent · 2/2 match the expected value
  Watch it in the browser: https://dnsmigrator.com/tools/propagation-checker?name=example.com&type=A

The JSON report includes name, type, optional expected, a results row per resolver, summary, and url. Use the propagation checker for a smaller browser query-type set.

dnssec#

Read DS records from the parent, DNSKEY records from the child, compare key tags, and report whether a validating resolver accepts the chain.

text

Usage: dnsmigrator dnssec <domain> [options]

There are no command-specific flags.

Option	Effect
`--json`	Emit the DNSSEC report plus nameservers, detected provider and browser URL.
`--strict`	Exit 1 unless status is `signed`; unsigned, broken and unknown all fail strict mode.

bash

npx dnsmigrator dnssec example.com

text

  example.com  ✓ signed
  Signed, and the resolver validated.

  DS at parent  key 2371 · algorithm 13 · digest type 2
  DNSKEY        key 2371 · algorithm 13 · KSK (flags 257)
                key 34505 · algorithm 13 · ZSK (flags 256)
  Matching keys 2371
  Validated     yes
  Nameservers   ada.ns.cloudflare.com, bob.ns.cloudflare.com
  DNS host      Cloudflare DNS

  Check in the browser: https://dnsmigrator.com/tools/dnssec-checker?domain=example.com

JSON shape extends the DNSSEC report:

json

{
  "domain": "example.com",
  "status": "signed",
  "detail": "Signed, and the resolver validated.",
  "ds": [],
  "dnskeys": [],
  "matchingKeyTags": [2371],
  "resolverValidated": true,
  "nameservers": [],
  "provider": { "id": "cloudflare", "name": "Cloudflare DNS" },
  "url": "https://dnsmigrator.com/tools/dnssec-checker?domain=example.com"
}

Use DNSSEC transitions before changing nameservers for a signed zone.

providers#

List DNS destinations in the bundled catalog or show one provider’s capability sheet. Registrar-only entries are rejected because they cannot be translation targets.

text

Usage: dnsmigrator providers [<id>] [--featured] [options]

Option	Value	Effect
`--featured`	boolean	Limit list output to featured providers. Ignored when a specific provider is supplied.
`--json`	boolean	Emit an array for a list or one object for a specific provider.
`--strict`	boolean	Accepted as a global option, but this command has no findings condition and returns 0 on success.

bash

npx dnsmigrator providers cloudflare

text

  Cloudflare DNS  cloudflare · cloud · featured · verified

  Record types  A, AAAA, CNAME, …
  TTL           1m to 1d, default auto
  Apex          CNAME
  Proxy / CDN   yes
  Routing       –
  TXT length    … characters
  DNSSEC        api, auto
  Batch size    …
  Web app auth  API token
  DNSControl    CLOUDFLAREAPI
  Docs          https://…

  Caveats
  • …

List JSON objects contain:

json

{
  "id": "cloudflare",
  "name": "Cloudflare DNS",
  "shortName": "Cloudflare",
  "slug": "cloudflare",
  "kind": "cloud",
  "dns": true,
  "registrar": false,
  "featured": true,
  "verified": true,
  "dnscontrol": "CLOUDFLAREAPI",
  "docsUrl": "https://…",
  "auth": "API token",
  "caveats": [],
  "nameserverPatterns": [],
  "capabilities": {}
}

capabilities.batchSize is null when the internal value is unlimited. For setup instructions rather than machine-readable capabilities, use Supported providers.