CLI Reference

All commands accept an optional site directory argument. When omitted, the current directory is used.

braised init

Scaffold a new project interactively.

braised init [dir]

Prompts for site title (required), canonical URL, and description, then creates:

• braised.yaml — site configuration
• nav.yaml — navigation definition
• docs/index.md — a starter page with block syntax examples
• theme/main.css — CSS entry point importing the built-in theme
• package.json — Tailwind dependency for the CSS pipeline

After scaffolding, run npm install before building.

Flags

Flag	Description
--title	Site title (skips prompt)
--url	Canonical URL, e.g. https://docs.example.com (skips prompt)
--description	Site description (skips prompt)

Fails with an error if braised.yaml already exists in the target directory.

braised init-theme

Scaffold a new theme directory.

braised init-theme [name]

Creates a skeleton theme under themes/{name}/ with the following structure:

themes/{name}/
  theme/main.css       ← CSS entry file with braised:theme imports
  layouts/partials/    ← directory for partial overrides
  blocks/              ← directory for custom block templates
  assets/              ← directory for fonts, icons, extra JS
  static/              ← directory for root-level static files

After running, add theme: themes/{name} to braised.yaml.

The name argument defaults to default when omitted. Fails with an error if the theme directory already exists.

braised build

Build the documentation site to the output directory.

braised build [site-dir]

Reads braised.yaml, nav.yaml, and all .md files under docs/, then writes HTML to dist/ (or build.output from braised.yaml).

A broken page is skipped — it never aborts the rest of the build. Exit code is 1 if any page had errors, 0 otherwise.

Flags

Flag	Description
--config <file>	Path to config file (default: braised.yaml in site-dir)
--cpuprofile <file>	Write a CPU profile (analyse with go tool pprof)
--memprofile <file>	Write a heap profile after build

braised serve

Build the site and start a local dev server with live reload.

braised serve [site-dir]

Watches docs/, nav.yaml, and braised.yaml for changes. Connected browsers reload automatically via server-sent events. Default port is 4321.

braised serve --port 8080

Flags

Flag	Description
-p, --port <n>	Port to listen on (default: 4321)
--host <addr>	Address to bind (default: 127.0.0.1; use 0.0.0.0 to expose on LAN)
--config <file>	Path to config file (default: braised.yaml in site-dir)
--pprof-port <n>	Enable pprof debug server on this port; 0 disables it

braised inspect

Diagnose block rendering for a single Markdown file.

braised inspect docs/my-page.md

Prints four sections:

• Resolved source — Markdown after :::include substitutions
• Block tree — every fenced block in the AST with name, props, template source, and child count
• Rendered HTML — final HTML from the block template pipeline
• Diagnostics — all errors and warnings

Use inspect when a block renders unexpectedly or you need to verify that :::include is resolving correctly.

Flags

Flag	Description
--site-dir <dir>	Project root containing braised.yaml (default: search upward from file)
--no-source	Omit the resolved source section
--no-tree	Omit the block tree section
--no-html	Omit the rendered HTML section
--debug	Enable block-parser and render tracing to stderr
--dump-ast	Print the full goldmark AST after parsing
--agent	Show agent diagnostic sections only: llms.txt inclusion, companion .md file, chunks, and artifact index. Mutually exclusive with --no-source, --no-tree, --no-html. Companion .md and artifact sections require a prior braised build.

--agent mode

--agent replaces the standard four sections with agent-specific diagnostics for the given file:

• llms.txt — whether the page is included, where the description comes from (llm_description frontmatter or first paragraph), and the resolved description text.
• companion .md — whether the companion Markdown file exists in dist/ and its size. Requires a prior braised build.
• chunks — every chunk the AST chunker produces for this page: heading, level, first 120 characters of baked content, and hash. This is exactly what the pipeline writes to manifest.jsonl.
• artifacts — whether the page appears in the frontmatter-index artifact, and the resolved layout and in_nav values. Requires a prior braised build.

Use --agent to verify what an agent sees for a specific page before deploying, or to debug why a chunk looks unexpected.

braised mcp

Start a Model Context Protocol server over stdio.

braised mcp

Exposes braised's built-in block syntax, braised.yaml schema, and nav format as MCP resources. AI tools (Claude Desktop, Cursor, and others) can connect to it and answer questions about braised without browsing documentation.

Configure it in your MCP client as a stdio server:

{
  "command": "braised",
  "args": ["mcp"]
}

braised mcp serve

Start a Streamable HTTP MCP server serving built site artifacts.

braised mcp serve [site-dir]

Reads built artifacts from artifacts/ (configurable via braised.yaml) and exposes them as structured MCP tools for AI clients to query.

Requires a prior braised build to populate the artifacts directory. The server binds to 127.0.0.1:8081 by default (configurable via braised.yaml under mcp.serve.host and mcp.serve.port).

Built-in tools

Tool	Description
get_nav_structure	Returns the full site navigation tree as JSON.
get_page_index	Returns all pages with title, URL, and metadata.
get_theme_variables	Returns all CSS custom properties with defaults.
get_page(path)	Returns raw Markdown source for a specific page URL.

Custom artifacts

Artifacts with an mcp_tool block are auto-registered as tools. This allows custom generators (Step 6) to expose domain-specific data to AI clients.

Graceful shutdown

On SIGTERM, the server drains in-flight requests with a 10-second deadline, then exits cleanly.

Logging

All operations are logged as JSON to stdout via slog, including tool calls, artifact sizes, and startup diagnostics.

Flags

Flag	Description
--site	Path to the braised site directory (default: current directory)