Commands Reference

Reference for all Vizzly CLI commands. Each command includes its options and usage examples.

Authentication Commands

`vizzly login`

Authenticate with your Vizzly account.

vizzly login

Opens your browser for OAuth authorization. Tokens are stored in ~/.vizzly/config.json with 30-day expiry and automatic refresh.

`vizzly logout`

Clear stored authentication tokens.

vizzly logout

Revokes tokens on the server and removes them locally.

`vizzly whoami`

Show current authentication status.

vizzly whoami [--json]

Displays your user info, organizations, token expiry, and project mappings.

Options:

--json - Output as JSON

`vizzly project:select`

Map a project token to the current directory.

vizzly project:select

Interactive prompts walk you through selecting an organization and project. The token is mapped to your current directory path.

`vizzly project:list`

Show all project mappings.

vizzly project:list

`vizzly project:token`

Show the project token for the current directory.

vizzly project:token [--json]

Displays the first 10 characters of the token for security.

Options:

--json - Output as JSON

`vizzly project:remove`

Remove the project configuration for the current directory.

vizzly project:remove

See Authentication for detailed authentication workflows.

Configuration Commands

`vizzly init`

Create a vizzly.config.js file in the current directory.

vizzly init [--force]

Options:

--force - Overwrite existing config file

Examples:

# Create config file
vizzly init

# Overwrite existing config
vizzly init --force

`vizzly upload`

Upload screenshots from a directory for comparison.

vizzly upload <directory> [options]

Build Configuration:

-b, --build-name <name> - Custom build name
--branch <branch> - Git branch override
--commit <sha> - Git commit SHA override
--message <msg> - Commit message override
--environment <env> - Environment name (default: test)

Processing Options:

--wait - Wait for processing to complete
--upload-all - Upload all without SHA deduplication
--threshold <number> - Comparison threshold in CIEDE2000 Delta E (default: 2.0)
--upload-timeout <ms> - Upload wait timeout in milliseconds
--batch-size <n> - Upload batch size

Parallel Execution:

--parallel-id <id> - Unique identifier for parallel builds

Development:

--token <token> - API token override
-m, --metadata <json> - Additional metadata as JSON

Examples:

# Basic upload
vizzly upload ./screenshots

# Upload with custom build name
vizzly upload ./screenshots --build-name "Release v1.2.3"

# Wait for processing completion
vizzly upload ./screenshots --wait

# Upload all without deduplication
vizzly upload ./screenshots --upload-all

# For parallel CI builds
vizzly upload ./screenshots --parallel-id "ci-run-123"

`vizzly run`

Run your test command with Vizzly integration.

vizzly run "<command>" [options]

Server Configuration:

--port <port> - Screenshot server port (default: 47392)
--timeout <ms> - Server timeout in milliseconds (default: 30000)

Build Configuration:

-b, --build-name <name> - Custom build name
--branch <branch> - Git branch override
--commit <sha> - Git commit SHA override
--message <msg> - Commit message override
--environment <env> - Environment name (default: test)

Processing Options:

--wait - Wait for build completion and exit with appropriate code
--threshold <number> - Comparison threshold in CIEDE2000 Delta E (default: 2.0)
--upload-timeout <ms> - Upload wait timeout in milliseconds
--upload-all - Upload all screenshots without SHA deduplication

Parallel Execution:

--parallel-id <id> - Unique identifier for parallel test execution

Development:

--allow-no-token - Allow running without API token (local mode only)
--token <token> - API token override

Examples:

# Basic test run
vizzly run "npm test"

# Custom port
vizzly run "pytest" --port 3002

# Wait for completion (useful in CI)
vizzly run "npm test" --wait

# Run without API token (local development)
vizzly run "npm test" --allow-no-token

# Parallel CI builds
vizzly run "npm test" --parallel-id "ci-run-123"

# Custom build configuration
vizzly run "npm test" \
  --build-name "Feature branch tests" \
  --environment "staging" \
  --threshold 1.5

`vizzly tdd`

Local development mode with immediate visual feedback.

`vizzly tdd start`

Start a background TDD server with interactive dashboard.

vizzly tdd start [options]

Options:

--port <port> - Server port (default: 47392)
--open - Open dashboard in browser after starting
--baseline-build <id> - Use specific build as baseline (requires API token)
--baseline-comparison <id> - Use specific comparison as baseline (requires API token)
--threshold <number> - Comparison threshold in CIEDE2000 Delta E (default: 2.0)
--timeout <ms> - Server timeout in milliseconds (default: 30000)
--environment <env> - Environment name (default: test)
--token <token> - API token override

