Quickstart

Expect the first run to be red. Almost every site that has never been audited carries a backlog. That is not a reason to wait until it is clean: steps 3 to 5 exist precisely so you can gate a site that is not clean yet.

1. Look at one page

Start with the entry page only, so you can read every finding:

pnpm dlx @goflag/cli https://example.com --depth 0 --no-sitemap

--depth 0 stops the crawl following links, but sitemap discovery is on by default and every URL the sitemap lists is seeded into the crawl at depth 0 — so --depth 0 alone still audits the whole selected page set. --no-sitemap is what reduces the run to the single URL you named. This is the fastest way to see whether the metadata rules agree with what you think your site declares.

2. Crawl the site

pnpm dlx @goflag/cli https://example.com --summary

--summary lists each distinct problem once, with a count and a sample of affected pages, instead of repeating the same finding under 40 URLs. On a site with a real backlog it is the only readable view.

On a site with a sitemap, this run does not audit every page. goflag selects by structure: every page that stands alone is audited, and families of pages built from one template (eight or more URLs of the same shape) are sampled — three per family. Template rules (canonical.missing, hreflang.missing, og.image.missing) are conclusive on a sample; copy rules (title.length, description.length) are not. The run prints a COVERAGE line and records what it looked at under diagnostics.coverage, family by family. Pass --coverage all to audit everything the sitemap lists instead, up to --max-pages.

Two flags are worth reaching for immediately:

• --no-external skips off-origin links, the ones you cannot fix. CI explains why they never belong in a gate.
• --locales "en,fr" on any locale-prefixed site. It fixes the locale axis, and it also keeps your top-level sections from being folded into one sampled family.

--max-pages 50 caps a run only when there is no sitemap, or when you also pass --coverage all: under structural coverage the selection has already decided how many pages to audit, and the flag cannot cut below it. --include and --exclude do not help either — they filter the links the crawl discovers, not the sitemap selection it starts from. To explore a genuinely smaller slice, use --coverage all --max-pages 50.

One flag is worth knowing about but not reaching for yet: --static makes the run several times faster and is only safe on fully server-rendered metadata. See Install.

3. Fix what is cheap, then capture a baseline

Fix the errors that take a line of code: a missing canonical, a missing og:image, a <title> that never made it out of a template. Then freeze everything still outstanding:

mkdir -p .goflag
goflag https://example.com \
  --baseline .goflag/baseline.json --update-baseline

That writes the current run to the file and exits 0. It prints how many findings it grandfathered, and the --max-debt ceiling to set next. Commit the file. It is the record of what you agreed to live with.

4. Gate on regressions

goflag http://localhost:3000 --no-external \
  --baseline .goflag/baseline.json --regressions-only

Only findings that are new relative to the baseline fail the build. Page URLs are normalised to origin-independent routes, so SEO, site, translation and unreachable-page findings survive the environment change — a baseline captured against production gates a run against localhost. Broken links are the exception: a link's identity includes where it points, so an internal broken link fingerprints differently on each origin. Capture the baseline in the environment you gate in, or gate with --no-external against the origin the baseline came from. Baseline gating explains the rest.

The output never goes green while findings are outstanding; it says how many are being let through and how old the baseline is:

REGRESSION GATE  0 new · 13 known findings NOT gating this build
baseline https://example.com/ — taken 2026-07-21T09:14:02.881Z (14 days ago)

5. Lower the ratchet

Fix one finding, drop the ceiling by one, commit both:

goflag … --baseline .goflag/baseline.json --regressions-only --max-debt 12

--max-debt fails the build when the total number of findings (new or known) exceeds the budget. This is the only part of the loop that makes the backlog shrink; without it a baseline fossilises behind a build that keeps passing.

Then

• CI: the two moments worth auditing, and why the flags differ.
• Baseline gating: fingerprints, route normalisation, and how to accept a finding on purpose.
• Rule catalogue: what each finding means and how to fix it.
• Look at the cards your pages actually unfurl with — the questions the catalogue states and refuses to answer.