@thepixelhouse/cli

Visual regression testing from the command line. Capture screenshots, diff them against baselines, run regression suites, and manage monitors — all from your terminal or CI pipeline.

Install

npm install -g @thepixelhouse/cli

Or run without installing:

npx @thepixelhouse/cli screenshot https://example.com

Quick start

# 1. Create a config file
pixelhouse init

# 2. Set your API key
export PIXELHOUSE_API_KEY=ph_live_your_key_here

# 3. Capture your first screenshot
pixelhouse screenshot https://your-site.com --project prj_xxx

# 4. Promote it to a baseline
pixelhouse baseline create ss_abc123 --project prj_xxx --url https://your-site.com

# 5. Run a regression test
pixelhouse regression run --url https://your-site.com --baseline bl_xyz789

Authentication

The CLI needs an API key. Provide it in any of these ways (highest priority first):

1. CLI flag: --api-key ph_live_xxx
2. Environment variable: PIXELHOUSE_API_KEY=ph_live_xxx
3. Config file: apiKey field in .pixelhouserc.json

Get your API key from the dashboard.

Commands

pixelhouse screenshot <url>

Capture a screenshot of a URL.

pixelhouse screenshot https://example.com
pixelhouse screenshot https://example.com --viewport mobile
pixelhouse screenshot https://example.com --viewport 1440x900 --full-page
pixelhouse screenshot https://example.com --output ./screenshot.png

| Option | Description | Default | |--------|-------------|---------| | --viewport <preset\|WxH> | Viewport size (desktop, tablet, mobile, or custom) | desktop | | --full-page | Capture the full scrollable page | false | | --project <id> | Project ID | from config | | --output <path> | Save PNG to a local file | - | | --wait-for <strategy> | Load strategy (networkIdle, domContentLoaded, load) | networkIdle |

pixelhouse compare <screenshot-a> <screenshot-b>

Compare two screenshots for visual differences.

pixelhouse compare ss_abc123 ss_def456
pixelhouse compare ss_abc123 ss_def456 --threshold 0.5 --output ./diff.png

| Option | Description | Default | |--------|-------------|---------| | --threshold <number> | Diff threshold percentage (0-100) | 1.0 | | --output <path> | Save diff image to a local file | - |

pixelhouse regression run

Run visual regression tests against baselines.

Single URL mode:

pixelhouse regression run --url https://example.com --baseline bl_xyz789

Config-driven mode (reads pages from .pixelhouserc.json):

pixelhouse regression run
pixelhouse regression run --ci
pixelhouse regression run --fail-on-diff

| Option | Description | Default | |--------|-------------|---------| | --url <url> | Single URL to test | - | | --baseline <id> | Baseline ID to compare against | - | | --threshold <number> | Diff threshold percentage | 1.0 | | --viewport <preset\|WxH> | Viewport size | desktop | | --ci | CI mode with exit codes | false | | --fail-on-diff | Non-zero exit on any diff exceeding threshold | false |

Exit codes (CI mode):

• 0 — all tests passed
• 1 — visual regression detected
• 2 — error (capture failed, network error, etc.)

pixelhouse baseline <subcommand>

Manage screenshot baselines.

# List baselines
pixelhouse baseline list --project prj_xxx
pixelhouse baseline list --project prj_xxx --branch staging

# Promote a screenshot to baseline
pixelhouse baseline create ss_abc123 --project prj_xxx --url https://example.com
pixelhouse baseline create ss_abc123 --project prj_xxx --url https://example.com --branch staging

# Delete a baseline
pixelhouse baseline delete bl_xyz789

pixelhouse monitor <subcommand>

Manage scheduled visual monitors.

# List monitors
pixelhouse monitor list --project prj_xxx

# Add a monitor (checks every hour)
pixelhouse monitor add https://example.com --project prj_xxx --every 1h

# Add with custom interval and threshold
pixelhouse monitor add https://example.com --project prj_xxx --every 30m --threshold 0.5

# Pause / resume / delete
pixelhouse monitor pause mon_abc123
pixelhouse monitor resume mon_abc123
pixelhouse monitor delete mon_abc123

| Interval | Cron equivalent | |----------|-----------------| | 30m | */30 * * * * | | 1h | 0 */1 * * * | | 6h | 0 */6 * * * | | 1d | 0 0 */1 * * |

You can also pass a raw cron expression: --every "0 9 * * 1-5".

pixelhouse mcp serve

Start a local MCP server over stdio. AI coding assistants (Claude Code, Cursor, Windsurf) connect to it as a child process — no network roundtrip for the MCP protocol.

# Claude Code
claude mcp add pixelhouse -- pixelhouse mcp serve

# With explicit API key
claude mcp add pixelhouse -- pixelhouse mcp serve --api-key ph_live_xxx

For Cursor and Windsurf, add to your MCP config:

{
  "mcpServers": {
    "pixelhouse": {
      "command": "pixelhouse",
      "args": ["mcp", "serve"]
    }
  }
}

The server exposes the same tools as the hosted MCP server at mcp.thepixelhouse.co.uk: take_screenshot, compare_screenshots, run_visual_regression, create_baseline, approve_changes, list_baselines, get_diff_report, and discover_pages.

pixelhouse init

Create a .pixelhouserc.json configuration file.

pixelhouse init
pixelhouse init --force  # overwrite existing

Configuration

Create a .pixelhouserc.json in your project root (or run pixelhouse init):

{
  "apiKey": "ph_live_your_key_here",
  "apiUrl": "https://api.thepixelhouse.co.uk",
  "projectId": "prj_xxx",
  "viewport": "desktop",
  "threshold": 1.0,
  "branch": "main",
  "pages": [
    {
      "url": "https://your-site.com",
      "baselineId": "bl_abc123",
      "viewport": "desktop",
      "threshold": 1.0
    },
    {
      "url": "https://your-site.com/pricing",
      "baselineId": "bl_def456",
      "viewport": "mobile"
    }
  ]
}

The CLI searches for this file starting from your current directory, walking up to the filesystem root.

CI/CD integration

GitHub Actions

- name: Run visual regression tests
  env:
    PIXELHOUSE_API_KEY: ${{ secrets.PIXELHOUSE_API_KEY }}
  run: npx @thepixelhouse/cli regression run --ci

GitLab CI

visual-regression:
  script:
    - npx @thepixelhouse/cli regression run --ci
  variables:
    PIXELHOUSE_API_KEY: $PIXELHOUSE_API_KEY

Global options

These options apply to all commands:

| Option | Description | |--------|-------------| | --api-key <key> | API key (overrides env var and config) | | --api-url <url> | API base URL | | --json | Output results as JSON | | --no-color | Disable coloured output | | -v, --version | Print version | | -h, --help | Print help |

JSON output

Pass --json to any command for machine-readable output:

pixelhouse screenshot https://example.com --json | jq '.id'
pixelhouse regression run --json | jq '.summary'

Links

• Documentation
• Dashboard
• API reference

Licence

MIT - ToggleKit Ltd