Webtrax docs

CLI reference

Every webtrax command and option, the exit codes, and how flags combine with webtrax.yml.

Options on the command line win over webtrax.yml, which wins over the defaults.

Commands

Command What it does
webtrax check [url] Crawl a site and report what is broken. Without a URL, uses target from webtrax.yml.
webtrax init [url] [--force] Write a commented webtrax.yml. Refuses to overwrite one unless --force.
webtrax diff <runA> <runB> Compare two runs: new, fixed and persisting findings. With no arguments, compares the last two runs.
webtrax explain <rule|finding> Why a rule matters and how to fix it; a finding id (from a report) also shows where it was seen.
webtrax doctor Check that this machine can run webtrax: Node version, DNS, HTTPS, write access, config.
webtrax mcp [--allow-public] Run the local MCP server over stdio. See MCP.
webtrax --version, webtrax --help Version and help.

Options for check

Option Default What it does
--config <file> ./webtrax.yml if present Config file to read.
--max-pages <n> 300 Pages to crawl. Links beyond the limit are still checked, once each.
--max-depth <n> 10 Link depth from the start page.
--suites <list> links,security,seo Suites to run: links, security, seo, a11y, performance.
--browser off Also run the browser suites, a11y and performance. They load a sample of pages in Chromium (through the runner’s egress proxy), so they need Chromium or Google Chrome.
--fail-on <severity> high Exit 1 when a finding is at this severity or worse: critical, high, medium, low, info, or none.
--reports <list> html,md Report files to write: html, md, json, sarif (GitHub code scanning), junit (CI dashboards).
--out <dir> ./.webtrax Where runs are written: <dir>/runs/<time>/.
--stdout <format> console What to print: console, md or json.
--quiet off Print nothing; use the exit code and the report files.
--allow-private off Allow private network targets. Automatic for localhost and private IPs.
--ignore-robots off Crawl paths robots.txt disallows. Only for sites you run.
--no-external off Do not check links to other sites.
--rps <n> 2 Requests per second to each host.
--concurrency <n> 4 Parallel requests.
--time-budget <s> 600 Stop after this many seconds and report what was found.
--ignore <rules> none Rule ids to leave out of the reports and the exit code, for example seo.noindex on a staging site. They stay in run.ndjson.

Options for mcp

Option Default What it does
--allow-public off Let the MCP server check public sites, not only local ones. Crawls are then capped at 500 pages and 2 requests per second per host. See MCP.

Exit codes

Code Meaning
0 The check ran and nothing reached --fail-on.
1 At least one finding at or above --fail-on.
2 Usage or configuration error.
3 The site could not be crawled (unreachable, or the start URL redirects to another site).

Press Ctrl-C once to stop a check and still get a report of what was found (the run is marked partial); press it again to quit at once.