Configuration reference

These options control how Chromatic behaves via the CLI, config file and the GitHub Action. Refer to branching docs and diagnosing CLI issues for more context on when to use some of these flags.

Note that the config file only supports a subset of these options. Some options are exclusive to the CLI or the config file. The next section tags each option with the appropriate context.

Glob Types: Where supported, globs are handled via picomatch. To learn more about globs and how to use them, refer to our guide on globs. To verify your glob pattern, use the picomatch-playground.

Options

Auto accept changes

CLI

GitHub Action

Config File

Flag:

--auto-accept-changes

Option:

autoAcceptChanges

Type:

glob | boolean

Default:

false

Example:

"main" or true

If there are any changes to the build, automatically accept them. Only for given branch, if specified.

Branch name

CLI

GitHub Action

Flag:

--branch-name

Option:

branchName

Type:

string

Default:

Inferred from CI or Git

Example:

"my-branch"

Override the branch name for certain CI providers or cross-fork PR comparisons. Also accepts <owner>:<branch>

Build command

CLI

GitHub Action

Config File

Flag:

--build-command

Option:

buildCommand

Type:

string

Example:

"nx run my-app:build-storybook"

The command Chromatic uses to build your Storybook before capturing snapshots. Use this if your Storybook build command does not exist in the “scripts” field of your package.json.
Requires --output-dir.

Build script name

CLI

GitHub Action

Config File

Flag:

--build-script-name (-b)

Option:

buildScriptName

Type:

string

Default:

build-storybook

Example:

"build:storybook"

The npm script Chromatic uses to build your Storybook before capturing snapshots. Use this if your Storybook build script is named differently.

CI

CLI

Flag:

--ci

Type:

boolean

Default:

Inferred from CI

Example:

true

Mark the build as coming from CI.

Config file

CLI

GitHub Action

Flag:

--config-file

Option:

configFile

Type:

string

Default:

chromatic.config.json

Example:

"config/chromatic.json"

Path from where to load the Chromatic config JSON file.

Debug

CLI

GitHub Action

Config File

Flag:

--debug

Option:

debug

Type:

boolean

Default:

false

Example:

true

Output verbose debugging information. This option sets interactivity to false, preventing the CLI from prompting for user input and returning only message strings.

Diagnostics file

CLI

GitHub Action

Config File

Flag:

--diagnostics-file

Option:

diagnosticsFile

Type:

string | boolean

Default:

false

Example:

"debug.json" or true

When enabled, write process context information to a JSON file.
Defaults to chromatic-diagnostics.json

Dry run

CLI

GitHub Action

Flag:

--dry-run

Option:

dryRun

Type:

boolean

Default:

false

Example:

true

Run without actually publishing to Chromatic.

Exit once uploaded

CLI

GitHub Action

Config File

Flag:

--exit-once-uploaded

Option:

exitOnceUploaded

Type:

glob | boolean

Default:

false

Example:

"my-branch" or true

Exit with status 0 (OK) once the built version has been published to Chromatic. Only for given branch, if specified.

Exit zero on changes

CLI

GitHub Action

Config File

Flag:

--exit-zero-on-changes

Option:

exitZeroOnChanges

Type:

glob | boolean

Default:

true in the GitHub Action, otherwise false

Example:

"!(main)" or true

If all tests render successfully but visual changes are found, exit with code 0 rather than the usual exit code 1. Only for given branch, if specified.

Externals

CLI

GitHub Action

Config File

Flag:

--externals

Option:

externals

Type:

string | string[] (glob)

Example:

"my-folder/**"

Disable TurboSnap when any of these files have changed since the baseline build.
Requires onlyChanged.

Force rebuild

CLI

GitHub Action

Flag:

--force-rebuild

Option:

forceRebuild

Type:

glob | boolean

Default:

false

Example:

"my-branch" or true

Do not skip build when a rebuild is detected. Only for given branch, if specified.

Git timeout

Config File

Option:

gitTimeout

Type:

number

Default:

20

Example:

30

The maximum number of seconds Chromatic waits for individual git operations to complete before timing out. Increase this value if you have a large repository where git commands take longer than usual.

Ignore last build on branch

CLI

GitHub Action

Config File

Flag:

--ignore-last-build-on-branch

Option:

ignoreLastBuildOnBranch

Type:

glob

Example:

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

Interactive

CLI

GitHub Action

Flag:

--no-interactive

Option:

interactive

Type:

boolean

Default:

Inferred from TTY

Example:

false

When set to false, it prompts the CLI not to ask interactive questions about your setup, and it doesn’t overwrite output. It’s set to true in non-TTY environments.

JUnit report

CLI

GitHub Action

Config File

Flag:

--junit-report

Option:

junitReport

Type:

string | boolean

Default:

false

Example:

"report.xml" or true

