Skip to content
v0.37.0

Upload command

Full CLI reference for v0.37.0, published . Cloud features may behave differently today.

Upload a directory

Use upload when tests or other tools already saved the screenshots to disk. Set up cloud authentication for the destination project, then pass the directory.

Terminal window
npx vizzly upload ./screenshots --wait

Vizzly attaches Git metadata when available. Use --wait when your job needs to wait for the build to process. A completed upload can still contain visual differences that need review. --wait exits nonzero when the completed comparisons fail.

Name and group builds

Terminal window
npx vizzly upload ./screenshots --build-name "Checkout visual tests"
npx vizzly upload ./screenshots --parallel-id "$CI_RUN_ID"
npx vizzly finalize "$CI_RUN_ID"

Run finalize after the shards finish. Each shard needs the same parallel ID.

Common options

FlagUse it to
--branch, --commit, --messageOverride Git metadata
--environmentRecord a different environment
--batch-sizeChange the number of screenshots in each batch
--thresholdSet the color tolerance
--upload-allSend all screenshots without SHA deduplication
--upload-timeoutChange the build-processing wait when using --wait

Use --min-cluster-size to change the minimum changed-pixel group size.

Diagnose an incomplete build

Check the upload summary and confirm the images can be decoded. Review the cloud screenshot requirements for current limits.

Individual upload failures leave the visual build incomplete. The summary identifies failed screenshots, and a wrapped test command keeps its own exit code.

Terminal window
npx vizzly upload --help

If tests capture through the Vizzly client, use vizzly run to start capture and upload around the test command.