CLI

This page documents gonemaster, the direct local test runner. It runs the engine in the current process without gonemaster-server.

gonemaster normalizes IDN domains to IDNA A-labels before use.

This page is for the local runner only. The server client is documented under client/ , including job and batch operations.

Installation

Install the CLI with Go:

go install codeberg.org/pawal/gonemaster/cmd/gonemaster@latest

For local development from a checkout:

go build -o gonemaster ./cmd/gonemaster

Synopsis

gonemaster [flags] [DOMAIN]

Notes:

• DOMAIN can be provided as a positional argument or with --domain.
• --domain or positional DOMAIN is required for test runs.
• --version, --list-tests, and --dump-profile do not require a domain.
• Malformed undelegated inputs such as --ns or --ds return exit code 2.
• The built-in profile uses resolver.defaults.parallel=8 and resolver.defaults.unordered=true.
• For deterministic ordered behavior, use --ordered --parallel 1.

Exit Codes

• 0: success
• 2: usage or runtime error
• 130: interrupted by signal

Output Modes

Default output is translated human-readable text on stdout. Progress goes to stderr when stdout is a terminal.

Additional output controls:

• --count appends human-readable level and tag counts.
• --nstimes appends per-nameserver timing statistics.
• --debug-queries appends a per-nameserver query trace: attempts, timeouts, errors, canceled attempts and skip decisions.
• --output PATH writes selected output to a file.
• --save PATH writes the DNS packet cache after the run.
• --restore PATH primes the DNS packet cache before the run.
• --cache-stats PATH prints statistics for a saved cache file and exits.
• --cache-strict treats cache-file warnings (unknown fields/kinds, missing checksum) as errors when restoring or inspecting.

See cache-format.md for the packet cache file schema.

Machine-Consumer Result Contract

Use --json or --json-stream for machine consumption.

For migrated coherent entries:

• args.ns is the nameserver name.
• args.address is the nameserver IP address.
• args.servers is an array of {ns, address} objects.
• args.asns is an array of ASN integers when ASN data is emitted.

Legacy keys can still appear on non-migrated tags during migration. Prefer the v1.1 keys when they are present.

Reference:

• specifications/log-args-coherency.md
• specifications/log-args-key-glossary.md

Options

The flag groups below follow gonemaster --help.

Target

Output

Cache

Resolver/Profile Overrides

Undelegated

Utility

--raw, --json, and --json-stream are mutually exclusive. --count is human-output only.

Examples

Run a full test:

gonemaster example.com

Run one module and testcase:

gonemaster --module address --testcase address01 example.com

Run several testcases (across modules):

gonemaster --testcase consistency04 --testcase delegation07 example.com

Run the profile without the DNSSEC module and zone11:

gonemaster --exclude dnssec,zone11 example.com

Print JSON:

gonemaster --json --domain example.com | jq

Stream JSON entries to a file:

gonemaster --json-stream --output /tmp/gonemaster.jsonl --domain example.com

Save and replay a DNS packet cache:

gonemaster --domain example.com --save /tmp/gonemaster-cache.json
gonemaster --domain example.com --restore /tmp/gonemaster-cache.json

Inspect a saved cache file without running a test:

gonemaster --cache-stats /tmp/gonemaster-cache.json

Show per-nameserver query timing statistics:

gonemaster --nstimes example.com

The table holds max, min, avg, stddev, median, total and count, sorted by nameserver name, address, then median, and covers answered queries only. The timeout column counts exchanges that spent every attempt without an answer, and refused counts responses carrying rcode REFUSED.

Include nameserver timing data in JSON output:

gonemaster --json --nstimes example.com | jq .nameserver_timings

Trace every query attempt and the skip decisions, slowest nameserver first:

gonemaster --debug-queries example.com

The columns and decision kinds are described in debugging.md .

Disable IPv6 and raise parallelism:

gonemaster --no-ipv6 --parallel 4 --domain example.com

Dump the effective profile:

gonemaster --dump-profile --profile ./profile.yaml

List available test cases:

gonemaster --list-tests

High-performance test with Swedish output:

gonemaster --unordered --parallel 8 --locale sv --domain example.com

Undelegated test with explicit nameservers and glue:

gonemaster --domain example.com \
  --ns ns1.example.com/192.0.2.10 \
  --ns ns2.example.net/2001:db8::10

Undelegated test with one nameserver and both IPv4 and IPv6:

gonemaster --domain example.com \
  --ns ns1.example.com/192.0.2.10 \
  --ns ns1.example.com/2001:db8::10

Undelegated DS-only test:

gonemaster --domain example.com \
  --ds 12345,13,2,0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF

Run a test and display score and grade:

gonemaster --score example.com

Use a custom scoring config:

gonemaster --scoring-config /etc/gonemaster/scoring.json example.com

Score with JSON output. The score goes to stderr to keep stdout valid JSON.

gonemaster --json --score example.com | jq

Extract coherent nameserver name and IP pairs:

gonemaster --json-stream --domain example.com \
  | jq -r 'select(.args.ns and .args.address)
           | [.args.ns, .args.address] | @tsv'

Extract ASN lists:

gonemaster --json --domain example.com \
  | jq -r '.[]
           | select(.args.asns != null)
           | [.tag, (.args.asns | map(tostring) | join(","))] | @tsv'

Badkeys Blocklist Setup

Update blocklist data in the default user data directory:

gonemaster --badkeys-update

For developers and packagers, update blocklist data in share/badkeys/:

make badkeys-update

Further Reference

• Testcase specifications: specifications/tests/
• Tag catalogs: specifications/tags/
• Cache format: cache-format.md
• Debugging a run: debugging.md
• Scoring: scoring.md