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.