CLI

Every Blume command and flag explained in one place — init, dev, build, preview, add, sync, and eject — along with the options each one accepts.

blume <command> [options]

Commands

Common flags

• blume init — in a terminal, walks you through a few questions (where to create the project, site name, template, content sources); each flag below pre-answers its question.
• blume init --yes — skip the prompts and scaffold with defaults (also the behavior in CI or when stdin isn’t a terminal).
• blume init --content-dir <dir> — set the content folder (default docs).
• blume init --template docs|api|sdk|changelog — scaffold from a starter (API reference, SDK, or changelog instead of the plain docs seed).
• blume init --package-manager npm|pnpm|yarn|bun — tailor the printed next-steps to your package manager.
• blume init --eject — scaffold, then eject to a standalone Astro project (falls back to guiding you through blume eject when dependencies aren’t installed yet).
• blume dev --host --port <n> --open
• blume dev --content-dir <dir> — scan a different content folder without editing blume.config.ts.
• blume dev --debug — verbose Astro/Vite logging for troubleshooting.
• blume dev --preview / blume build --preview — include drafts and unpublished CMS content.
• blume build --no-strict — build despite diagnostic errors. By default blume build fails (exit 1) on any error diagnostic, because pages that fail frontmatter validation are dropped from the output; with --no-strict the build succeeds and reports how many pages are missing. blume dev --strict opts dev into the same fail-fast behavior.
• blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs — override the deployment output, adapter, and base path from blume.config.ts.
• blume build --analyze — print the client JavaScript bundle sizes (largest first) after the build.
• blume build --budget-js <kb> --budget-css <kb> — fail the build when total client JavaScript/CSS exceeds the budget, turning a performance target into a CI gate.
• blume build --isolated — build into a throwaway .blume-verify/ runtime (and its own dist/) instead of .blume/, so a running blume dev server and your real dist/ are left untouched. See Verifying while the dev server runs.
• blume preview --host --port <n> — bind the preview server.
• blume sync --force — re-fetch remote sources, dropping the cached snapshot first.
• blume add <item> --force — overwrite files that already exist.
• blume check --preview — include drafts and unpublished CMS content when checking.
• blume check --strict — fail on content diagnostics as well as type errors.
• blume check --isolated — type-check in a throwaway .blume-verify/ runtime so a running blume dev server is left untouched. See Verifying while the dev server runs.
• blume eject --yes — skip the confirmation prompt.
• blume validate --external — also check external links over the network.
• blume validate --strict — exit non-zero on warnings too.
• blume validate --json / blume doctor --json — emit diagnostics as JSON on stdout (with code, severity, file, line/column, and docsUrl) for CI and editor integrations.
• blume audit --fail-on error|warning|info — the CI gate; defaults to error. --strict is an alias for --fail-on warning.
• blume audit --url <origin> — also probe a live deployment for status codes, response headers, and redirect chains.
• blume audit --external — probe outbound links over the network.
• blume audit --only <check|category> / --skip <check|category> — narrow the report while you work through it (comma-separated).
• blume audit --list-checks — print every check the audit can report.
• blume audit --verbose — list every affected page instead of the first few.
• blume audit --json — emit the report as JSON on stdout.
• blume audit --claude / --codex — hand the findings to Claude Code or Codex to fix interactively.

Verifying while the dev server runs

blume dev serves a live Astro server rooted at the generated .blume/ runtime and regenerates it on every change. blume build and blume check regenerate the same .blume/, so running either while the dev server is live would corrupt it — both refuse with an error and exit non-zero:

A `blume dev` server is running at http://localhost:3000; building would
corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
--isolated to build/verify against .blume-verify without touching it.

The --isolated flag is the escape hatch. It relocates the entire generated runtime (and, for build, its output dist/) to a sibling .blume-verify/ directory, so the verification never writes anything the dev server — or your real dist/ — depends on:

# In a second terminal, while `blume dev` is running:
blume check --isolated   # fast: type-check the .astro/config changes
blume build --isolated   # thorough: full production render into .blume-verify/dist

check --isolated is the quick path (Astro type + template diagnostics, no dist/); build --isolated is the heavier one that also catches runtime render errors. Isolated builds skip the deploy post-steps (search index, hosted-provider sync, llms.txt, sitemap/robots, redirects) — a verify only needs to confirm the site compiles and renders, not publish it. --analyze and the --budget-js/--budget-css gates still run, measured against the isolated output. Blume adds .blume-verify/ to your .gitignore automatically.

This is especially useful when a coding agent needs to verify changes while you keep the dev server open. To make plain blume build/blume check isolate without the flag — for example in an agent’s shell — set BLUME_RUNTIME_DIR to the runtime directory to use:

export BLUME_RUNTIME_DIR=.blume-verify

Type-checking

blume check runs astro check over your project. It regenerates the .blume runtime, syncs Astro’s content types, then reports any TypeScript errors — in your blume.config.ts, in custom .astro pages, and in the components they import. It exits non-zero when there are errors, so it works as a typecheck step in CI:

{
  "scripts": {
    "typecheck": "blume check"
  }
}

Add a tsconfig.json extending Astro’s config to your project root so authored pages resolve blume/* imports and virtual modules like blume:data:

{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
}

Without a project tsconfig.json, only the generated runtime is checked.

Validating links

blume validate checks every link discovered in your content:

• Internal page links (/guides/intro, ./sibling) must resolve to a real page — broken ones are reported as errors.
• Anchor links (#section, /guides/intro#setup) must match a heading on the target page — misses are warnings.
• Asset links (/logo.png) are checked against the public/ directory.
• External links are only checked with --external (off by default since it requires the network); dead links (404/410/unreachable) are errors, while rate-limited or transient responses (403/429/5xx/timeout) are warnings.

Auditing the built site

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, and --only/--skip to work through one category at a time. blume audit --list-checks prints the full catalog.

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> (9 checks)
⊘ external     skipped — pass --external (2 checks)