CLI Reference

CLI Reference

Synopsis

natbench [OPTIONS]

Options

Flag	Default	Description
--top N	—	Show only the top N results
--protocol PROTO	udp	Protocol: udp tcp dot doh udp+tcp all
--af AF	auto	Address family: auto ipv4 ipv6
--count N	5	DNS queries per server (higher = more accurate)
--timeout SEC	3.0	Per-query timeout in seconds
--server IP[:PORT]	—	Add a custom server (repeatable)
--tag TAG	—	Filter built-in servers by tag (repeatable)
--no-system	off	Skip auto-detected system DNS
--export FILE	—	Write results to file (format by extension)
--format FORMAT	table	Output format: table json csv markdown
--quiet	off	Only print results, no progress
--version	—	Print version and exit

Protocol values

Value	Description
udp	Plain DNS over UDP (port 53)
tcp	Plain DNS over TCP (port 53)
dot	DNS over TLS (port 853)
doh	DNS over HTTPS
udp+tcp	Both UDP and TCP, results merged
all	All protocols, results merged

Examples

# Quick top-5 ranking, UDP
natbench --top 5

# Full test — all protocols, IPv6 only
natbench --protocol all --af ipv6

# Test only security-focused resolvers
natbench --tag malware --tag no-log

# Test with high accuracy (20 queries per server)
natbench --count 20 --top 10

# Include a custom server alongside built-ins
natbench --server 192.168.1.1 --top 5

# Export results to CSV
natbench --export results.csv

# JSON output for scripting
natbench --format json --top 10 | jq '.[0]'

# Silent mode — just the table
natbench --quiet --top 5

Output format

Default table output:

Rank  Server               IP/Protocol      Median  P95   Min  Max  Reliability  Score
   1  dns.wonx.eu          IPv4 145.239.0.…    1.4   2.1  1.1  3.2       100%   96.5
   2  Cloudflare Primary   IPv4 1.1.1.1         5.2   8.3  4.8  9.1       100%   92.1
   3  Quad9 Primary        IPv4 9.9.9.9          6.8  11.4  6.2 14.8       100%   89.3

All latency values are in milliseconds.

Exit codes

Code	Meaning
0	Success
1	No servers could be tested
2	Invalid arguments
130	Interrupted (Ctrl+C)