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 (max, min, avg, stddev, median, total, count), sorted by nameserver name, address, then median.
• --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.

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

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

Show per-nameserver query timing statistics:

gonemaster --nstimes example.com

Include nameserver timing data in JSON output:

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

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
• Scoring: scoring.md