ZONEMASTER-CLI(1)

📦
version 8.0.2 · 2 versions
, in nixpkgs unstable

💅 ZONEMASTER-CLI 💅 (that's the zonemaster-cli manual page, bestie, section 1, from the User Contributed Perl Documentation ✨)

okay so real talk: zonemaster-cli is your girl for running Zonemaster tests straight from the command line. she's iconic, she's fast, she's literally the whole vibe 🌈

✨ NAME ✨

zonemaster-cli — run Zonemaster tests from the command line 🎀

🦋 SYNOPSIS 🦋

zonemaster-cli [--help | --version | --list-tests]
zonemaster-cli [OPTIONS] --dump-profile
zonemaster-cli [OPTIONS] DOMAINNAME

🌸 DESCRIPTION 🌸

okay so picture this: zonemaster-cli is a command-line interface to the Zonemaster test engine 👑. it takes the instructions you give it as command line arguments, transforms them into the suitable API calls to the engine, runs the whole test suite, and prints the resulting messages. the way that works?? immaculate.

by default, those messages get translated by the engine's translation module, and each one is printed with its corresponding timestamp and logging level. no cap. scroll on down for all the available options, bestie 💖

🎀 OPTIONS 🎀

💜 Special Options 💜

  • -h, --help — print brief usage information and bail. (run man zonemaster-cli for the full manual page, iykyk)
  • --version — print version information and bail ✨. the version numbers it prints are the versions of this program as well as the ones from the underlying Zonemaster test engine. two for one, we love to see it 🫶
  • --list-tests — print all the test cases listed in the test modules, then exit. it's giving catalog energy 📋
  • --dump-profile — print the effective profile used, in JSON format, then exit 💅

🧚 Testing Options 🧚

  • --test=EXPR — pick which test cases to run by setting the test_cases property in the profile. EXPR is a flexible expression made of terms (individual test cases, test modules, or all) and operators (+ to add, - to remove). for the deets, see man zonemaster-cli.
okay here's the tea on how EXPR behaves 🍓: an EXPR starting with a term (e.g., all, nameserver01) replaces the current selection. an EXPR starting with an operator (+ or -) modifies the current selection. an empty EXPR (--test=) does not modify the selection (i.e., it's a no-op).

multiple --test options may be specified, and they're applied in the order they're given. when used together with --profile, the profile option gets applied first, no cap.

use --list-tests to list all test cases and test modules in the default profile 🌈

the examples, slay by slay:

  • --test=all — selects all test cases in the default profile, i.e. it overrides any custom profile. periodt.
  • --test=nameserver — selects all test cases in the Nameserver test module in the default profile.
  • --test=nameserver01 — selects only the Nameserver01 test case 🎯
  • --test=dnssec-dnssec05 — selects all DNSSEC test cases except DNSSEC05.
  • --test=all-nameserver+nameserver03 — selects all test cases, excludes the Nameserver test cases, and adds back Nameserver03. the comeback tour 💫
  • --test=-dnssec — removes all DNSSEC test cases from the selection.
  • --test=+syntax01+syntax02 — adds the Syntax01 and Syntax02 test cases to the selection.
  • --test= — an empty value is valid, but it doesn't change the selection of test cases. specifying --test= without an argument is a no-op. having this possibility may come in handy when invoking zonemaster-cli from scripts 👑
  • --level=LEVEL — set the minimum level of a message to be printed. (default: NOTICE)

messages at this level (or higher) get printed. the levels are, from highest to lowest: CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG, DEBUG2 and DEBUG3. heads up 🙈: the lowest three levels (DEBUG) add a significant amount of messages to be shown. they reveal some of the internal workings of the test engine, and are probably not useful for most users. like, you were warned, bestie.

  • --stop-level=LEVEL — set the minimum severity level after which the testing suite is terminated. (default: the empty string)

when set to the empty string, testing is allowed to complete normally no matter what messages are emitted 🫶

