Audit

blume audit crawls the built site and reports SEO and site-health issues — every finding names the source file and front matter line that fixes it.

blume validate reads your content; blume audit reads the built site. It crawls the HTML in dist/ after a build and reports SEO and site-health issues — titles, meta descriptions, canonicals, Open Graph and X cards, headings, hreflang, images, the sitemap, robots.txt, and structured data.

Because Blume built the site, every finding names the source file and the front matter line that fixes it, not just the URL a crawler would see:

⚠ Meta description too long or too short   5 pages
    /docs/configuration/export    content/docs/configuration/export.mdx:3
    fix: Rewrite `description` in the frontmatter to fit the length range.

Run it after a build:

blume build
blume audit

Findings are grouped by check rather than listed per page, so the report reads as a to-do list. Use --verbose to expand every affected page with its full detail, and --only/--skip to work through one category at a time. blume audit --list-checks prints the full catalog, which is also the check catalog at the end of this page — every finding’s docsUrl links to its entry there.

Flags

--fail-on error|warning|info — the CI gate: exit non-zero at this severity or above. Defaults to error; --strict is an alias for --fail-on warning.
--url <origin> — also probe a live deployment for status codes, response headers, and redirect chains.
--external — probe outbound links over the network.
--only <check|category> / --skip <check|category> — narrow the report to, or away from, these checks or categories (comma-separated). A term that names no check or category is an error that suggests the closest one, so a typo can’t quietly empty the report.
--list-checks — print every check the audit can report, then exit.
--verbose — list every affected page with each finding’s full detail, instead of the first few.
--json — emit the report as JSON on stdout.
--claude / --codex — hand the findings to Claude Code or Codex to fix interactively.

Failing CI

The exit code is the contract. By default blume audit fails only on errors — things that are definitely broken, like a link to a page that was never built, a redirect loop, or an invalid sitemap. Advisory findings (a short description, a duplicate title) are warnings and do not fail the build:

blume audit                      # fails on errors
blume audit --fail-on warning    # also fails on warnings

Checking a live deployment

Some things only the real server can tell you: whether a page that exists in dist/ actually 404s behind a bad rewrite, whether responses are compressed, and whether an X-Robots-Tag header is quietly deindexing a page whose HTML looks perfectly fine. Point the audit at a deployment to add those checks:

blume audit --url https://docs.example.com
blume audit --url https://docs.example.com --external   # also probe outbound links

Outbound links are graded rather than flatly failed: a 404 is a broken link you can fix, while a 403 or 5xx is usually rate limiting or someone else’s outage and is reported as a warning.

Fixing the findings with an agent

If you use Claude Code or Codex, the audit can hand its findings straight to it:

blume audit --claude   # or --codex

This writes the complete JSON report — every affected page, not the terminal’s three-page preview — to a file and opens the agent interactively with a prompt that walks it through the findings: edit the source file each finding names, apply its suggested fix, then run blume build and blume audit again until the report is clean. The session is interactive by design: you review the edits through the agent’s own permission flow, and the agent is told never to fix a finding by deleting content.

--only and --skip narrow the handoff the same way they narrow the report, so you can send one category at a time.

What it does and doesn’t check

The check set is deliberately narrower than a general-purpose SEO crawler’s. Much of what such a crawler reports cannot happen to a Blume site — it never emits rel=nofollow, and Vite’s content-hashed bundles are never missing or redirecting — and reporting those as permanent zeroes would just teach you to ignore the report.

Two limits worth stating plainly:

Structured data is validated for well-formedness (valid JSON, a @context, a @type on every node). Blume does not validate against the full schema.org vocabulary or Google’s rich-results rules.
Core Web Vitals are not checked. They need a real browser, and a flag that quietly measured nothing would be worse than not having one — so blume audit reports the layout-shift causes it can see offline (images with no width/height, oversized assets) and leaves the rest alone for now.

Anything the audit did not run is reported as skipped rather than silently passing:

⊘ network      skipped — pass --url <origin> (11 checks)
⊘ external     skipped — pass --external (2 checks)