CLI

The stateofpixel package on npm. Node 20 or newer. Run npx stateofpixel <command> --help for the same list.

Commands#

Command	What it does
`upload <dir>`	Upload a folder of screenshots and compare it with the baseline.
`storybook <static-dir>`	Capture every story of a built Storybook, then upload.
`finalize`	Finish a build whose shards ran with --shard auto.
`compare <dir> <baseline-dir>`	Compare a folder of screenshots against a baseline folder.

upload#

Flag	Default	What it does
`--build-name <name>`STATEOFPIXEL_BUILD_NAME		Separate builds of one project, like storybook.
`--shard <i/n>`STATEOFPIXEL_SHARD		This shard and the shard count, or auto with a finalize step.
`--nonce <id>`STATEOFPIXEL_NONCE		Shared by every shard of one build.
`--baseline-branch <branch>`STATEOFPIXEL_BASELINE_BRANCH		Branch to compare against.
`--subset`		Only some snapshots ran, do not mark others removed.
`--threshold <number>`		Color difference threshold, 0 to 1, overrides project settings.
`--strict`		Fail instead of skipping on an outage, a rate limit or a fork.
`--dry-run`		Hash and print the plan, upload nothing.

storybook#

Takes every flag of upload, plus these. See Storybook.

Flag	Default	What it does
`--viewports <widths>`	`1280`	Comma separated viewport widths.
`--include <glob>`		Only stories whose title/name match.
`--exclude <glob>`		Skip stories whose title/name match.
`--wait-for-selector <selector>`	`#storybook-root > *`	Wait for this before each screenshot.
`--delay <ms>`	`0`	Wait this long before each screenshot.

finalize#

Use the same values the shards used. See Sharding.

Flag	Default	What it does
`--build-name <name>`STATEOFPIXEL_BUILD_NAME		The build name the shards used.
`--nonce <id>`STATEOFPIXEL_NONCE		The nonce the shards used.
`--baseline-branch <branch>`STATEOFPIXEL_BASELINE_BRANCH		Branch to compare against, for --skip-if-empty.
`--skip-if-empty`		Create a build with no changes when no shard ran.
`--strict`		Fail instead of skipping on an outage, a rate limit or a fork.

compare#

Flag	Default	What it does
`--out <dir>`	`stateofpixel-report`	Report folder.
`--threshold <number>`	`0.1`	Color difference threshold, 0 to 1.
`--include-aa`		Count anti-aliased pixels as changes.

Authentication#

On GitHub Actions the CLI uses the OIDC token, which needs permissions: id-token: write. Anywhere else, set STATEOFPIXEL_TOKEN to a project token. See Other CI.

GitHub gives pull requests from forks no OIDC token and no secrets, so the CLI skips them with a warning and sets no check. If stateofpixel is a required check, those pull requests cannot merge until an admin bypasses the rule.

Output#

terminal

stateofpixel  build #411  feat/header vs main (#405)
  1,500 snapshots  1,488 unchanged  10 changed  2 added  1 removed
  uploaded 22 images (1.3 MB) in 2.1 s
  review: https://stateofpixel.com/acme/web-app/builds/411

Exit codes#

0 when the build was reported, with or without changes. The GitHub check decides whether the pull request can merge.
0 with a warning when stateofpixel or the GitHub OIDC token service is down, a rate limit is hit, or the pull request comes from a fork, so an outage does not break your CI. Pass --strict to exit 1 instead.
1 on configuration and authentication errors, failed uploads, and images over the limits.