Skip to content
Vizzly Docs

CLI Overview

The Vizzly CLI runs a local HTTP server during test execution. Your tests send screenshots to this server, which either compares them locally (TDD mode) or uploads them to Vizzly’s cloud for team review.

Two Ways to Test

Local development (TDD mode):

Terminal window
vizzly tdd start
npm test --watch

Start a local server with a dashboard at http://localhost:47392. Run tests in watch mode. Screenshots get compared against local baselines with a web UI showing diffs. No uploads, no waiting.

CI/CD (cloud mode):

Terminal window
vizzly run "npm test"

Run your test command. The CLI starts a server, collects screenshots during test execution, then uploads them to Vizzly’s cloud. You get a build URL with comparisons for your team to review.

Installation

Terminal window
npm install -D @vizzly-testing/cli

Requires Node.js 22 or newer.

Authentication

Local development:

Terminal window
vizzly login

Opens your browser for OAuth authentication. Stores a token that lasts 30 days.

CI/CD:

Terminal window
export VIZZLY_TOKEN=your-project-token

Set the token in your CI provider’s secrets. The CLI reads it automatically.

Token priority: --token flag > VIZZLY_TOKEN env var > project mapping (vizzly project:select) > user token (vizzly login).

Commands

Test Integration

Upload & Status

Setup & Validation

Authentication & Projects

Using the Client in Tests

Import the client in your test files:

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


test('homepage test', async ({ page }) => {
  await page.goto('/');
  const screenshot = await page.screenshot();


  await vizzlyScreenshot('homepage', screenshot, {
    browser: 'chrome',
    viewport: '1920x1080'
  });
});

The client sends screenshots to the local server via HTTP POST. Works with Playwright, Cypress, Puppeteer, or anything that captures screenshots.

You can pass a file path instead of a buffer:

await page.screenshot({ path: './screenshots/homepage.png' });
await vizzlyScreenshot('homepage', './screenshots/homepage.png', {
  browser: 'chrome',
  viewport: '1920x1080'
});

Package Exports

The CLI package provides four entry points:

@vizzly-testing/cli/client (recommended for test runners):

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

Lightweight client. Sends screenshots to the local server.

@vizzly-testing/cli/sdk (for custom integrations):

import { createVizzly } from '@vizzly-testing/cli/sdk';


const vizzly = await createVizzly({
  apiKey: process.env.VIZZLY_TOKEN,
  server: { port: 3003 }
});


await vizzly.start();
await vizzly.screenshot('test', buffer);
await vizzly.upload();
await vizzly.stop();

Full SDK with programmatic control over server lifecycle and uploads.

@vizzly-testing/cli/config (for config files):

import { defineConfig } from '@vizzly-testing/cli/config';


export default defineConfig({
  threshold: 0.1,
  upload: {
    screenshotsDir: './screenshots'
  }
});

Config helper with type hints for vizzly.config.js.

@vizzly-testing/cli (main export):

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

Convenience export that includes both client and SDK.

AI Integration

Vizzly includes built-in support for AI-powered development tools:

  • Claude Code Integration - AI-assisted visual testing workflows with intelligent debugging, test coverage suggestions, and interactive setup

Get AI help with visual regressions, baseline management, and test coverage.

Next Steps