CLI Overview

The Vizzly CLI has three jobs:

run visual regression test workflows
give you fast local feedback while you work
fetch review history from Vizzly Cloud or your local .vizzly workspace

If you’re wiring Vizzly into CI, start with vizzly run. If you’re iterating locally, start with vizzly tdd. For cloud data in scripts or agents, start with vizzly api schema. Use vizzly context to read local TDD results.

Pick the workflow you need

Local iteration

Use TDD mode when you want fast feedback and local baselines.

vizzly tdd start --open
npm test -- --watch

That gives you a local dashboard, usually at http://localhost:47392. If that port is busy, Vizzly picks the next available port and prints the URL to use. Screenshots stay local. Cloud baseline options download reference images for local comparison.

CI and shared review

Use run when you want a build in Vizzly Cloud that your team can review.

vizzly run "npm test" --wait

The CLI starts a screenshot server, runs your tests, and uploads screenshots. With --wait, it then waits for comparisons to finish.

Check the upload summary before reviewing the build. Failed uploads leave visual testing incomplete, even if your tests passed. The CLI reports those failures and keeps your test command’s exit code; it skips waiting for comparisons when uploads are incomplete. See upload failures.

Existing screenshots

If your screenshots already exist on disk, skip test integration and upload the folder directly.

vizzly upload ./screenshots --wait

Read visual test results from scripts

Use the schema to discover cloud requests:

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 shows the method, version header, request fields, and response for each operation. Use vizzly api to make the request.

For local TDD results, use context JSON:

vizzly context build current --source local --json

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 agent requests.

Install and authenticate

Install the CLI in your project:

npm install -D @vizzly-testing/cli

The package declares Node.js 22+. For local development, sign in once:

vizzly login

For CI, set VIZZLY_TOKEN.

export VIZZLY_TOKEN=your-project-token

For local cloud uploads, link this checkout to a project:

vizzly project link your-org/your-project

Auth depends on the command family. run, upload, preview, and finalize use project credentials from --token, VIZZLY_TOKEN, or a linked project. Account commands like whoami, orgs, and projects use your logged-in user token first.

The commands most teams use

vizzly run runs tests and uploads a cloud build.
vizzly tdd runs local visual comparisons with a dashboard or report.
vizzly upload uploads screenshots from disk.
vizzly status checks one build.
vizzly preview uploads static files for in-context review.
vizzly context fetches read-only UI context for humans, scripts, and agents.
vizzly doctor checks your setup.

If you need the full surface area, use vizzly --help or vizzly <command> --help. Nested help works too, so commands like vizzly tdd start --help and vizzly tdd stop --help show the flags for that specific action.

Add the client to your tests

import { vizzlyScreenshot } from '@vizzly-testing/cli/client';

let screenshot = await page.screenshot();

await vizzlyScreenshot('homepage', screenshot, {
  properties: {
    browser: 'chrome',
    viewport: { width: 1920, height: 1080 },
  },
});

You can pass a buffer or a file path. Both follow the cloud screenshot requirements.

Package entry points

@vizzly-testing/cli/client for sending screenshots to the local server
@vizzly-testing/cli/sdk for custom programmatic integrations
@vizzly-testing/cli/config for defineConfig()
@vizzly-testing/cli as a convenience entry point