Skip to content
v0.37.0

Commands reference

Full CLI reference for v0.37.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

Terminal window
npx vizzly run "npm test" --wait

run 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

CommandWhat it does
vizzly run "npm test"Start the capture server, run tests, and upload screenshots
vizzly upload ./screenshotsUpload files your tests already captured
vizzly tdd run "npm test"Run local visual comparisons once
vizzly tdd startKeep a local comparison server running
vizzly tdd status, list, stopInspect or stop a local server
vizzly finalize parallel-idFinalize a build after parallel shards complete
vizzly preview ./distAttach 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

Terminal window
npx vizzly preview ./dist --build build-id
npx vizzly preview ./dist --dry-run

Use --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

Terminal window
npx vizzly status build-id
npx vizzly builds --project web-app --org acme --json
npx vizzly comparisons --build build-id --json
npx vizzly baselines --name "checkout*"

Use context for this release's local evidence. See Scripting for query examples.

For cloud screenshots and review state, discover the supported operations with vizzly api schema --json and call them with vizzly api.

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.

Terminal window
npx vizzly approve comparison-id
npx vizzly reject comparison-id --reason "The heading moved below the fold"
npx vizzly comment build-id "Ready for a second look"

Setup and account

  • init creates project config. config --json shows the loaded settings.
  • config comparison.threshold reads a single effective config value.
  • login, whoami, and logout manage the user session.
  • orgs and projects list accessible accounts and projects.
  • doctor diagnoses the local environment. Add --api for connectivity.

Use project link to choose an upload destination.

Global flags

FlagWhat 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
--verboseUse debug-level output
--colorForce terminal colors
--strictFail on errors the CLI would otherwise warn about
--no-colorDisable terminal colors
Terminal window
npx vizzly --help