Doctor

blume doctor diagnoses configuration and content problems before you build — the config, every page, the Node version, and features that need a server.

blume doctor scans the project exactly as blume build would and reports what it finds, without generating or building anything. It’s the first thing to run when a build fails for a reason that isn’t obvious, and a cheap gate to keep in CI:

blume doctor

blume init also adds it to package.json as a doctor script. With pnpm, run that as pnpm run doctor (pnpm --filter <workspace> run doctor from a monorepo root): a bare pnpm doctor runs pnpm’s own built-in doctor command instead of the script.

What it checks

The Node version against the range the installed blume package supports, read from its own engines field. A version outside it is a warning: things may work, but it isn’t a combination Blume tests.
blume.config.ts, with the same validation a build runs. A removed or renamed key fails with a hint naming its replacement rather than a bare “unrecognized key”.
Every content page and folder meta: the diagnostics blume dev and blume build print as they load the project — invalid frontmatter, .mdx that doesn’t parse, navigation problems, missing include targets, and the rest — collected in one report.
Navigation that leads nowhere: a tab, selector item, featured link, header action, or call to action whose path matches no page, custom .astro page, generated route, reference, public/ file, or file Blume generates: a warning (BLUME_NAV_MISSING_PAGE), the same one blume dev and blume build print. A tab is checked where it links: its href when it has one, else its path.
<Component> examples that don’t exist: a path that names no file under examples, which the page would show as a “No example found” box: a warning (BLUME_EXAMPLE_NOT_FOUND) at its line, as blume dev and blume build print it. A components.ts override or island named Component replaces the built-in, and isn’t checked.
Features that need a server on a site configured for static output — the assistant, the MCP server, the Try it playground’s built-in proxy, or server-mode search (Mixedbread): an error naming the feature, with the deployment adapter to switch to (or, when a host adapter is set to output: "static", telling you to drop that option).
Packages your config needs that aren’t installed — the SDK a search, content source, assistant, or narration adapter imports, a deployment adapter’s @astrojs/* package, or the renderer for Vue or Svelte islands: an error naming each package, with the install command for your package manager. blume build stops on the same check.
components.ts overrides Blume can’t plan — an inline or computed entry, or an import whose file doesn’t exist: an error for each, at its line.
A version-shaped folder (v1.0/) on a site with no versions configured, which would otherwise build as ordinary content: a warning pointing at blume version.
Secrets an enabled feature reads that aren’t set, such as MIXEDBREAD_API_KEY or OPENROUTER_API_KEY: a warning naming the variable. Doctor loads .env and .env.local first, like blume dev and blume build, and checks before any remote content source fetches, so the warning still prints when a source then fails without its token.

The summary

After the diagnostics, doctor prints what the project resolved to, so a mismatch between what you think is configured and what Blume sees is visible at a glance: the page count, the output mode and deployment adapter, the search provider, the configured reference, analytics, and content source adapters, and whether the assistant is on and which backend it uses.

Exit code and JSON

Doctor exits non-zero when there are error diagnostics, so it fails CI on the same problems a build would; warnings are reported and don’t fail. --json emits the diagnostics as JSON on stdout instead of the terminal report, in the same shape blume validate --json uses.