Sign inSign up
Introduction

Chromatic CLI

The Chromatic CLI builds and publishes your Storybook. Run chromatic in your project directory.

Quick Start

npx chromatic --project-token <your-project-token>

If you customize the way your Storybook runs, you may need to pass additional options. After the first run, the CLI will automatically ask you to add a script to your package.json.

Installing

Optionally, you can install chromatic as a dependency while using the same script above.

npm install -D chromatic

If you don’t install chromatic as a dependency, npx will automatically download and run the latest version. This has pros and cons:

  • 👍 You’ll never be out of date, you’ll use the latest version every time, never have to worry about upgrading Chromatic.
  • 👍 You won’t need to install the package during local development if you’re only running it in continuous integration.
  • 👎 It will be slower to run because the package has to be downloaded first.

Configuration

Chromatic CLI can be configured through options in ./chromatic.config.json file (recommended) placed at the root of your project folder, or by passing CLI flags.

For use in CI, the only required option is the project token. Get your project token from the Chromatic website during onboarding or on your project’s Manage page. Store your project token as the CHROMATIC_PROJECT_TOKEN environment variable or secret. The CLI automatically picks up the CHROMATIC_PROJECT_TOKEN environment variable so you won’t have to explicitly provide it.

For local builds with the Visual Tests addon, your personal OAuth token (with which you authenticated the addon) is used instead of the project token.

A full-featured ./chromatic.config.json file in a CI workflow where all changes to main happen through a pull request may look like this:

// ./chromatic.config.json

{
  "projectId": "Project:...",
  "autoAcceptChanges": "main",
  "exitOnceUploaded": true,
  "externals": ["public/**"],
  "onlyChanged": true,
  "skip": "dependabot/**"
}

For unlinked projects that rely on the CI script to report build results, the recommended setup looks like this:

// ./chromatic.config.json

{
  "projectId": "Project:...",
  "externals": ["public/**"],
  "junitReport": true,
  "onlyChanged": true
}

If you aren’t using CI (yet), you are better off with the minimum setup:

// ./chromatic.config.json

{
  "projectId": "Project:..."
}

You can use the --config-file flag to customize the Chromatic configuration file path.

Flags must be passed as --kebab-case whereas options are camelCase. Flags take precedence over configuration options. When passing a flag without value, it is treated as true. Where an array is accepted, specify the flag multiple times (once for each value).

Configuration options

These options control how Chromatic behaves. See also branching docs and diagnosing issues for when to use some of these flags. Some options are only available as a flag or as an input to the GitHub Action.