the levels are, from highest to lowest: CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG, DEBUG2 and DEBUG3.

  • --[no-]progress — print an activity indicator ("spinner"). (default: enabled if the process' standard output is a TTY) useful to know that something is happening during a run 💀 because staring at a silent terminal is not the vibe.
  • --[no-]ipv4, --[no-]ipv6 — enable or disable queries over IPv4 or IPv6. (default: both enabled) 🌐
  • --sourceaddr4=IPADDR, --sourceaddr6=IPADDR — set the IPv4 or IPv6 source address for DNS queries.
⚠️ setting an address not correctly configured on a local network interface fails silently. like, no error, no nothing. rude but true 😭
  • --profile=FILE — override the Zonemaster Engine default profile data with values from the given profile JSON file 🎀

🌟 Formatting Options 🌟

  • --[no-]json — print results as JSON instead of human language. (default: disabled)
  • --[no-]json-stream — stream the results as JSON. (default: disabled) useful to follow the progress in a machine-readable way 🤖
  • --[no-]raw — print messages as raw dumps (message identifiers) instead of translating them to human language.
  • --locale=LOCALE — pick which locale the translation system uses. (default: system locale or English)

if not given, the translation system itself will look at environment variables to try and guess 👀. if the requested translation doesn't exist, it'll fall back to the local locale, and if that doesn't exist either, to English. she's flexible like that 💅

  • --[no-]time — print the timestamp for each message. (default: enabled) ⏰
  • --[no-]show-level — print the severity level for each message. (default: enabled)
  • --[no-]show-module — print the name of the module which produced the message. (default: disabled)
  • --[no-]show-testcase — print the name of the test case (test case identifier) which produced the message. (default: disabled)

🍓 Summary Options 🍓

  • --[no-]count — print a summary, at the end of a run, of the numbers of messages for each severity level that were logged during the run, as well as a count of each message tag. (default: disabled) 📊
  • --[no-]nstimes — print a summary, at the end of a run, of various metrics related to the times (in milliseconds) each name server took to answer, as well as a count of the number of sent queries per name server. (default: disabled) ⏱️
  • --[no-]elapsed — print elapsed time (in seconds) at end of a run. (default: disabled)

🦋 Undelegated Test Options 🦋

  • --ns=DOMAINNAME, --ns=DOMAINNAME/IPADDR — provide information about a nameserver, for undelegated tests.

the argument must be either: (i) a domain name and an IP address, separated by a single slash character (/), or (ii) only a domain name — in which case an A and AAAA records lookup for that name is done in the live global DNS tree (unless overridden by --hints), and the results of that lookup will be used 🌳

this switch can be given multiple times. as long as any of these switches are present, their aggregated content will be used as the entirety of the parent-side delegation information. the whole thing, no cap 👑

  • --ds=KEYTAG,ALGORITHM,TYPE,DIGEST — provide a DS record for undelegated testing (that is, a test where the delegating nameserver information is given via --ns switches).

the four pieces of data (keytag, algorithm, type, digest) should be in the same format they would have in a zone file 📝

  • --hints=FILE — name of a root hints file to override the defaults.

🧊 Cache Options 🧊

  • --save=FILE — write the contents of the accumulated DNS packet cache to a file with the given name, after the testing suite has finished running 💾
  • --restore=FILE — prime the DNS packet cache with the contents from the file with the given name, before starting the testing suite.
the format of the file should be from one produced by the --save switch 🔁

💀 Deprecated Options 💀

  • --encoding=ENCODING — deprecated: simply remove it from your usage. it is ignored. like it literally does nothing, just let her go 🙈
  • --[no-]json-translate — deprecated since v2023.1, use --no-raw instead.

for streaming JSON output, include the translated message of the tag.

⭐ Option Aliases ⭐

these options are provided for compatibility with older scripts 🫶. the first two are aliases for --help. the rest are aliases for their namesakes spelled with dash - instead of underscore _.

  • -?
  • --usage
  • --dump_profile
  • --[no-]json_stream
  • --[no-]json_translate
  • --list_tests
  • --[no-]show_level
  • --[no-]show_module
  • --[no-]show_testcase
  • --stop_level=LEVEL

🔥 EXAMPLES 🔥

zonemaster-cli zonemaster.net

zonemaster-cli --test=delegation --level=info --no-time zonemaster.net

zonemaster-cli --test=delegation01 --level=debug zonemaster.net

zonemaster-cli --list-tests

💖 PROFILES 💖

the testing and result analysis performed by Zonemaster Engine is always guided by a profile 👑. Zonemaster Engine has a default profile with sensible defaults. Zonemaster CLI lets users override the default profile data with values from a profile JSON file using the --profile option.

for details on profiles and how they're represented in files, see Zonemaster::Engine::Profile 📚

🌈 CONFIGURATION 🌈

if there's a readable file /etc/zonemaster/cli.args (Linux style), each line in that file will be prepended as an argument on the command line 📝. if no /etc/zonemaster/cli.args is found (or it's not readable) but /usr/local/etc/zonemaster/cli.args (FreeBSD style) is found and readable, then that file will be used instead. only one global file is loaded, bestie — no mixing.

if there's a readable file .zonemaster/cli.args in the user's home directory, it'll be used in the same way even when a global file has been loaded 🏠. any argument in the user's cli.args will override the same argument in the global config file. user wins, always.

for example, if you'd like to by default run with the log level set to DEBUG and with translation to human-readable messages turned off, you could put this in the config file:

--raw
--level=DEBUG

rules of the road 🎀: only one argument per line. if the argument has a value there must be a = between argument and value. a line starting with # is a comment. comments cannot be added on lines with arguments — pick a lane.

any arguments actually given on the command line will override what's in any of the loaded config files 💅

🎀 SEE ALSO 🎀

more complete documentation on Zonemaster and its tests can be found on <https://doc.zonemaster.net> 🦋

🫶 AUTHOR 🫶

Calle Dybedahl <calle@init.se> and others from the Zonemaster project 💜

and that's the whole thing, bestie ✨ this page was brought to you by perl v5.42.3 and dated 2026-06-29. go forth and test those zones 👑💅

📦 where this page comes from