Commands reference
Full CLI reference for v0.38.0, published . Cloud features may behave differently today.
Run npx vizzly --help for the command list from your installed CLI. Add
--help after a command for its arguments, flags, and defaults.
Run tests and upload
npx vizzly run "npm test" --waitrun starts the screenshot server, runs your command, and uploads captures.
Use --build-name, --environment, --branch, --commit, and
--message to set build metadata. Use --parallel-id when several CI
shards contribute to one visual build.
Use --batch-size and --upload-timeout to tune cloud runs, or --threshold and --min-cluster-size for comparison settings.
A failed capture upload leaves the visual build incomplete while preserving the test command's exit code. Read data.uploads.failed from JSON output as well as checking the exit status. Failed uploads also skip waiting for comparisons.
After successful uploads, --wait waits for comparisons and exits nonzero
if they fail. Inspect upload failures before treating passing tests as a
complete visual check.
Visual testing and CI
| Command | What it does |
|---|---|
vizzly run "npm test" | Start the capture server, run tests, and upload screenshots |
vizzly upload ./screenshots | Upload files your tests already captured |
vizzly tdd run "npm test" | Run local visual comparisons once |
vizzly tdd start | Keep a local comparison server running |
vizzly tdd status, list, stop | Inspect or stop a local server |
vizzly finalize parallel-id | Finalize a build after parallel shards complete |
vizzly preview ./dist | Attach a built static site to a visual build |
Add --wait to run or upload to wait for processing. Use
Upload for batching and parallel builds,
or TDD mode to compare without uploading.
Attach a preview
npx vizzly preview ./dist --build build-idnpx vizzly preview ./dist --dry-runUse --public-link when uploading a preview for a private project. Anyone
with that link can open the preview until it expires. --exclude and
--include control which files are sent. --base overrides the detected
asset path, and --open opens the preview after upload.
Find builds, screenshots, and baselines
npx vizzly status build-idnpx vizzly builds --project web-app --org acme --jsonnpx vizzly comparisons --build build-id --jsonnpx vizzly baselines --name "checkout*"For cloud screenshots and review state, discover the supported operations with vizzly api schema --json and call them with vizzly api.
Use tdd screenshots list, latest, show, or accept for local captures. See TDD mode.
Review comparisons
These commands write to the cloud build or comparison. Use IDs from the build or comparison query and credentials that can perform the action.
npx vizzly approve comparison-idnpx vizzly reject comparison-id --reason "The heading moved below the fold"npx vizzly comment build-id "Ready for a second look"Setup and account
initcreates project config.config --jsonshows the loaded settings.config comparison.thresholdreads a single effective config value.login,whoami, andlogoutmanage the user session.orgsandprojectslist accessible accounts and projects.doctordiagnoses the local environment. Add--apifor connectivity.
Use project link to choose an upload destination.
Global flags
| Flag | What it changes |
|---|---|
--config <path> | Select a config file |
--token <token> | Pass a project credential for this run |
--json [fields] | Request machine-readable output, with optional field selection |
--log-level <level> | Choose debug, info, warn, or error diagnostics |
--verbose | Use debug-level output |
--color | Force terminal colors |
--strict | Fail on errors the CLI would otherwise warn about |
--no-color | Disable terminal colors |
npx vizzly --help