Option / FlagDescriptionTypeExample valueDefault value
autoAcceptChanges
--auto-accept-changes
If there are any changes to the build, automatically accept them. Only for given branch, if specified.glob or boolean"main" or truefalse
branchName
--branch-name
Override the branch name for certain CI providers or cross-fork PR comparisons. Also accepts <owner>:<branch>.string"my-branch"Inferred from CI or Git
buildScriptName
--build-script-name (-b)
The npm script that builds your Storybook. Use this if your Storybook build script is named differently.string"build:storybook""build-storybook"
configFile (Node.js API only)
--config-file
Path from where to load the Chromatic config JSON file.string"config/chromatic.json""chromatic.config.json"
debug
--debug
Output verbose debugging information. This option implies interactive: false.booleantruefalse
diagnosticsFile
--diagnostics-file
Write process context information to a JSON file. Default target is chromatic-diagnostics.json, if enabled.string or boolean"debug.json" or truefalse
dryRun
--dry-run
Run without actually publishing to Chromatic.booleantruefalse
exitOnceUploaded
--exit-once-uploaded
Exit with status 0 (OK) once the built version has been published to Chromatic. Only for given branch, if specified.glob or boolean"my-branch" or truefalse
exitZeroOnChanges
--exit-zero-on-changes
If all snapshots render, but there are visual changes, exit with code 0 rather than the usual exit code 1. Only for given branch, if specified.glob or boolean"!(main)" or truefalse
externals
--externals
Disable [TurboSnap] when any of these files have changed since the baseline build. Requires onlyChanged.glob or array thereof"my-folder/**"
forceRebuild
--force-rebuild
Do not skip build when a rebuild is detected. Only for given branch, if specified.glob or boolean"my-branch" or truefalse
fromCI
--ci
Mark the build as coming from CI.booleantrueInferred from CI
ignoreLastBuildOnBranch
--ignore-last-build-on-branch
Do not use the last build on this branch as a baseline if it is no longer in history (i.e., the branch was rebased).glob"my-branch"
interactive: false
--no-interactive
Don’t ask interactive questions about your setup, and don’t overwrite output. true in non-TTY environments.booleanfalseInferred from TTY
isLocalBuild (Node.js API only)
Mark the build as “local”.booleantruefalse
junitReport
--junit-report
Write build results to a JUnit XML file. Default target is chromatic-build-{buildNumber}.xml, if enabled. {buildNumber} will be replaced with the actual build number.string or boolean"report.xml" or truefalse
logFile
--log-file
Write CLI logs to a file. Default target is chromatic.log, if enabled.string or boolean"logs.txt" or truefalse
onlyChanged
--only-changed
Enables [TurboSnap]: Only run stories affected by files and dependencies changed since the baseline build. Only for given branch, if specified.glob or booleantruefalse
onlyStoryFiles
--only-story-files
Only run a single story or a subset of stories by their filename(s). Specify the full path to the story file relative to the root of your Storybook project.glob or array thereof"src/ui/**"
onlyStoryNames
--only-story-names
Only run a single story or a subset of stories by their name.glob or array thereof"Atoms/Button/*"
outputDir
--output-dir (-o)
Relative path to target directory for building your Storybook. Use this if you want to preserve it for other tasks.string"storybook-static"Temporary directory
--patch-buildCreate a patch build to fix a missing PR comparison.string"my-feature...main"
projectIdThe unique identifier for your project, sometimes referred to as appId.string"Project:5d67dc0374b2e300209c41e7"
projectToken
--project-token (-t)
The secret token for your project. Prefer to use CHROMATIC_PROJECT_TOKEN instead if you can.string"chpt_b2aef0123456789"Environment variable
repositorySlug
--repository-slug
Override the repository slug. This is mainly used to correctly handle cross-fork builds, where the owner deviates.string"owner/repositoryName"Inferred from CI or Git
skip
--skip
Skip Chromatic tests, but mark the commit as passing. It avoids blocking PRs due to required merge checks. Only for given branch, if specified.glob or boolean"my-branch" or truefalse
storybookBaseDir
--storybook-base-dir
Relative path from repository root to Storybook project root. Use with onlyChanged and storybookBuildDir when your Storybook is located in a subdirectory of your repository.string"src/ui"
storybookBuildDir
--storybook-build-dir (-d)
If you have already built your Storybook, provide the path to the static build directory.string"dist/storybook"
storybookConfigDir
--storybook-config-dir
Relative path from where you run Chromatic to your Storybook config directory. Use with onlyChanged and storybookBuildDir when using a custom --config-dir (-c) flag for Storybook.string"storybook-config"".storybook"
storybookLogFile
--storybook-log-file
Write Storybook build logs to a custom file path.string or boolean"sb.txt" or true"build-storybook.log"
traceChanged
--trace-changed
Print dependency trace for changed files to affected story files. Set to “expanded” to list individual modules. Requires onlyChanged.string or boolean"expanded" or truefalse
workingDir
--working-dir
Provide the location of Storybook’s package.json if installed in a subdirectory (i.e., monorepos).string"my-folder"process.cwd()
untraced
--untraced
Disregard these files and their dependencies when tracing dependent stories for [TurboSnap]. Requires onlyChanged.glob or array thereof"my-folder/**"
uploadMetadata
--upload-metadata
Upload Chromatic metadata files as part of the published Storybook. This option implies diagnosticsFile: true and logFile: true.booleantruefalse
zip
--zip
Publish your Storybook to Chromatic as a single zip file instead of individual content files.booleantruefalse
playwright
--playwright
Use your Playwright tests to power visual tests with Chromatic. Learn morebooleantruefalse
cypress
--cypress
Use your Cypress tests to power visual tests with Chromatic. Learn morebooleantruefalse

