Overview

Every Blume command in one place, the flags each one accepts, and how to verify a site while the dev server keeps running.

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 — install with, and print next-steps for, a specific package manager (default: whichever ran blume init).
• blume init --no-install — write the files but skip the dependency install, for CI or custom dependency workflows. By default blume init runs the package manager’s install so the project is ready to run; if the install fails, the scaffold is kept, the retry command is printed, and the exit code is non-zero.
• blume init --eject — scaffold, then eject to a standalone Astro project (with --no-install, falls back to guiding you through blume eject once dependencies are installed).
• 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 --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.

The commands with a page of their own list every flag there: blume doctor, blume validate, blume audit, blume eval, blume translate, and blume version. blume validate, blume doctor, blume audit, blume eval, and blume translate take --json to print machine-readable results on stdout for CI and editor integrations (see Validate for the diagnostics shape); build, check, and dev report to the terminal only. Every command rejects a flag it doesn’t take, suggesting the closest match and listing the flags it accepts, so a typo like --isolatd fails instead of being ignored.

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:4321; 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", "**/*"]
}

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