CLI Reference
The pixeleagle CLI simplifies uploading screenshots and triggering comparisons from CI pipelines. Source code and additional documentation are available on GitHub .
Global Options
| Option | Env Variable | Description |
|---|---|---|
--token <TOKEN> | PIXEL_EAGLE_TOKEN | Project API token (required) |
--format <FORMAT> | Output format: text (default) or json | |
--pixel-eagle-url <URL> | PIXEL_EAGLE_URL | Server URL (default: https://pixel-eagle.com). Only available in builds with the self-hosted feature |
Commands
pixeleagle new-run
Create a new run. Prints the run ID to stdout, or {"id": <ID>} with --format json.
| 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>] [--clean-name]
| Option | Description |
|---|---|
--name <NAME> | Name of the screenshot (default: the file name) |
--clean-name | Use the file name without its extension as the screenshot name |
pixeleagle upload-screenshots
Upload multiple screenshots to a run.
pixeleagle upload-screenshots <RUN_ID> <PATH>... [--clean-name]
| Option | Description |
|---|---|
--clean-name | Use the file names without their extension as the screenshot names |
pixeleagle compare-run
Trigger a comparison for a run. The target is either an explicit run (--with-run) or the latest run matching metadata filters (--filter / --same).
| 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]
| Option | Description |
|---|---|
--with-run <ID> | The run the comparison was made with (required) |
--wait | Wait for the comparison to finish |
--wait-timeout <SECS> | Timeout when waiting (default: 300s) |
--print-details | Print detailed comparison results |
pixeleagle download-screenshot
Download the screenshot image for a given name from a comparison result. The project must be public.
pixeleagle download-screenshot <RUN_ID> <NAME> --with-run <OTHER_RUN_ID> --output <PATH>
| Option | Description |
|---|---|
--with-run <ID> | The run the comparison was made with (required) |
--output <PATH>, -o <PATH> | Output file path (required) |
pixeleagle download-diff
Download the visual diff image for a given screenshot name from a comparison. The project must be public.
pixeleagle download-diff <RUN_ID> <NAME> --with-run <OTHER_RUN_ID> --output <PATH>
| Option | Description |
|---|---|
--with-run <ID> | The run the comparison was made with (required) |
--output <PATH>, -o <PATH> | Output file path (required) |