Skip to content
Vizzly Docs

Commands Reference

Use this page as a map, not a wall of flags. For the exhaustive option list, run vizzly --help or vizzly <command> --help.

Core workflows

vizzly run

Run a test command with Vizzly capture and upload the result to Vizzly Cloud.

Terminal window
vizzly run "npm test" --wait

Common options:

  • --wait
  • --build-name
  • --environment
  • --parallel-id
  • --allow-no-token
  • --upload-timeout

When a screenshot fails to upload

If an upload fails, vizzly run prints the screenshot’s name and the reason, then keeps uploading later captures. Your tests keep running. You don’t need debug logging to see what went wrong.

Check the summary at the end of the run:

Screenshots: 4 captured, 2 uploaded, 1 reused, 1 failed

Here, one screenshot never reached Vizzly. The CLI reports that visual testing is incomplete and marks the Vizzly build failed. If it can’t reach the API to update the build, it warns you in the terminal.

An upload failure won’t fail a passing test suite. The CLI keeps your test command’s exit code: zero when tests pass, nonzero when they fail. With --wait, it returns after an incomplete upload instead of waiting for comparisons. When all uploads succeed, --wait still exits nonzero for failed visual comparisons.

For scripts, use --json and check uploads.failed; a zero exit code alone doesn’t tell you whether all screenshots arrived. Once you’ve fixed the upload problem, rerun the affected tests to capture the missing screenshots.

vizzly tdd

Run local visual comparisons.

Terminal window
vizzly tdd start --open
vizzly tdd run "npm test"
vizzly tdd status --port 47393
vizzly tdd stop

Subcommands:

  • start
  • run
  • status
  • stop
  • list

start uses port 47392 by default, but it can auto-assign another free port when needed. Use the port printed by start with status --port <port> and stop --port <port> when you need to manage a specific daemon.

vizzly upload

Upload screenshots from a folder.

Terminal window
vizzly upload ./screenshots --wait

Common options:

  • --wait
  • --build-name
  • --environment
  • --parallel-id
  • --batch-size
  • --upload-timeout

vizzly preview

Upload static build output for in-context review.

Terminal window
vizzly preview ./dist

Common options:

  • --build
  • --open
  • --dry-run
  • --public-link
  • --base
  • --exclude
  • --include

Read-only query commands

vizzly status

Terminal window
vizzly status <build-id>

vizzly builds

Terminal window
vizzly builds --limit 10
vizzly builds --build <id> --comparisons

vizzly comparisons

Terminal window
vizzly comparisons --build <id>
vizzly comparisons --name "header*"

vizzly context

Read local TDD results or inspect one build, screenshot, or comparison.

Terminal window
vizzly context build current --source local --json
vizzly context build <build-id> --json
vizzly context comparison <comparison-id> --json
vizzly context screenshot <name> --json
vizzly context review-queue --json

All context commands support --source auto|cloud|local. Use --json when a script needs structured output. For cloud requests from agents and scripts, start with vizzly api schema.

The --agent options for context build and context comparison are deprecated in v0.37.x and will be removed in v0.38.0. Use API schema discovery for cloud requests. For local TDD results, use vizzly context ... --json.

context comparison shows one visual change, including its current and baseline images, diff details, downloadable artifacts, and history. context screenshot follows a screenshot name across builds. context similar finds earlier comparisons with the same Honeydiff fingerprint and needs cloud history.

vizzly baselines

Inspect local TDD baselines.

Terminal window
vizzly baselines
vizzly baselines --info homepage

Review commands

vizzly approve

Terminal window
vizzly approve <comparison-id>

vizzly reject

Terminal window
vizzly reject <comparison-id> --reason "Unexpected regression"

vizzly comment

Terminal window
vizzly comment <build-id> "Looks good overall"

Setup and account

vizzly init

Create a starter config for the project. For repos where agents help with UI work, add the Vizzly skill and project guidance at the same time.

Terminal window
vizzly init
vizzly init --agent-guidance
vizzly init --agent-skill
vizzly init --skip-agent-skill

Use --agent-guidance when you want the full agent setup. It installs the repo-local Vizzly skill at .agents/skills/vizzly and writes a short Vizzly section to AGENTS.md, so agents know how to use screenshot history and the local visual TDD loop.

Use --agent-skill when you only want the local skill. Use --skip-agent-skill when you want config setup without the agent prompt.

vizzly doctor

Terminal window
vizzly doctor
vizzly doctor --api

vizzly config

Terminal window
vizzly config
vizzly config comparison.threshold

vizzly login

Terminal window
vizzly login

vizzly logout

Terminal window
vizzly logout

vizzly whoami

Terminal window
vizzly whoami

vizzly orgs

Terminal window
vizzly orgs

vizzly projects

Terminal window
vizzly projects
vizzly projects --org acme
Terminal window
vizzly project link acme/web
vizzly project link --org acme --project web

Advanced

vizzly finalize

Finalize a parallel build after all shards finish.

Terminal window
vizzly finalize <parallel-id>

vizzly api

Discover supported requests, then call an API endpoint.

Terminal window
vizzly api schema --json
vizzly api schema sdk.listBuilds --json
vizzly api /api/sdk/builds \
  --header 'Vizzly-API-Version: 2026-09-12' --json

The schema describes each request’s method, API version header, parameters, body, and response. Use --output to save image responses. See API schema and requests for details.

Global flags

These work across the CLI:

  • --json [fields]
  • --token
  • --config
  • --verbose
  • --log-level
  • --strict
  • --color
  • --no-color

Next steps