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 snapshot tests by capturing screenshots of every story variant.

holt snapshot [OPTIONS]

Options:

Option	Default	Description
--port, -p	8080 (or config)	Port to run the server on

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

Environment Variables:

Variable	Effect
CI	Enables headless mode; saves new screenshots silently

In CI mode, differing screenshots are written to the baseline directory so they can be uploaded as artifacts for review.

Examples:

# Run snapshot tests
holt snapshot

# Run on a custom port
holt snapshot --port 4000

Requirements:

• Firefox installed
• geckodriver in PATH

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.