Examples:

# Start background server
vizzly tdd start

# Start and open dashboard
vizzly tdd start --open

# Start with remote baseline
vizzly tdd start --baseline-build "build-uuid-123"

`vizzly tdd run`

Run tests once with TDD mode, then exit.

vizzly tdd run "<command>" [options]

Options:

--set-baseline - Accept current screenshots as new baseline
--baseline-build <id> - Use specific build as baseline (requires API token)
--baseline-comparison <id> - Use specific comparison as baseline (requires API token)
--threshold <number> - Comparison threshold in CIEDE2000 Delta E (default: 2.0)
--port <port> - Server port (default: 47392)
--timeout <ms> - Server timeout in milliseconds (default: 30000)
--branch <branch> - Git branch override
--environment <env> - Environment name (default: test)
--token <token> - API token override

Examples:

# First run - creates local baselines
vizzly tdd run "npm test"

# Make changes and test - fails if visual differences detected
vizzly tdd run "npm test"

# Accept changes as new baseline
vizzly tdd run "npm test" --set-baseline

# Use specific threshold
vizzly tdd run "npm test" --threshold 1.5

# Use remote build as baseline
vizzly tdd run "npm test" --baseline-build "build-uuid-123"

`vizzly tdd stop`

Stop the background TDD server.

vizzly tdd stop

`vizzly tdd status`

Check if TDD server is running.

vizzly tdd status

Dashboard & Reports

The TDD server provides a web dashboard at http://localhost:47392 (or your configured port) with:

Comparisons view - All screenshot comparisons with visual diffs
Settings view - Configure threshold and other options
Projects view - Access cloud baselines when authenticated

Each tdd run generates an HTML report with comparison tools:

Side-by-side mode - Compare baseline and current images
Slide mode - Drag to reveal differences
Toggle mode - Click to switch between baseline and current

`vizzly status`

Check build progress and results.

vizzly status <build-id> [--verbose] [--json]

Options:

--verbose - Show detailed build information
--json - Machine-readable JSON output

Examples:

# Basic status check
vizzly status abc123-def456-build-id

# Detailed information for debugging
vizzly status abc123-def456-build-id --verbose

# JSON output for CI/CD integration
vizzly status abc123-def456-build-id --json

Shows build status, screenshot and comparison counts (new, changed, identical), git details, web dashboard link, and timing information.

`vizzly finalize`

Finalize a parallel build after all shards complete.

vizzly finalize <parallel-id>

Use after all parallel test shards complete to trigger final processing.

Examples:

# Finalize parallel build
vizzly finalize "ci-run-123"

`vizzly doctor`

Validate your local setup and configuration.

vizzly doctor [--api] [--json]

Options:

--api - Include API connectivity checks
--json - JSON output for tooling

Examples:

# Local-only checks
vizzly doctor

# Include API connectivity
VIZZLY_TOKEN=your-token vizzly doctor --api

# JSON output for tooling
vizzly doctor --json

Local checks:

Node.js version (>= 22.0.0)
Configuration file format (apiUrl, threshold, port)
Port availability (default 47392)

API checks (with --api flag):

API connectivity using your VIZZLY_TOKEN
Authentication validation
Service availability

Global Options

Available for all commands:

--help, -h - Show help information
--version, -v - Show version number
--json - Machine-readable output
--no-color - Disable colored output
--verbose - Verbose output (alias for --log-level debug)
--log-level <level> - Log level: debug, info, warn, error (default: info)
-c, --config <path> - Config file path
--token <token> - API token override

Environment Variables

All commands respect these environment variables:

VIZZLY_TOKEN - API authentication token
VIZZLY_API_URL - Override API base URL
VIZZLY_LOG_LEVEL - Logger level (debug, info, warn, error)
VIZZLY_PARALLEL_ID - Unique identifier for parallel builds
VIZZLY_COMMIT_SHA - Override detected commit SHA
VIZZLY_COMMIT_MESSAGE - Override detected commit message
VIZZLY_BRANCH - Override detected branch name
VIZZLY_PR_NUMBER - Override detected pull request number

Exit Codes

Commands return these exit codes:

0 - Success
1 - General failure or visual differences detected (with --wait)

Next Steps

Configuration - Detailed configuration options
TDD Mode - Local visual testing workflow
Upload Workflow - Uploading existing screenshots
Doctor Command - Diagnostics and troubleshooting