chromaui/chromatic-docs/run-build

Run a Chromatic build

Builds come from the Chromatic CLI, never from the MCP. Running one here turns the fix-and-verify loop from a CI round trip into one command.

Every build spends snapshots from the account's quota. Say what will run and how it is limited, and get the user's yes before each build. Never loop builds unattended.

Before you start

• The CLI. Use the version the repository pins: look for chromatic in

package.json and run it with the repository's package manager (npx chromatic, yarn chromatic, pnpm exec chromatic). If it is not a dependency, ask before running npx chromatic@latest.

• The project token. The CLI reads it from CHROMATIC_PROJECT_TOKEN.

Check that the variable is set without printing it: test -n "$CHROMATIC_PROJECT_TOKEN" && echo set || echo missing. If it is missing, ask the user to make it available to this agent's shell, for example by exporting it before starting the agent. It is on the project's Manage page in Chromatic. Never ask them to paste it into the conversation, never write it to a file, and never pass it on the command line where it lands in shell history.

• This is not the MCP login. The project token is what the CLI and CI

authenticate with. The Chromatic MCP does not accept it, and results are read through the MCP, not the token.

Steps

1. Pick the scope. Prefer the narrowest that verifies the work:

• Stories named: --only-story-names "<Title>/<Story>", repeatable, globs

allowed ("Components/Button/*"). The name is the component's title and the story's name, joined by a slash.

• Story files: --only-story-files <path>, relative to the Storybook

project root, repeatable.

• Everything the branch touched: --only-changed (TurboSnap).

Story names and titles come from the repository and from Chromatic, not from you. Pass each one as a single quoted argument, and refuse any that contains a quote, backtick, $ or newline.

Tell the user the scope and wait for a yes.

1. Run it. For example:

`` npx chromatic --only-story-names "Components/Button/*" ``

The CLI builds Storybook, uploads it, and waits for the tests. This takes minutes; run it in the background if you can, and do not start a second build while one runs. Add --exit-once-uploaded only when the user wants the command back as soon as the upload finishes.

1. Read the exit code.

Any other code: show the last lines of the CLI's output.

1. Read the results through the MCP. The CLI prints the build number and

link. Call chromatic_get_latest_build for this branch; for the stories themselves, use the skill the table points to.

Why did TurboSnap test so much?

Run with --only-changed --diagnostics-file. The file it writes (chromatic-diagnostics.json by default) holds a turboSnap section. When TurboSnap gave up, turboSnap.bailReason says why: for example a changed package or lock file, a file matched by --externals, no ancestor build to compare against, or a rebuild. Read that section only, and report it in plain words. The CLI's own output says the same thing in prose. The public API does not expose it, so the MCP cannot answer this question.

The diagnostics file describes the whole run. Do not paste it whole, and do not commit it.