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

yarn add --dev chromatic

pnpm add --save-dev chromatic

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.

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:

{
  "$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:

{
  "$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:

{
  "$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.

{
  "$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

Troubleshooting