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

```bash
blume <command> [options]
```

## Commands

| Command | Description |
| --- | --- |
| `blume init [dir]` | Scaffold a project (interactive by default). |
| `blume dev` | Start the dev server with hot reload. |
| `blume build` | Build the static (or server) site. |
| `blume preview` | Preview the last build. |
| `blume add <item>` | Install a source component from the registry. |
| `blume sync` | Re-fetch remote content sources and regenerate. |
| `blume eject` | Promote the runtime into a standalone Astro app. |
| `blume check` | Type-check the site with `astro check`. |
| [`blume doctor`](/docs/cli/doctor) | Diagnose config and content problems. |
| [`blume validate`](/docs/cli/validate) | Validate links across your content. |
| [`blume audit`](/docs/cli/audit) | Audit the built site for SEO and health issues. |
| [`blume eval`](/docs/cli/evals) | Test the docs: an agent answers your questions using only the documentation. |
| [`blume translate`](/docs/cli/translate) | Translate docs into the configured locales with a local agent CLI. |
| [`blume version [id]`](/docs/cli/version) | Freeze the current docs as an archived version (no id lists configured versions). |
| [`blume migrate [source]`](/docs/migrating) | Move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume with Claude Code or Codex. |
| [`blume upgrade`](/docs/upgrading) | Move to a new major: bump `blume`, then list the config changes left or hand them to Claude Code or Codex. |

## 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](#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](#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`](/docs/cli/doctor), [`blume validate`](/docs/cli/validate), [`blume audit`](/docs/cli/audit), [`blume eval`](/docs/cli/evals), [`blume translate`](/docs/cli/translate), and [`blume version`](/docs/cli/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](/docs/cli/validate#json-output) 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:

```bash
# 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:

```bash
export BLUME_RUNTIME_DIR=.blume-verify
```

## Type-checking

`blume check` runs [`astro check`](https://docs.astro.build/en/reference/cli-reference/#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:

```json title="package.json"
{
  "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`:

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", "**/*"]
}
```

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