CLI

The Blume command-line interface.

blume <command> [options]

Commands

Common flags

• blume init --content-dir <dir> --yes — set the content folder (default docs) and skip prompts.
• 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 --strict — fail the build on diagnostic errors (also works on blume dev).
• 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.

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 against .blume; building would corrupt it.
Stop the dev server, 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. 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.