Where supported, globs are handled via picomatch.

Environment variables

Some options can be configured through environment variables. You will typically only need these when instructed to. Flags take precedence over environment variables. Environment variables are also read from a .env file if present.

Environment variableDescription
CHROMATIC_PROJECT_TOKENProject token, see --project-token
CHROMATIC_SHAGit commit hash. See troubleshooting guide for issues
CHROMATIC_BRANCHGit branch name. See --branch-name for additional options and troubleshooting guide for issues
CHROMATIC_SLUGGit repository slug (e.g., chromaui/chromatic-cli). See troubleshooting guide for issues
CHROMATIC_POLL_INTERVALPolling interval when waiting for the build to finish (default: 1000)
CHROMATIC_OUTPUT_INTERVALFrequency of progress output while polling or uploading (default: 10000)
CHROMATIC_RETRIESNumber of times to retry file upload (default: 5)
CHROMATIC_STORYBOOK_VERSIONOverrides Storybook package/version detection (e.g. @storybook/react@7.0.1-alpha.25)
CHROMATIC_TIMEOUTNumber of ms before giving up on storybook dev (default: 300000 (5 minutes))
STORYBOOK_BUILD_TIMEOUTNumber of ms before giving up on storybook build (default: 600000 (10 minutes))
CHROMATIC_DNS_SERVERSOverrides the DNS server IP address(es) used by node-fetch, comma-separated. See troubleshooting guide for issues
CHROMATIC_DNS_FAILOVER_SERVERSFallback DNS server IPs (default: 1.1.1.1, 8.8.8.8 (Cloudflare, Google)). See troubleshooting guide for issues
CISee --ci
LOG_LEVELOne of: silent, error, warn, info, debug
DISABLE_LOGGINGSet to true to disable logging. Equal to LOG_LEVEL=silent
HTTPS_PROXY or HTTP_PROXYUsed to configure https-proxy-agent. See troubleshooting guide for issues
CHROMATIC_ARCHIVE_LOCATIONChange the default location for archives generated by Playwright or Cypress tests
STORYBOOK_NODE_ENVSpecify a different environment for building Storybook in (default is production). Note that changing this value might slow down your builds or even alter the build behavior.

Exit codes

Exit codeKeyDescription
0OKExited successfully
1BUILD_HAS_CHANGESChromatic build has (visual) changes
2BUILD_HAS_ERRORSChromatic build has component errors
3BUILD_FAILEDChromatic build failed due to system error
4BUILD_NO_STORIESChromatic build failed because it contained no stories
5BUILD_WAS_LIMITEDChromatic build was limited
6BUILD_WAS_CANCELEDChromatic build was canceled
11ACCOUNT_QUOTA_REACHEDChromatic account reached its snapshot quota
12ACCOUNT_PAYMENT_REQUIREDChromatic account requires payment
101GIT_NOT_CLEANGit repository workspace not clean
102GIT_OUT_OF_DATEGit repository not up-to-date with remote
103GIT_NO_MERGE_BASEGit branch has no merge base
104NPM_INSTALL_FAILEDnpm or Yarn failed to install dependencies
105NPM_BUILD_STORYBOOK_FAILEDnpm or Yarn failed to run build-storybook script
201FETCH_ERRORHTTP fetch error
202GRAPHQL_ERRORGrahpQL API error
254INVALID_OPTIONSInvalid options (flags) provided
255UNKNOWN_ERRORUnknown error

Deprecated options

The following options are still supported but will be removed in a future version. If your project still uses them, we encourage you to remove them from your scripts or configuration at your earliest convenience.

