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>

buildCommand

CLI

GitHub Action

Config File

Flag:

--build-command

Type:

string

Example:

"nx run my-app:build-storybook"

The command that builds your Storybook. Use this if your Storybook build command does not exist in the “scripts” field of your package.json.
Requires --output-dir.

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:

true in the GitHub Action, otherwise 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.

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

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

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). This is a GitHub Actions–specific key. Other CI/CD providers have their own flag.

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