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

--depth 0 audits the URL you named and follows nothing. 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.

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.
• --max-pages 50 caps the crawl while you are still exploring. A run that hit a cap says so under diagnostics, rather than reporting a smaller number as if it were the whole site.

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. Matching survives the environment change (a baseline captured against production gates a run against localhost), and Baseline gating explains how.

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.