CLI flag
--allow-console-errorsContinue running Chromatic even if Storybook logs errors in the console.
--app-code <token>Renamed to --project-token.
--listList available stories. This requires running a full build.

Unsupported options

The options listed below are no longer supported by our CLI and will not yield any result if you provide them in your project. We recommend removing them from your scripts and configuration.

CLI flag
--do-not-startDon’t attempt to start or build Storybook. Use this if your Storybook is already running, for example, when part of a larger app. Alias: -S
--exec <command>Alternatively, a shell command that starts your Storybook. Alias: -e
--preserve-missing-specsPreserve missing stories when publishing a partial Storybook.
--script-name [name]The npm script that starts your Storybook. Defaults to storybook. Alias: -s
--storybook-port <port>What port is your Storybook running on. Auto detected from the npm script when using --script-name. Alias: -p
--storybook-httpsEnable if Storybook runs on HTTPS (locally). Auto detected from the npm script when using --script-name.
--storybook-cert <path>Use with --storybook-https. Auto detected from the npm script when using --script-name.
--storybook-key <path>Use with --storybook-https. Auto detected from the npm script when using --script-name.
--storybook-ca <ca>Use with --storybook-https. Auto detected from the npm script when using --script-name.
--storybook-url <url>Run against an online Storybook at some URL. This implies --do-not-start. Alias: -u

Diagnosing issues

Getting your Chromatic CI script configured just right can take some trial and error. To help debug issues, you may want to consider using some of the debug flags:

  • --no-interactive: When running the CLI locally, use this flag to get logs like you would in CI, which are more elaborate than the interactive logs. This is automatically enabled in CI, so adding it to a CI script is useless.
  • --diagnostics: Before terminating the process, this dumps process context information to chromatic-diagnostics.json. This is the first place to look if you see things you didn’t expect. In a CI system, you’ll have to configure this file as a build artifact so you can download it. How to do this depends on your CI provider.
  • --dry-run: Use this if you want to debug the CLI without actually publishing your Storybook or running a Chromatic build. Typically you’d pair this with --diagnostics.
  • --debug: This enables verbose logging and --no-interactive. Use this if you want to see the nitty-gritty details. Primarily useful if you have issues publishing (uploading) your Storybook to Chromatic.
  • --trace-changed: Specifically for TurboSnap, you can use this flag to get a printed tree view of the dependencies between changed files (according to Git) and your story files.
  • --only-story-names: If you have some specific stories which are causing problems, you can use this flag to run a build for just those stories (one or more). If you don’t know which stories are available, you can use --list to print a list of all stories in your Storybook, though it will require running a Chromatic build.

Migrating to the new CLI package

This package was previously named storybook-chromatic. If you still have storybook-chromatic installed, you should remove it and install chromatic instead:

With npm:

npm uninstall --save-dev storybook-chromatic
npm install --save-dev chromatic

With yarn:

yarn remove storybook-chromatic
yarn add --dev chromatic

Troubleshooting

I see "Chromatic: Failed to publish. Reason: self signed certificate in certificate chain" when running the CLI on my machine.

This isn’t a Chromatic CLI issue. Check if your machine is using special security or network settings before running the CLI.

I see "ENOTFOUND" when running the CLI on my machine

By default, DNS resolution is handled by the environment system. If you are experiencing DNS issues (i.e. ENOTFOUND), the CLI will try and switch from the operating system DNS lookup (i.e., dns.lookup) to network DNS resolve (i.e., dns.resolve). If this also fails, the CLI will add CHROMATIC_DNS_FAILOVER_SERVERS to the list of available DNS servers and try again. For additional information regarding Node’s DNS implementation, please refer to their documentation.

Why are Git environment variables not working with the CLI?

If you’ve configured the Chromatic CLI to run with one of the Git environment variables (i.e.,CHROMATIC_SHA, CHROMATIC_BRANCH, CHROMATIC_SLUG), you must configure all three. Otherwise, Chromatic will ignore them when running the build.