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 / Flag | Description | Type | Example value | Default 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 true | false |
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 . | boolean | true | false |
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 true | false |
dryRun--dry-run | Run without actually publishing to Chromatic. | boolean | true | false |
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 true | false |
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 true | false |
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 true | false |
fromCI--ci | Mark the build as coming from CI. | boolean | true | Inferred 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. | boolean | false | Inferred from TTY |
isLocalBuild (Node.js API only) | Mark the build as “local”. | boolean | true | false |
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 true | false |
logFile--log-file | Write CLI logs to a file. Default target is chromatic.log , if enabled. | string or boolean | "logs.txt" or true | false |
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 boolean | true | false |
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-build | Create a patch build to fix a missing PR comparison. | string | "my-feature...main" | |
projectId | The 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 true | false |
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 true | false |
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 . | boolean | true | false |
zip--zip | Publish your Storybook to Chromatic as a single zip file instead of individual content files. | boolean | true | false |
playwright--playwright | Use your Playwright tests to power visual tests with Chromatic. Learn more | boolean | true | false |
cypress--cypress | Use your Cypress tests to power visual tests with Chromatic. Learn more | boolean | true | false |
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 variable | Description |
---|---|
CHROMATIC_PROJECT_TOKEN | Project token, see --project-token |
CHROMATIC_SHA | Git commit hash. See troubleshooting guide for issues |
CHROMATIC_BRANCH | Git branch name. See --branch-name for additional options and troubleshooting guide for issues |
CHROMATIC_SLUG | Git repository slug (e.g., chromaui/chromatic-cli ). See troubleshooting guide for issues |
CHROMATIC_POLL_INTERVAL | Polling interval when waiting for the build to finish (default: 1000 ) |
CHROMATIC_OUTPUT_INTERVAL | Frequency of progress output while polling or uploading (default: 10000 ) |
CHROMATIC_RETRIES | Number of times to retry file upload (default: 5 ) |
CHROMATIC_STORYBOOK_VERSION | Overrides Storybook package/version detection (e.g. @storybook/react@7.0.1-alpha.25 ) |
CHROMATIC_TIMEOUT | Number of ms before giving up on storybook dev (default: 300000 (5 minutes)) |
STORYBOOK_BUILD_TIMEOUT | Number of ms before giving up on storybook build (default: 600000 (10 minutes)) |
CHROMATIC_DNS_SERVERS | Overrides the DNS server IP address(es) used by node-fetch, comma-separated. See troubleshooting guide for issues |
CHROMATIC_DNS_FAILOVER_SERVERS | Fallback DNS server IPs (default: 1.1.1.1 , 8.8.8.8 (Cloudflare, Google)). See troubleshooting guide for issues |
CI | See --ci |
LOG_LEVEL | One of: silent , error , warn , info , debug |
DISABLE_LOGGING | Set to true to disable logging. Equal to LOG_LEVEL=silent |
HTTPS_PROXY or HTTP_PROXY | Used to configure https-proxy-agent. See troubleshooting guide for issues |
CHROMATIC_ARCHIVE_LOCATION | Change the default location for archives generated by Playwright or Cypress tests |
STORYBOOK_NODE_ENV | Specify 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 code | Key | Description |
---|---|---|
0 | OK | Exited successfully |
1 | BUILD_HAS_CHANGES | Chromatic build has (visual) changes |
2 | BUILD_HAS_ERRORS | Chromatic build has component errors |
3 | BUILD_FAILED | Chromatic build failed due to system error |
4 | BUILD_NO_STORIES | Chromatic build failed because it contained no stories |
5 | BUILD_WAS_LIMITED | Chromatic build was limited |
6 | BUILD_WAS_CANCELED | Chromatic build was canceled |
11 | ACCOUNT_QUOTA_REACHED | Chromatic account reached its snapshot quota |
12 | ACCOUNT_PAYMENT_REQUIRED | Chromatic account requires payment |
101 | GIT_NOT_CLEAN | Git repository workspace not clean |
102 | GIT_OUT_OF_DATE | Git repository not up-to-date with remote |
103 | GIT_NO_MERGE_BASE | Git branch has no merge base |
104 | NPM_INSTALL_FAILED | npm or Yarn failed to install dependencies |
105 | NPM_BUILD_STORYBOOK_FAILED | npm or Yarn failed to run build-storybook script |
201 | FETCH_ERROR | HTTP fetch error |
202 | GRAPHQL_ERROR | GrahpQL API error |
254 | INVALID_OPTIONS | Invalid options (flags) provided |
255 | UNKNOWN_ERROR | Unknown 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-errors | Continue running Chromatic even if Storybook logs errors in the console. |
--app-code <token> | Renamed to --project-token . |
--list | List 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-start | Don’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-specs | Preserve 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-https | Enable 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 tochromatic-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.