VizProof CLI

CLI tool for interacting with the VizProof Visual Regression Testing API.

Installation

npm install -g @vizproof/cli
# or
pnpm add -g @vizproof/cli

Configuration

Set your API token:

vrt config set-token vrt_your_token_here

Set your API URL (optional, defaults to http://localhost:3000):

vrt config set-url https://vizproof.com

Or use environment variables:

export VRT_API_TOKEN=vrt_your_token_here
export VRT_API_URL=https://vizproof.com

Usage

List sites

vrt sites

Create a run

vrt runs:create <siteId>

Check run status

vrt runs:status <runId>

List runs

vrt runs:list [siteId]

Check usage

vrt usage

List Playwright flows

vrt flows:list <siteId>

Run Playwright steps (custom flow)

# Run an existing flow
vrt flows:run <siteId> --flow-id <flowId>

# Run ad-hoc steps from a JSON file
vrt flows:run <siteId> --steps-file ./flow.steps.json --name "Checkout flow"

Wait for run completion (CI-friendly)

vrt runs:wait <runId> --timeout 600 --interval 10

Gate deployment on visual regressions

# Fail if at least 1 critical diff (status=fail)
vrt runs:gate <runId> --max-fail 0

# Strict mode: also fail on warnings
vrt runs:gate <runId> --max-fail 0 --max-warn 0

# Auto-rebaseline when run is truly identical (fail=0, warn=0, mismatch <= 0%)
vrt runs:gate <runId> --max-fail 0 --rebaseline-if-identical

# Same, but tolerate tiny mismatch noise up to 0.02%
vrt runs:gate <runId> --max-fail 0 --rebaseline-if-identical --rebaseline-max-mismatch 0.02

JSON output for pipelines

vrt runs:create <siteId> --json
vrt runs:status <runId> --json
vrt runs:gate <runId> --max-fail 0 --json

Examples

# List all sites
vrt sites

# Create a run for a site
vrt runs:create clx123abc456

# Check the status of a run
vrt runs:status run789xyz

# List all runs for a specific site
vrt runs:list clx123abc456

# Wait + gate for CI/CD
vrt runs:wait run789xyz --timeout 600
vrt runs:gate run789xyz --max-fail 0

# Check your current usage
vrt usage

# Run custom Playwright steps from file
vrt flows:run clx123abc456 --steps-file ./flow.steps.json --json

Example flow.steps.json

[
  { "type": "goto", "url": "https://example.com" },
  { "type": "click", "selector": "a[href='/pricing']" },
  { "type": "waitFor", "ms": 1200 },
  { "type": "screenshot", "name": "pricing", "fullPage": true }
]

GitHub Actions (minimal)

- name: Install CLI
  run: npm install -g @vizproof/cli

- name: Configure CLI
  run: |
    vrt config set-token "${{ secrets.VRT_API_TOKEN }}"
    vrt config set-url "${{ secrets.VRT_API_URL || 'https://vizproof.com' }}"

- name: Create run
  id: create_run
  run: |
    RUN_JSON=$(vrt runs:create "${{ secrets.VRT_SITE_ID }}" --json)
    RUN_ID=$(echo "$RUN_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const j=JSON.parse(s);process.stdout.write(j.runId||'')})")
    echo "run_id=$RUN_ID" >> "$GITHUB_OUTPUT"

- name: Wait
  run: vrt runs:wait "${{ steps.create_run.outputs.run_id }}" --timeout 600 --interval 10

- name: Gate
  run: vrt runs:gate "${{ steps.create_run.outputs.run_id }}" --max-fail 0 --json

Exit Codes

• 0: Success
• 1: Error / gate failed / timeout / invalid run state

The CLI will exit with code 1 if:

• API token is not configured
• API request fails
• runs:wait times out or run ends in failed
• runs:gate thresholds are exceeded (fail and optionally warn)
• flows:run finishes with success=false
• Invalid command or arguments