CLI reference

Every flag goflag accepts, its default, and what it changes, grouped by the question it answers rather than alphabetically.

goflag <url> [options]

The URL is positional and required. Everything else has a default that is safe to leave alone; the flags below are the ones worth knowing about when it is not.

Output

The terminal view is a render of the JSON, not the other way round. Reach for these when something other than a human reads the result.

--json: Print the JSON report to stdout (nothing else).
--summary-s: Roll findings up, deduplicated by link, rule or code. Pairs with --json for a compact, agent-friendly payload.
--report <file>: Write the full JSON report to <file>.
--conformance: Report every rule's status on every page (pass, fail, warn, n/a), not just the violations. A violations list cannot tell a rule that passes everywhere apart from one that never applied; this can. The terminal shows per-rule totals, and the JSON carries the full rule by page grid.
--advisories: Attach the prose rules: the judgment calls goflag refuses to fake, each with its sources and the observed facts an agent needs to judge it. Asked only where the subject exists, and never counted toward the verdict or the exit code, because nobody has judged them yet.

Crawl

What gets visited. Every default here is a ceiling, not a target.

--depth <n>default 2: Crawl depth. 0 audits the entry page only.
--max-pages <n>default 200: Hard cap on pages crawled.
--include <glob>: Only crawl paths matching <glob>. Repeatable.
--exclude <glob>: Skip paths matching <glob>. Repeatable.
--no-sitemap: Do not discover the sitemap; crawl from <url> only. Discovery is on by default because link-only crawling cannot find locales a site never links to.

Multilingual sites

goflag never guesses a locale from the shape of a path. These two flags are how you tell it what it cannot observe.

--locales <list>: Comma-separated locales the site serves, e.g. "fr,en,pt-br". Authoritative: it overrides what the sitemap and crawl suggest, and makes a locale the site does not serve yet show up as missing.
--ignore-holes <glob>: A locale-free route that is deliberately not translated everywhere, so its gaps are not reported as missing translations. Repeatable, and the suppressed count is still reported under diagnostics.ignoredHoles.

The gate

A plain run fails on any finding, which is unusable on a site that is not clean yet, so it gets switched off. These flags make the gate ask whether a change made things worse.

--profile <name>default default: Policy overlay on the rule set: default, strict (every spec-backed rule fails the build), spec-only (heuristic rules switched off entirely), or marketing (snippet and unfurl metadata gaps are errors). It changes how loudly a rule fires and whether it runs, never what it observes or how authoritative it claims to be. The report records which profile judged it, and the terminal names any non-default one.
--fail-on <level>default warning: Exit 1 at or above this severity: warning, error, or never.
--baseline <file>: Stored report to compare against. On its own it is an error: it weakens the gate, so it has to be asked for by name.
--regressions-onlyrequires --baseline: Fail only on findings that are new relative to the baseline. Known findings stop blocking the build, so a passing run no longer means a clean site, and the output never claims otherwise.
--update-baselinerequires --baseline: Write this run to the baseline and exit 0 instead of judging against it. Use it to capture a baseline, or to accept findings you have decided to live with; it prints what it accepted.
--max-debt <n>: Fail when the site carries more than <n> findings in total, new or known. Lower it as you fix, to stop a baseline from fossilising behind a passing build.

Booting the app

Audit a branch before it ships, against the build it actually produced rather than against production.

--start <cmd>: Boot <cmd>, wait for <url> to answer, audit, then stop it. The process group is killed on exit.
--start-cwd <dir>default the current directory: Directory to run --start in. Set it when auditing a monorepo package from the repository root.
--start-timeout <ms>default 60000: How long to wait for --start to answer. Any HTTP response counts as up.

Fetching

How pages and links are retrieved. --no-external belongs in a CI gate; --static is an opt-in for sites that are certain everything renders on the server.

--static: Static HTML only; never launch headless Chromium, and skip the detection that would. Only safe when every page emits its metadata on the server, an assumption that drifts as a site grows. A client-rendered page is then judged on its unhydrated shell.
--no-external: Do not probe off-origin links. Their failures are somebody else's outage.
--timeout <ms>default 8000: Per-request timeout.
--allow-insecure-tls: Accept self-signed or otherwise invalid TLS. For localhost and tunnels.

Terminal

Progress goes to stderr, so stdout stays clean for the JSON.

--verbose-V: Log every page as it is analyzed, and stream the --start child's output.
--quiet-q: Suppress the live progress output.
--no-colordefault colour when stdout is a TTY and NO_COLOR is unset: Disable coloured output.
--help-h: Show the help text.
--version-v: Show the version.

Exit codes

Only 1 is a verdict about your site. Treat 2 as a broken job.

0 · clean: No findings at or above --fail-on. Also returned by --update-baseline, --help and --version.
1 · findings: Findings at or above --fail-on, a new regression against a baseline, or --max-debt exceeded. This is the CI gate.
2 · fatal: The audit could not run: malformed URL, unreadable baseline, a --start command that never answered.

Engine limits

Compiled in, not configurable. See Limits for what happens when a run hits one.

Pages inspected in parallel: 4
Pages scanned for links: 500
Unique link targets probed: 10,000
Link probes in parallel: 8 overall, 3 per host
Redirect hops followed: 10, then reported as a loop