CLI reference

plasmoid has two verbs: build and serve.

`plasmoid build`

Render a docs tree into a complete static site.

plasmoid build --docs ./docs --site ./public [--version X.Y.Z] \
  [--palette NAME] [--themes-dir DIR]

Option	Default	Description
`--docs <DIR>`	`./docs`	Docs directory (must contain `plasmoid.toml`).
`--site <DIR>`	—	Output directory for the built site.
`--version <V>`	from `Cargo.toml`	Override the resolved version. Required when `[versions] source = "manual"`.
`--palette <NAME>`	from `[theme] palette`	Tone to emit, overriding the config. Resolved from `docs/themes/<name>.css`, then `--themes-dir`/`[theme] themes_dir`, then the built-in `default`.
`--themes-dir <DIR>`	from `[theme] themes_dir`	External theme library (holds `tokens.base.css` + `themes/<tone>.css`), overriding the config. A relative path resolves against the current directory.

The build is deterministic and offline: same inputs, byte-identical output, no network. See The build pipeline.

`plasmoid serve`

Build the site and serve it locally for preview, optionally rebuilding on change.

plasmoid serve --docs ./docs [--port 8080] [--watch] [--palette NAME] [--themes-dir DIR]

Option	Default	Description
`--docs <DIR>`	`./docs`	Docs directory to build and serve.
`--port <N>`	`8080`	Port for the local preview server.
`--watch`	off	Rebuild and live-reload on file changes.
`--palette <NAME>`	from `[theme] palette`	Tone to preview, overriding the config (same as `build --palette`).
`--themes-dir <DIR>`	from `[theme] themes_dir`	External theme library to preview from, overriding the config (same as `build --themes-dir`).

--palette and --themes-dir make it easy to preview a different tone locally without editing the config — and --palette alone is enough when [theme] themes_dir is already set, since it just swaps the tone resolved from that library.

serve builds into a temporary preview directory and serves it over a tiny built-in HTTP server. With --watch, edits trigger a rebuild and connected browsers reload automatically.

Exit status

Both verbs exit non-zero with an actionable message on error — a bad config field, an unreadable file, or a version that can’t be resolved. Error messages name the offending file or field so you can fix it directly.

Examples

# One-off production build
plasmoid build --docs ./docs --site ./public

# Build a non-Rust project at an explicit version
plasmoid build --docs ./docs --site ./public --version 2.4.0

# Live-editing preview on a custom port
plasmoid serve --docs ./docs --watch --port 4000