CLI reference

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

goflag <url> [options]
goflag rules
goflag flags
goflag preview <url>

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.

goflag rules and goflag flags answer a question about goflag rather than about a site, so they take no URL and touch no network. The first prints every rule as JSON — severity, rigor, the documents it cites, the fix snippet. The second prints this page’s flag table, the same one goflag --help is rendered from and the argument parser dispatches on.

goflag preview does take a URL, and audits like a normal run. It writes .goflag/preview.html — one self-contained file showing what Google, Open Graph, X, LinkedIn, Slack, Discord and WhatsApp make of each page, each surface labelled with how well its geometry is actually documented. It never gates: it exits 0 unless the run itself failed, because looking at your own cards is not a check.

Neither the rule catalogue nor the flag list below is a description of that data — each one is that data, read from the file the command prints. That is not a detail: both pages used to be kept by hand, and both had drifted from the engine by the time anybody checked.

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.

--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.
--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.
--json: Print the JSON report to stdout (nothing else).
--report <file>: Write the full JSON report to <file>.
--summary-s: Roll findings up, deduplicated by link, rule or code. Pairs with --json for a compact, agent-friendly payload. Not available with --baseline, which is an error rather than a preference: baseline mode answers with the diff, a rollup has no way to express one, and accepting the flag would print an answer to the other question — the whole backlog, next to an exit code decided by findings it never named. --report writes the full report alongside the diff.

Crawl

What gets visited, and how the pages to audit are chosen.

--coverage <mode>default structural when a sitemap is found, all otherwise: How the pages to audit are chosen. "structural" keeps every page that stands alone and samples three pages from each family of pages built from one template, so a site of thousands of pages is covered by its templates rather than by whichever URLs the crawl reached first. "all" audits what the sitemap lists, in order, up to --max-pages. Selecting needs a sitemap: with --no-sitemap, or when discovery finds nothing, there is nothing to select from and the run behaves as "all" — though diagnostics.coverage.mode still echoes the value you passed, with no considered/selected/families beside it, which is how you tell the two apart.
--depth <n>default 2: How far the crawl follows links out of each page it visits. 0 follows none. It does not bound the page set on its own: sitemap URLs are seeded at depth 0, so --depth 0 still audits every page the coverage selection named. Add --no-sitemap to audit the entry page alone.
--exclude <glob>: Skip paths matching <glob>. Repeatable.
--include <glob>: Only crawl paths matching <glob>. Repeatable.
--max-pages <n>default 200: The crawl's page budget. A hard cap under --coverage all, or when no sitemap was found. Under structural coverage the selection has already answered "how many", so the effective budget is max(--max-pages, pages selected + 5) and a run left at the default will audit as many pages as the selection needs. Narrow a structural run with --include/--exclude instead.
--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.

--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.
--locales <list>: Comma-separated locales the site serves, e.g. "fr,en,pt-br". Your declaration of intent, and the only way to make a locale the site does not serve yet show up as missing. The list is unioned with the prefixes the sitemap shows, never substituted for them, so a locale your sitemap demonstrably serves stays on the axis; the report labels the source "explicit" as soon as the flag is present. It is also what folds /en/… and /fr/… into one route family for structural coverage, so it is worth passing on any locale-prefixed site.

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.

--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.
--fail-on <level>default warning: Exit 1 at or above this severity: warning, error, or never.
--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.
--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.
--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.

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.

--allow-insecure-tls: Accept self-signed or otherwise invalid TLS. For localhost and tunnels.
--no-external: Do not probe off-origin links. Their failures are somebody else's outage.
--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.
--timeout <ms>default 8000 for link probes, 15000 for page fetches: Per-request timeout, applied to page fetches and link probes alike. The two defaults differ when the flag is left off; headless navigation has its own and this flag does not reach it.

Terminal

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

--help-h: Show the help text.
--no-colordefault colour when stdout is a TTY and NO_COLOR is unset: Disable coloured output.
--quiet-q: Suppress the live progress output.
--verbose-V: Log every page as it is analyzed, and stream the --start child's output.
--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. With a baseline it means nothing got worse, not that the site is clean: known findings pass through by design. Also returned by --update-baseline, --help and --version.
1 · findings found: Findings at or above --fail-on, a new regression against a baseline, or --max-debt exceeded. This is the CI gate.
2 · fatal error: The audit could not run, or refused to report: malformed URL, a missing <url>, an unknown flag, an unreadable baseline, a --start command that never answered — or a sitemap that was declared and could not be fetched, which leaves the crawl following links and auditing a different site from the one a baseline was taken on.

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: the pages the crawl audited (--max-pages, or the structural selection)
Unique link targets probed: 10,000
Link probes in parallel: 8 overall, 3 per host
Redirect hops followed: 10, then reported as a loop
URLs collected from a sitemap: 5,000
Child sitemaps followed from an index: 50