ContactSign inSign up
Contact

Chromatic CLI

The Chromatic CLI manages the visual testing and review process.

Usage with Storybook

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

The CLI defaults to running with Storybook. It builds and uploads your Storybook to Chromatic’s cloud infrastructure, to start the publish and visual test workflows.

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.

If you don’t install chromatic as a dependency, npx automatically downloads and runs the latest version. This means you’ll always have the newest features but might experience slightly slower startup times due to the download.

Usage with Playwright or Cypress

When pairing Chromatic with Playwright or Cypress, you have to pass the corresponding flag: --playwright or --cypress. Chromatic captures an archive of your UI (DOM, styles, and assets) while Playwright or Cypress runs your E2E tests. The CLI uploads the archive to the Chromatic cloud infrastructure to run visual testing.

# For Chromatic with Playwright
$ npx chromatic --project-token <your-project-token> --playwright

# For Chromatic with Cypress
$ npx chromatic --project-token <your-project-token> --cypress

For Playwright and Cypress, we recommend installing the chromatic package as a dependency. This ensures that the CLI is in sync with the @chromatic-com/playwright or @chromatic-com/cypress package.

Installing

npm install chromatic --save-dev

Configuring the CLI

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

Note: some options are only available as flags. For a full list of available options, please refer to the configuration reference page.

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).

Flags

  • Flags take precedence over options specified in the config file and GitHub Action.

  • Passing a flag without value is treated as true. e.g.:

    $ npx chromatic --dry-run -t <your-project-token>
    
  • Where an array is accepted, specify the flag multiple times (once for each value). e.g.:

    $ npx chromatic --externals "my-folder/**" --externals "another-folder/**" -t <your-project-token>
    

Chromatic Config File

The configuration file is stored in the root of your project folder as ./chromatic.config.json. You can use the --config-file flag to customize the Chromatic configuration file name and path.

If you aren’t using CI (yet), you just need the minimum setup:

chromatic.config.json
{
  "$schema": "https://www.chromatic.com/config-file.schema.json",
  "projectId": "Project:..."
}

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
{
  "$schema": "https://www.chromatic.com/config-file.schema.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
{
  "$schema": "https://www.chromatic.com/config-file.schema.json",
  "projectId": "Project:...",
  "externals": ["public/**"],
  "junitReport": true,
  "onlyChanged": true
}

JSON schema for the config file

We provide a JSON schema for the Chromatic config file at: https://www.chromatic.com/config-file.schema.json. You can use this schema to validate your configuration file directly in your editor. To enable this, add the following to your settings.json.

This will give you IntelliSense suggestions as you type, and your editor will perform both structural and value verification.

chromatic.config.json
{
  "$schema": "https://www.chromatic.com/config-file.schema.json"
  /* ... config options */
}

Authentication

Chromatic builds are authenticated using your project’s secret project token. You can access your project token from the Chromatic website during onboarding or from your project’s Manage page.

Continuous Integration

To set up CI, store your project token as the CHROMATIC_PROJECT_TOKEN environment variable or secret. The CLI automatically recognizes this variable, so you won’t have to provide it explicitly.

Visual Tests addon

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.

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
21STORYBOOK_BUILD_FAILEDFailed to run build-storybook script
22STORYBOOK_START_FAILEDFailed to start Storybook
23STORYBOOK_BROKENUnable to load Storybook or one of the stories
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
210MISSING_DEPENDENCYDependency issue
220VERIFICATION_TIMEOUTBuild verification timeout
254INVALID_OPTIONSInvalid options (flags) provided
255UNKNOWN_ERRORUnknown error

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.

Flags to help diagnose build issues with the CLI
  • --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-file: 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-file.
  • --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 specific stories 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.