CLI reference

subenum [flags] <domain>
subenum [flags] -dL domains.txt

Flags may appear before or after the domain. A URL, a port or an internationalized name is normalized to the apex domain before scanning.

Flags

Flag	Default	Description
`-attempts <int>`	-	Total DNS resolution attempts per subdomain, 1 = no retry (default 1)
`-ct`	-	Add names from Certificate Transparency logs (crt.sh, one HTTPS request per target, no API key) as candidates and -permute seeds
`-dL <string>`	-	File of apex domains to scan, one per line (- for stdin); replaces the <domain> argument
`-depth <int>`	1	Max recursion depth when -recursive is set (1 = no recursion)
`-diff <string>`	-	Previous results file (any -format); report only names added or removed since then, and exit 4 when there are changes
`-dns-server <string>`	8.8.8.8:53	DNS server: ip:port (UDP, TCP fallback), tls://host[:853] (DNS over TLS) or https://host/path (DNS over HTTPS)
`-exclude <string>`	-	Comma-separated out-of-scope names and *.parent patterns; never queried or expanded
`-exclude-file <string>`	-	File of out-of-scope names and *.parent patterns, one per line (# comments allowed)
`-force`	-	Continue scanning even if wildcard DNS is detected
`-format <string>`	text	Output format: text, json, jsonl, or csv
`-hit-rate <int>`	15	In simulation mode, percentage of names that resolve (1-100)
`-max-queries <int>`	-	Max candidate names to test (0 = unlimited); each name sends one query per record type, per attempt
`-no-abort`	-	Do not abort when the resolver failure rate exceeds 20% (warning is still emitted)
`-o <string>`	-	Write results to file (in addition to stdout)
`-permute`	-	After each scan, scan permutations of the names found (api -> api-dev, dev-api, dev.api, api2, …)
`-print-config`	-	Print every setting’s effective value and its source (flag, env, config or default), then exit
`-progress`	true	Show progress during scanning
`-r <string>`	-	File of resolvers (ip or ip:port, one per line) to spread queries over; every hit is re-validated against -dns-server
`-rate <int>`	-	Max DNS queries per second on the wire, all workers combined; counts every record type, retry and wildcard probe (0 = unlimited)
`-recursive`	-	Recursively enumerate subdomains of discovered subdomains
`-resume <string>`	-	Resume an interrupted run from its state file (no other arguments)
`-retries <int>`	-	Deprecated: use -attempts instead
`-sarif <string>`	-	Write takeover candidates to this file as SARIF 2.1.0, for GitHub code scanning (needs CNAME in -type)
`-seed <uint>`	-	In simulation mode, seed for reproducible results (0 = random; the seed used is printed)
`-seeds <string>`	-	Results file (any -format) whose names also seed -permute; implies -permute
`-show-records`	-	In text format, append each result’s records (TYPE=value)
`-silent`	-	Pipeline mode: bare result names on stdout, and only errors (and a simulation warning) on stderr
`-simulate`	-	Run in simulation mode without actual DNS queries (for testing)
`-simulate-zone <string>`	-	Lab mode: answer every query from this scenario file via a local DNS server, so no traffic leaves the machine (see the Labs page)
`-state <string>`	subenum-resume.json	Where an interrupted run saves its state for -resume
`-stats <string>`	-	Write a JSON run-quality report (outcomes, queries sent, verdict) to this file
`-t <int>`	100	Number of concurrent workers
`-timeout <int>`	1000	DNS lookup timeout in milliseconds
`-tui`	-	Launch the interactive terminal UI (all other flags are ignored)
`-type <string>`	A,AAAA	Comma-separated DNS record types to look up: A, AAAA, CNAME
`-v`	-	Enable verbose output
`-version`	-	Show version information
`-w <string>`	-	Path to the wordlist file (- for stdin); omitted: the bundled top-5000 list

Exit codes

Code	Meaning
`0`	Success
`1`	Failure
`2`	Invalid arguments or configuration
`3`	Some `-dL` targets failed
`4`	`-diff` found added or removed names
`130`	Interrupted (Ctrl+C)
`143`	Terminated (SIGTERM)

Defaults from the environment or a file

Settings you repeat on every run can live in the environment or a config file. Precedence, highest first: command-line flag, then SUBENUM_* environment variable, then config file, then built-in default.

Each flag reads SUBENUM_<FLAG>, upper-cased with dashes as underscores: SUBENUM_DNS_SERVER, SUBENUM_RATE, SUBENUM_T.
The config file is config.json in your user config directory (~/.config/subenum/ on Linux, ~/Library/Application Support/subenum/ on macOS, %AppData%\subenum\ on Windows), or the path in SUBENUM_CONFIG. Keys are flag names; values are strings, numbers or booleans, and exclude and type also take a list of strings. Mode flags (tui, version, print-config, resume) are command-line only.
The TUI (-tui) starts its form from these values too, over the values it remembers from its last session.
subenum -print-config prints every effective setting and where it came from: flag, env, config or default. With a bad value, -h, -version and -print-config still run and warn; a scan refuses to start and names every bad value.
When -attempts and the deprecated -retries both have a value, the one from the higher-precedence source wins; both on the command line (or both from the same file) is an error.

{
  "dns-server": "tls://1.1.1.1",
  "rate": 200,
  "type": "A,AAAA,CNAME"
}

Output streams

Resolved names go to stdout and nothing else does, so subenum example.com | httpx works as expected. Progress, warnings and the per-outcome breakdown go to stderr. -o writes the same results to a file in the chosen -format; results files are replaced atomically.