CLI

The stageboard CLI starts the board, renders stories and flows to PNGs, runs the MCP server and installs the agent skill. Run it with npx stageboard <command>; npx stageboard --help and npx stageboard <command> --help list the options.

Every command except init and skill reads stageboard.config.ts (or .mts, .js, .mjs), searching upward from the current folder.

devCopy Anchor Link

stageboard dev [--port <port>] [--host <host>]

Starts the board (Screens, Flows, Components), the agent bridge and the Vite dev server, and prints the catalog URL, the public URL if set, and the agent provider.

The board is at http://localhost:6060/__stageboard/. STAGEBOARD_PUBLIC_URL (or publicUrl in the config) sets the URL printed as public and used for hot reload behind a proxy.

npx stageboard dev --port 7070

shotCopy Anchor Link

stageboard shot <story> [--variant <id=key>]... [--width <px>] [--height <px>] [--full] [--theme <theme>] [--scale <n>] [--out <file>]

Renders one story in headless Chromium and writes a PNG. <story> is a story id, file#Export (for example src/hero.stories.tsx#Default), or a search term that matches exactly one story. It uses the running stageboard dev server if there is one, and starts a temporary one otherwise, so the app does not need to run.

It prints the PNG path on stdout, and console errors from the story on stderr. Without --full, it clips to the story's stage unless the story's layout is fullscreen. Chromium is found from Playwright, STAGEBOARD_CHROME, CHROME_PATH or a system install; if none exists, run npx playwright install chromium.

npx stageboard shot landing-hero--default --variant landing.hero=hero.calm --width 1440 --full --out /tmp/hero.png

flowCopy Anchor Link

stageboard flow shot <flow> [--device <device>] [--theme <theme>] [--cols <n>] [--out <file>]
stageboard flow save <json or file>

flow shot renders every screen of a flow, in order, into one grid image. <flow> is a flow id or name (a unique part of the name works). Before capturing a step, it plays the step's actions. It prints the PNG path, then the flow as text: each step's title, story id, route and note, and every action marked ✓ (played), ✗ (failed, with the reason) or · (not played).

npx stageboard flow shot "Sign up" --device mobile

flow save saves a flow to stageboard/board.json through the running stageboard dev server. The argument is the JSON itself or a path to a JSON file. Pass "flow": "<id>" to update a flow; omit it to add one. The fields are the same as the MCP tool save_flow.

npx stageboard flow save '{ "name": "Sign up", "group": "Onboarding", "steps": [{ "storyId": "pages-signup--default", "note": "The user enters an email", "actions": [{ "do": "click", "target": "Continue" }] }, { "pending": "Check your inbox" }] }'

See Flows.

framesCopy Anchor Link

stageboard frames [filter] [--write]

Measures what every component story draws and gives it a frame, parameters.viewport, that fits: the content plus 40px on each side, with room for a menu, popover or dialog it opens, grown if the story lays out larger at that size. Each file gets one frame that fits all its stories, and a story much smaller than that gets its own. filter matches id, title or file. Like shot, it uses the running stageboard dev server or starts a temporary one. See Component frames.

npx stageboard frames --write

listCopy Anchor Link

stageboard list [filter] [--json]

Lists every story: its id, its file, and page for page stories. filter matches id, title or name, case-insensitive.

npx stageboard list hero

mcpCopy Anchor Link

stageboard mcp

Runs the stageboard MCP server on stdio. See MCP server.

npx stageboard mcp

doneCopy Anchor Link

stageboard done <job> [summary] [--failed]

Tells the running stageboard dev server that an agent job is finished, so the board stops showing it as running. Agents run this as their last step when they don't have the MCP tool complete_job.

npx stageboard done 3f9c2a1b "Made the hero title two lines on mobile"

skillCopy Anchor Link

stageboard skill [dir] [--claude] [--codex]

Installs the stageboard agent skill into .claude/skills/stageboard and .agents/skills/stageboard under dir (default: the current folder), replacing an existing copy.

npx stageboard skill --claude

variantsCopy Anchor Link

stageboard variants

Regenerates the variants registry file (variantsFile, default stageboard.variants.ts) from the *.variant.tsx files. stageboard dev does this on its own; run it after adding or removing variants without the dev server.

npx stageboard variants

See Variants.

initCopy Anchor Link

stageboard init

Creates stageboard.config.ts in the current folder, unless one already exists:

import { defineConfig } from "stageboard"

export default defineConfig({
  stories: ["src/**/*.stories.tsx"],
  preview: "./stageboard.preview.tsx",
  agent: { provider: "claude" },
})

npx stageboard init

See Configuration.