---
title: CLI
description: Every Blume command and flag explained in one place, along with the options each one accepts.
---

```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` | Diagnose config and content problems. |
| `blume validate` | Validate links across your content. |
| `blume audit` | Audit the built site for SEO and health issues. |
| `blume eval` | Test the docs: an agent answers your questions using only the documentation. |
| `blume translate` | Translate docs into the configured locales with a local agent CLI. |
| `blume version [id]` | Freeze the current docs as an [archived version](/docs/content/versioning) (no id lists configured versions). |

## 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](#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.
- `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 with each finding's full detail, such as which link target is broken.
- `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.
- `blume eval` — run the questions in `evals.yaml` through an agent that reads only your docs; see [Evals](/docs/reference/eval).
- `blume eval init` — have the agent draft a starter `evals.yaml` from your docs.
- `blume eval --agent claude|codex --threshold <0..1> --timeout <seconds> --json --fix --verbose` — see [Evals](/docs/reference/eval) for each flag.
- `blume translate --claude` / `--codex` — translate missing and outdated pages into your configured locales; see [Translate](/docs/reference/translate).
- `blume translate --check` — report translation drift and exit non-zero (the CI gate), without running an agent.
- `blume translate --locale <codes> --concurrency <n> --force --timeout <seconds> --json` — see [Translate](/docs/reference/translate) for each flag.

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

```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", ".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** are checked where the file lives: an absolute path (`/logo.png`) against the `public/` directory, a relative image embed (`![](./diagram.png)`) against the page's own folder. A plain link to a relative path still resolves as a site route — only image embeds go through the image pipeline.
- **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:

```bash
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 with its full detail, 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:

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

```bash
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](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli), the audit can hand its findings straight to it:

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