When enabled, write the build results to a JUnit XML file.
Defaults to chromatic-build-{buildNumber}.xml where the {buildNumber} will be replaced with the actual build number.

List available stories

CLI

Flag:

--list

Type:

boolean

Default:

false

Example:

true

Outputs the list of available stories in your Storybook.
Useful for debugging and diagnosing issues.

Log file

CLI

GitHub Action

Config File

Flag:

--log-file

Option:

logFile

Type:

string | boolean

Default:

false

Example:

"logs.txt" or true

Write CLI logs to a file. Defaults to chromatic.log

File hashing

CLI

GitHub Action

Config File

Flag:

--no-file-hashing

Option:

fileHashing

Type:

boolean

Default:

false

Example:

true

Enabling this option will turn off the built-in file hashing mechanism, leading to all the files being uploaded to Chromatic on every build.

Only changed

CLI

GitHub Action

Config File

Flag:

--only-changed

Option:

onlyChanged

Type:

glob | boolean

Default:

false

Example:

true

Enables TurboSnap.
Runs Chromatic for stories affected by files and dependencies that have changed since the baseline build, including the specified branch if provided.

Only story files

CLI

GitHub Action

Config File

Flag:

--only-story-files

Option:

onlyStoryFiles

Type:

string | string[] (glob)

Example:

"src/ui/**"

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.

Only story names

CLI

GitHub Action

Config File

Flag:

--only-story-names

Option:

onlyStoryNames

Type:

string | string[] (glob)

Example:

"Atoms/Button/*"

Only run a single story or a subset of stories by their name.

Output directory

CLI

GitHub Action

Config File

Flag:

--output-dir (-o)

Option:

outputDir

Type:

string

Default:

Temporary directory

Example:

"storybook-static"

Relative path to target directory for building your Storybook. Use this if you want to preserve it for other tasks.

Patch build

CLI

GitHub Action

Flag:

--patch-build

Option:

patchBuild

Type:

string

Example:

"my-feature...main"

Create a patch build to fix a missing PR comparison.

Project ID

Config File

Option:

projectId

Type:

string

Example:

"Project:5d67dc0374b2e300209c41e7"

The unique identifier for your project, sometimes referred to as appId.

Project token

CLI

GitHub Action

Config File

Flag:

--project-token (-t)

Option:

projectToken

Type:

string

Default:

Environment variable

Example:

"chpt_b2aef0123456789"

The secret token for your project. Prefer to use CHROMATIC_PROJECT_TOKEN instead if you can.

Repository slug

CLI

GitHub Action

Flag:

--repository-slug

Option:

repositorySlug

Type:

string

Default:

Inferred from CI or Git

Example:

"owner/repositoryName"

Override the repository slug. This is mainly used to correctly handle cross-fork builds, where the owner deviates.

Skip

CLI

GitHub Action

Config File

Flag:

--skip

Option:

skip

Type:

glob | boolean

Default:

false

Example:

"my-branch" or true

Skip Chromatic tests, but mark the commit as passing. It avoids blocking PRs due to required merge checks. Only for given branch, if specified.

Skip update check

CLI

GitHub Action

Config File

Flag:

--skip-update-check

Option:

skipUpdateCheck

Type:

boolean

Default:

false

Example:

true

Skips Chromatic CLI update check.

Storybook base directory

CLI

GitHub Action

Config File

Flag:

--storybook-base-dir

Option:

storybookBaseDir

Type:

string

Example:

"src/ui"

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.

Storybook build directory

CLI

GitHub Action

Config File

Flag:

--storybook-build-dir (-d)

Option:

storybookBuildDir

Type:

string

Example:

"dist/storybook"

If you have already built your Storybook, provide the path to the static build directory.

Storybook config directory

CLI

GitHub Action

Config File

Flag:

--storybook-config-dir

Option:

storybookConfigDir

Type:

string

Default:

.storybook

Example:

"storybook-config"

Relative path from where you run Chromatic to your Storybook config directory.
Use with onlyChanged and storybookBuildDir when using a custom --config-dir flag for Storybook.

Storybook log file

CLI

GitHub Action

Config File

Flag:

--storybook-log-file

Option:

storybookLogFile

Type:

string | boolean

Default:

build-storybook.log

Example:

"sb.txt" or true

Write Storybook build logs to a custom file path.

Trace changed

CLI

GitHub Action

Config File

Flag:

--trace-changed

Option:

traceChanged

Type:

string | boolean

Default:

false

Example:

"expanded" or true

Print dependency trace for changed files to affected story files. Set to “expanded” to list individual modules.
Requires onlyChanged.

Working directory

GitHub Action

Flag:

--working-dir

Option:

workingDir

Type:

string

Default:

process.cwd()

Example:

"my-folder"

