Documentation

Overview

Pixel Eagle is a visual regression testing platform. Upload screenshots from your test runs, and Pixel Eagle compares them to detect visual differences.

1. Create a Run

Group your screenshots into a run with metadata like branch name, commit hash, or platform.

2. Upload Screenshots

Upload screenshots to the run. Each screenshot is identified by a name.

3. Compare Runs

Compare two runs to find visual differences. View results in the UI or via the API.

Quick Start

Step 0Get a Token

Create a project in the Pixel Eagle UI, then generate a token from the project settings page. You'll need this token for all API and CLI operations.

Step 1Install the CLI

Install the pixeleagle CLI with a single command:

curl -fsSL https://pixel-eagle.com/install.sh | sh

This downloads the binary and makes it executable. Set INSTALL_DIR to control where it's placed (defaults to the current directory, or /usr/local/bin when run as root).

Set the token as an environment variable or pass it with --token:

export PIXEL_EAGLE_TOKEN=your_token_here

Step 2Create a Run

Create a new run with optional metadata. The command prints the run ID to stdout.

run_id=$(pixeleagle new-run --metadata '{"gitref": "1f6642d", "platform": "macOS"}')

Step 3Upload Screenshots

Upload a single screenshot:

pixeleagle upload-screenshot $run_id path/to/screenshot.png --name "home-page"

Or upload multiple screenshots at once:

pixeleagle upload-screenshots $run_id screenshots/*.png

Step 4Compare Runs

Compare against a specific run:

pixeleagle compare-run $run_id --with-run $other_run_id --wait --print-details

Or let Pixel Eagle automatically find a matching run to compare against:

# Compare against the latest run on the "main" branch
pixeleagle compare-run $run_id --filter branch:main --wait --print-details

# Compare against a run with the same platform
pixeleagle compare-run $run_id --same platform --wait --print-details

CI Integration

Add visual regression testing to your CI pipeline with a few lines.

- name: Install PixelEagle CLI
  run: curl -fsSL https://pixel-eagle.com/install.sh | sh

- name: Upload & compare screenshots
  env:
    PIXEL_EAGLE_TOKEN: ${{ secrets.PIXEL_EAGLE_TOKEN }}
  run: |
    RUN_ID=$(./pixeleagle new-run --metadata '{"commit": "${{ github.sha }}", "branch": "${{ github.ref_name }}"}')
    ./pixeleagle upload-screenshots $RUN_ID test-screenshots/*.png
    ./pixeleagle compare-run $RUN_ID --filter branch:main --wait --print-details

CLI Reference

The pixeleagle CLI simplifies uploading screenshots and triggering comparisons from CI pipelines.

Global Options

Option	Env Variable	Description
`--token <TOKEN>`	`PIXEL_EAGLE_TOKEN`	Project API token (required)
`--pixel_eagle_url <URL>`	`PIXEL_EAGLE_URL`	Server URL (default: `https://pixel-eagle.com`)

Commands

`pixeleagle new-run`

Create a new run. Prints the run ID to stdout.

Option	Description
`--metadata <JSON>`	JSON metadata (e.g. `'{"branch": "main"}'`)

`pixeleagle upload-screenshot`

Upload a single screenshot to a run.

pixeleagle upload-screenshot <RUN_ID> <PATH> [--name <NAME>]

If --name is not provided, the file name is used.

`pixeleagle upload-screenshots`

Upload multiple screenshots to a run.

pixeleagle upload-screenshots <RUN_ID> <PATH>...

`pixeleagle compare-run`

Trigger a comparison for a run.

Option	Description
`--with-run <ID>`	Compare with a specific run
`--filter <key:value>`	Find a matching run by metadata (repeatable)
`--same <key>`	Find a run with the same metadata value (repeatable)
`--wait`	Wait for the comparison to finish
`--wait_timeout <SECS>`	Timeout when waiting (default: 300s)
`--print-details`	Print detailed comparison results

`pixeleagle get-comparison`

Retrieve an existing comparison result.

pixeleagle get-comparison <RUN_ID> --with_run <OTHER_RUN_ID> [--wait] [--print-details]

API Reference

All API endpoints require a Bearer token. Pass it via the Authorization header.

POST`/runs`

Create a new run. Send a JSON body with metadata fields.

curl https://pixel-eagle.com/runs \
  --json '{"gitref": "abc123", "branch": "main"}' \
  --oauth2-bearer $token

POST`/runs/:run_id`

Upload a screenshot to a run. Use multipart form data with data (the image file) and screenshot (the name).

curl https://pixel-eagle.com/runs/$run_id \
  -F 'data=@file.png' \
  -F 'screenshot=home-page' \
  --oauth2-bearer $token

POST`/runs/:run_id_a/compare/:run_id_b`

Trigger a comparison between two runs. Screenshots are matched by name.

curl https://pixel-eagle.com/runs/$run_id_a/compare/$run_id_b \
  -X POST --oauth2-bearer $token

GET`/runs/:run_id_a/compare/:run_id_b`

Retrieve comparison results. Poll this endpoint until all screenshot comparisons are complete.

POST`/runs/:run_id/compare/auto`

Automatically find a matching run to compare against based on metadata filters. See Auto Comparison for details.

curl https://pixel-eagle.com/runs/$run_id/compare/auto \
  --json '{"branch": "main"}' \
  --oauth2-bearer $token

POST`/runs/:run_id/hashes`

Send screenshot hashes before uploading. If the server already has the image, the upload can be skipped - saving bandwidth in CI pipelines where screenshots rarely change.

Comparison Methods

Pixel Eagle supports multiple comparison algorithms. You can configure the method in your project settings.

Pixel XOR

Default

Compares screenshots pixel by pixel using XOR. Differences are highlighted in red on a transparent background.

Fast and precise - best for catching any pixel-level change.

FLIP

A perceptual comparison algorithm based on NVIDIA's FLIP metric. It models the human visual system to detect differences that would actually be noticeable to a viewer.

Best for ignoring sub-pixel rendering differences while catching meaningful visual changes. Can be enabled for all screenshots or only specific ones.

Threshold

Each project has a configurable difference threshold. Comparisons with a score below the threshold are treated as identical, reducing noise from insignificant changes.

Auto Comparison

Instead of specifying a run ID to compare against, you can let Pixel Eagle automatically select the best matching run based on metadata filters. This is especially useful in CI where you want to compare against the latest run on a base branch.

Exact Match

Filter for the latest run with a specific metadata value:

# API
curl https://pixel-eagle.com/runs/$run_id/compare/auto \
  --json '{"branch": "main"}' --oauth2-bearer $token

# CLI
pixeleagle compare-run $run_id --filter branch:main

Same Value Match

Find a run that has the same value for a metadata field as the current run. Use the special <equal> marker in the API, or --same in the CLI:

# API
curl https://pixel-eagle.com/runs/$run_id/compare/auto \
  --json '{"platform": "<equal>"}' --oauth2-bearer $token

# CLI
pixeleagle compare-run $run_id --same platform

Combining Filters

You can combine multiple filters to narrow down the matching run. For example, find the latest run on the "main" branch with the same platform:

# API
curl https://pixel-eagle.com/runs/$run_id/compare/auto \
  --json '{"branch": "main", "platform": "<equal>"}' --oauth2-bearer $token

# CLI
pixeleagle compare-run $run_id --filter branch:main --same platform