Quick Start

This guide walks you through capturing screenshots, comparing them against baselines, and reviewing visual diffs — all from your terminal.

Prerequisites

UI Inspect CLI installed (pnpm add -D @ui-inspect/cli)
A running web application to test
An API key from your UI Inspect dashboard

Initialize your project

npx ui-inspect init

This creates a ui-inspect.config.yml file in your project root:

ui-inspect.config.yml

projectId: "your-project-id"
baseUrl: "http://localhost:3000"
threshold: 0.1
failOnDiff: true
autoApprove: false

screenshots:
  - name: "homepage"
    url: "/"
    viewports:
      - name: "desktop"
        width: 1920
        height: 1080
      - name: "mobile"
        width: 375
        height: 667

  - name: "dashboard"
    url: "/dashboard"
    viewports:
      - name: "desktop"
        width: 1920
        height: 1080

Set your API token

Get an API key from your dashboard under Settings → API Keys, then export it:

export UI_INSPECT_TOKEN="uii_your-api-key-here"

Never commit your API token to version control. Use CI/CD secrets instead.

Run your first build

Make sure your app is running locally, then:

npx ui-inspect build --project your-project-id

The CLI will:

Launch a headless browser
Navigate to each URL in your config
Capture screenshots at every viewport
Compare against existing baselines
Report any visual differences

Review results

✓ Build created: build_abc123
✓ Captured 4 screenshots
✓ Compared against baselines

Results:
  ✓ homepage/desktop — No diff
  ✓ homepage/mobile — No diff
  ⚠ dashboard/desktop — 2.3% diff (threshold: 10%)
  ✗ dashboard/mobile — 15.7% diff (FAILED)

Build: FAILED (1 regression found)

Open your dashboard to see the visual diffs with highlighted regions.

Approve baselines

For new components without existing baselines, approve the initial screenshots:

npx ui-inspect approve --project your-project-id

This sets the current screenshots as the baseline for future comparisons.

Add to CI/CD

The real power of UI Inspect comes from running in CI. Here's a quick GitHub Actions setup:

.github/workflows/visual-regression.yml

name: Visual Regression Tests
on: [pull_request]

jobs:
  visual-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: pnpm install
      - run: pnpm build
      - run: pnpm start &

      - name: Run visual tests
        run: npx ui-inspect build --project $PROJECT_ID --report --pr ${{ github.event.pull_request.number }}
        env:
          UI_INSPECT_TOKEN: ${{ secrets.UI_INSPECT_TOKEN }}
          PROJECT_ID: ${{ secrets.UI_INSPECT_PROJECT_ID }}

Or generate it automatically:

npx ui-inspect ci-setup --provider github

Next steps

CLI Reference — Full command documentation
Configuration — Advanced config options
TurboSnap — Skip unchanged components for faster builds
CI Integration Guide — Detailed CI/CD setup

On this page