Sign inSign up

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

autoAcceptChanges

CLI
GitHub Action
Config File

Flag:

--auto-accept-changes

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.

branchName

CLI
GitHub Action

Flag:

--branch-name

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>

buildScriptName

CLI
GitHub Action
Config File

Flag:

--build-script-name (-b)

Type:

string

Default:

build-storybook

Example:

"build:storybook"
The npm script that builds your Storybook. 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.

configFile

CLI
GitHub Action

Flag:

--config.json

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

Type:

boolean

Default:

false

Example:

true
Output verbose debugging information. This option implies interactive: false

diagnosticsFile

CLI
GitHub Action
Config File

Flag:

--diagnostics-file

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

dryRun

CLI
GitHub Action

Flag:

--dry-run

Type:

boolean

Default:

false

Example:

true
Run without actually publishing to Chromatic.

exitOnceUploaded

CLI
GitHub Action
Config File

Flag:

--exit-once-uploaded

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.

exitZeroOnChanges

CLI
GitHub Action
Config File

Flag:

--exit-zero-on-changes

Type:

glob | boolean

Default:

false

Example:

"!(main)" or true
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.

externals

CLI
GitHub Action
Config File

Flag:

--externals

Type:

string | string[] (glob)

Example:

"my-folder/**"
Disable TurboSnap when any of these files have changed since the baseline build.
Requires onlyChanged.

forceRebuild

CLI
GitHub Action

Flag:

--force-rebuild

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.

ignoreLastBuildOnBranch

CLI
GitHub Action
Config File

Flag:

--ignore-last-build-on-branch

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: false

CLI
GitHub Action

Flag:

--no-interactive

Type:

boolean

Default:

Inferred from TTY

Example:

false
Don’t ask interactive questions about your setup, and don’t overwrite output. true in non-TTY environments.

isLocalBuild

CLI
GitHub Action

Type:

boolean

Default:

false

Example:

true
Mark the build as “local”.

junitReport

CLI
GitHub Action
Config File

Flag:

--junit-report

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

CLI
GitHub Action

Flag:

--list

Type:

boolean

Default:

false

Example:

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

logFile

CLI
GitHub Action
Config File

Flag:

--log-file

Type:

string | boolean

Default:

false

Example:

"logs.txt" or true
Write CLI logs to a file. Defaults to chromatic.log

fileHashing

CLI
GitHub Action
Config File

Flag:

--no-file-hashing

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.

onlyChanged

CLI
GitHub Action
Config File

Flag:

--only-changed

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.

onlyStoryFiles

CLI
GitHub Action
Config File

Flag:

--only-story-files

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.

onlyStoryNames

CLI
GitHub Action
Config File

Flag:

--only-story-names

Type:

string | string[] (glob)

Example:

"Atoms/Button/*"
Only run a single story or a subset of stories by their name.

outputDir

CLI
GitHub Action
Config File

Flag:

--output-dir (-o)

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

Type:

string

Example:

"my-feature...main"
Create a patch build to fix a missing PR comparison.

projectId

Config File

Type:

string

Example:

"Project:5d67dc0374b2e300209c41e7"
The unique identifier for your project, sometimes referred to as appId.

projectToken

CLI
GitHub Action
Config File

Flag:

--project-token (-t)

Type:

string

Default:

Environment variable

Example:

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

repositorySlug

CLI
GitHub Action

Flag:

--repository-slug

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

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.

skipUpdateCheck

CLI
GitHub Action
Config File

Flag:

--skip-update-check

Type:

boolean

Default:

false

Example:

true
Skips Chromatic CLI update check.

storybookBaseDir

CLI
GitHub Action
Config File

Flag:

--storybook-base-dir

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.

storybookBuildDir

CLI
GitHub Action
Config File

Flag:

--storybook-build-dir (-d)

Type:

string

Example:

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

storybookConfigDir

CLI
GitHub Action
Config File

Flag:

--storybook-config-dir

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.

storybookLogFile

CLI
GitHub Action
Config File

Flag:

--storybook-log-file

Type:

string | boolean

Default:

build-storybook.log

Example:

"sb.txt" or true
Write Storybook build logs to a custom file path.

traceChanged

CLI
GitHub Action
Config File

Flag:

--trace-changed

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.

workingDir

CLI
GitHub Action

Flag:

--working-dir

Type:

string

Default:

process.cwd()

Example:

"my-folder"
Provide the location of Storybook’s package.json if installed in a subdirectory (i.e., monorepos).

untraced

CLI
GitHub Action
Config File

Flag:

--untraced

Type:

string | string[] (glob)

Example:

"my-folder/**"
Disregard these files and their dependencies when tracing dependent stories for TurboSnap.
Requires onlyChanged.

uploadMetadata

CLI
GitHub Action
Config File

Flag:

--upload-metadata

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

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

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

Type:

boolean

Default:

false

Example:

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

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.

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.
--diagnosticsReplaced by --diagnostics-file.
--onlyReplaced by --only-story-names.
--preserve-missingReplaced 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
--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