CLI Commands

The holt CLI provides commands for developing and building component storybooks. It wraps Trunk and adds project-aware configuration.

Installation

cargo install holt-cli

Configuration File

Holt looks for holt.toml in the current directory. This lets you run commands from anywhere in your project:

[book]
path = "crates/kit-docs"  # Directory containing Trunk.toml and index.html

[serve]
port = 3000               # Default port (overridable via --port)
open = false              # Default for --open flag

All sections and fields are optional. Without a config file, Holt uses the current directory and default values.

Command-line options override configuration file values.

Commands

holt serve

Start a development server with hot reloading.

holt serve [OPTIONS]

Options:

Option	Default	Description
--port, -p	8080 (or config)	Port to run the server on
--open, -o	false (or config)	Open browser automatically

The server runs Trunk in the directory specified by book.path in your config (or current directory if not set).

Examples:

# Start on default port
holt serve

# Start on custom port
holt serve --port 3000

# Start and open browser
holt serve --open

holt build

Build a static storybook for deployment.

holt build [OPTIONS]

Options:

Option	Default	Description
--release, -r	false	Build in release mode

The build runs Trunk in the directory specified by book.path in your config.

Examples:

# Development build
holt build

# Production build
holt build --release

holt snapshot

Run visual regression tests by capturing screenshots of every story variant. Uses doco to manage a Caddy server and headless Chrome inside Docker containers — the only requirement is a running Docker daemon.

holt snapshot [OPTIONS]

Options:

Option	Description
--check	CI mode: pass/fail only, no saving, no prompts. Exits non-zero.
--headless	Run the browser without a visible window.
--no-headless	Force a visible browser even in non-interactive shells.
--save	Save new/changed screenshots to the baseline directory (default).
--no-save	Don't save screenshots.

Headless mode is auto-detected: if stdout is not a terminal, the browser runs headless.

Baseline Directory:

Screenshots are stored in <book.path>/tests/visual-baselines/ with this structure:

tests/visual-baselines/
├── <story-id>/
│   ├── <variant-name>.png
│   └── ...
└── ...

Exit Codes:

Code	Meaning
0	All screenshots match baselines
1	One or more screenshots differ from baseline

Examples:

# Run snapshot tests interactively
holt snapshot

# CI mode — strict pass/fail
holt snapshot --check

Requirements:

• Docker running

Example Project Setup

For a workspace with your storybook in a subdirectory:

my-project/
├── holt.toml
├── crates/
│   ├── my-lib/
│   └── kit-docs/        # Storybook lives here
│       ├── Trunk.toml
│       ├── index.html
│       └── src/
└── ...

Create holt.toml at the project root:

[book]
path = "crates/kit-docs"

[serve]
port = 3000
open = true

Now you can run holt serve from anywhere in the project.