Provide the location of Storybook’s package.json if installed in a subdirectory (i.e., monorepos). This is a GitHub Actions–specific key. Other CI/CD providers have their own flag.

Untraced

CLI

GitHub Action

Config File

Flag:

--untraced

Option:

untraced

Type:

string | string[] (glob)

Example:

"my-folder/**"

Disregard these files and their dependencies when tracing dependent stories for TurboSnap.
Requires onlyChanged.

Upload metadata

CLI

GitHub Action

Config File

Flag:

--upload-metadata

Option:

uploadMetadata

Type:

boolean

Default:

false

Example:

true

Upload Chromatic metadata files as part of the published Storybook. This option implies diagnosticsFile: true and logFile: true

Zip

CLI

GitHub Action

Config File

Flag:

--zip

Option:

zip

Type:

boolean

Default:

false

Example:

true

Publish your Storybook to Chromatic as a single zip file instead of individual content files.

Playwright

CLI

GitHub Action

Config File

Flag:

--playwright

Option:

playwright

Type:

boolean

Default:

false

Example:

true

Use your Playwright tests to power visual tests with Chromatic. Learn more

Cypress

CLI

GitHub Action

Config File

Flag:

--cypress

Option:

cypress

Type:

boolean

Default:

false

Example:

true

Use your Cypress tests to power visual tests with Chromatic. Learn more

Vitest

CLI

GitHub Action

Config File

Flag:

--vitest

Option:

vitest

Type:

boolean

Default:

false

Example:

true

Use your Vitest tests to power visual tests with Chromatic. Learn more

iOS build command

Config File

Option:

reactNative.iosBuildCommand

Type:

string

Example:

"nx run my-app:build-storybook-ios"

The command that builds your React Native Storybook for iOS.

Android build command

Config File

Option:

reactNative.androidBuildCommand

Type:

string

Example:

"nx run my-app:build-storybook-android"

The command that builds your React Native Storybook for Android.

Android build architectures

Config File

Option:

reactNative.androidBuildArchitectures

Type:

array of string

Example:

["arm64-v8a", "armeabi-v7a"]

The Android architectures to build for. Chromatic always builds for x86_64, if you would like additional architectures built you may specify them here.

Incompatible option combinations

Some options are mutually exclusive or fundamentally incompatible. Using them together either produces unexpected results, causes one to silently override the other, or makes one of them entirely irrelevant.

Options	Why they conflict
`onlyStoryNames` or `onlyStoryFiles` with `onlyChanged`	TurboSnap (`onlyChanged`) is an automated filter: it uses your git history and dependency graph to decide which stories need to be tested. `onlyStoryNames` and `onlyStoryFiles` are manual filters: you explicitly tell Chromatic which stories or files to include, and Chromatic does not infer or validate those choices.
`onlyStoryNames` and `onlyStoryFiles`	Both options filter what gets tested, but when used together only one gets applied.
`buildScriptName` and `storybookBuildDir`	These options represent mutually exclusive approaches to providing a Storybook build to Chromatic: `buildScriptName` has Chromatic build your Storybook for you, whereas `storybookBuildDir` points at a build you’ve already made.
`autoAcceptChanges` and `exitZeroOnChanges`	Both options prevent your CI pipeline from failing when visual changes are detected, but they do it differently: `autoAcceptChanges` automatically accepts all detected changes, while `exitZeroOnChanges` exits with a zero status code without accepting changes.
`skip` and any other option	The `skip` option bypasses the Chromatic build entirely, which invalidates any option meant to tweak Chromatic’s build behavior.
`forceRebuild` and `onlyChanged`	These options have directly opposing goals: TurboSnap (`onlyChanged`) is meant to skip stories that are unaffected by a change, while `forceRebuild` is meant to test them all.
`vitest`, `playwright`, and `cypress`,	These are mutually exclusive execution modes. A build runs with Vitest, Playwright, or Cypress, never a combination of them.

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 Vitest, 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.
`MAX_LOCK_FILE_SIZE`	Overrides default allowed lock file size (default: `10485760` (10 MB)). See troubleshooting guide for issues

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
`--preserve-missing`	Replaced by `--only-*` based options. Refer to the following documentation for more information on its deprecation and alternatives.

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
`--allow-console-errors`	Continue running Chromatic even if Storybook logs errors in the console.
`--app-code <token>`	Renamed to `--project-token`.
`--diagnostics`	Replaced by `--diagnostics-file`.
`--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`
`--only`	Replaced by `--only-story-names`.
`--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-ca <ca>`	Use with `--storybook-https`. 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-https`	Enable if Storybook runs on HTTPS (locally). 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-port <port>`	What port is your Storybook running on. Auto detected from the npm script when using `--script-name`. Alias: `-p`
`--storybook-url <url>`	Run against an online Storybook at some URL. This implies `--do-not-start`. Alias: `-u`

Edit page Submit feedback