Eyes Utilities (Labs)
Eyes Utilities is a Java-based CLI tool that extends Applitools capabilities by communicating directly with the Applitools API. Give a command a test result URL and an enterprise key, and it writes the artifacts behind the Eyes dashboard link: diff images, baseline and actual screenshots, animated GIFs, and offline HTML reports.
Eyes Utilities is an Applitools Labs project built by our field engineering team. It is released independently of the Eyes SDKs and requires an enterprise key, available through Applitools support.
Why use it?
- Results live behind a login - the Eyes SDK returns a status and a dashboard URL, but the images that explain a failure stay in the dashboard.
- Bug reports need attachments - a ticket with the diff image attached gets acted on faster than a ticket with a link and a login prompt.
- Pipelines archive files - CI systems keep artifacts with each build. Eyes Utilities runs after the fact against any result URL, locally or in the pipeline, without changing your tests.
Requirements
- An active Applitools account
- A Java runtime environment
- An enterprise API key with the appropriate permissions (read, write, or merge, depending on the command), provided by Applitools support
Installation
Download the latest jar from the GitHub releases page.
All commands follow the same format:
java -jar EyesUtilities.jar [command] [parameters]
For example, to download the diff images of every failed step in a batch:
java -jar EyesUtilities.jar diffs -k <enterprise-key> https://eyes.applitools.com/app/batches/00002560...
Commands
Artifact downloads
diffs
Downloads the images of every failed step with the difference markings drawn on.
java -jar EyesUtilities.jar diffs -k [EntKey] [ResultUrl]
images
Downloads the baseline and actual images of a test or an entire batch.
java -jar EyesUtilities.jar images -k [EntKey] [ResultUrl]
| Flag | Description |
|---|---|
-a | Download actual images only |
-b | Download baseline images only |
-st [statuses] | Filter steps by status |
-gs | Group the output files by status |
anidiffs
Generates an animated GIF per failing step that cycles between the baseline, actual, and marked-up diff images.
java -jar EyesUtilities.jar anidiffs -k [EntKey] [ResultUrl]
| Flag | Description |
|---|---|
-i [mSecs] | Frame transition interval (default: 1000 ms) |
playback
Generates one unified animated GIF with all the actual steps of a test.
java -jar EyesUtilities.jar playback -k [EntKey] [ResultUrl]
| Flag | Description |
|---|---|
-i [mSecs] | Frame transition interval (default: 1000 ms) |
-m | Include diff marks in the animation |
Offline reports
report
Generates an offline HTML report for one or more result URLs, based on a provided Velocity template. Reports include batch and test metrics (passed, failed, and unresolved counts and rates) as well as images.
java -jar EyesUtilities.jar report -k [EntKey] [ResultUrls]
| Flag | Description |
|---|---|
-t [FilePath] | Path to the report template |
-rt [title] | Report title |
-dr [date-range] | Limit the report to a date range |
Branch operations
merge
Merges baselines from a source branch into a target branch. Requires a key with merge permissions.
java -jar EyesUtilities.jar merge -k [apiKey] -s [sourceBranch]
| Flag | Description |
|---|---|
-t [targetBranch] | Target branch (default: default) |
-d | Delete the source branch after merging |
-db | Delete baselines |
-gt [timestamp] | Only merge baselines newer than the timestamp |
copyBaselines
Copies baselines from one branch to another. Requires a key with read and write permissions.
java -jar EyesUtilities.jar copyBaselines -k [apiKey] -t [targetBranch]
| Flag | Description |
|---|---|
-s [sourceBranch] | Source branch (default: default) |
-an [appName] | Only copy baselines for the given app name |
-li [limit] | Limit the number of baselines copied |
deleteBaselines
Deletes a baseline version. Requires a key with read and write permissions.
java -jar EyesUtilities.jar deleteBaselines -k [apiKey] -bld [baselineId]
Admin operations
admin
Lists teams, lists team members, creates teams, and adds or removes users. Requires organization admin credentials.
java -jar EyesUtilities.jar admin [subcommand] -k [api-key] -or [org-id]
| Subcommand | Description |
|---|---|
getTeams | List the teams in your organization |
getUsers | List the members of a team |
addTeam | Create a new team |
addUser | Add a user to a team |
remUser | Remove a user from a team or organization |
Common flags
These flags apply across commands:
| Flag | Description |
|---|---|
-k [EntKey] | Enterprise API key (required for most operations) |
-d [pathTmpl] | Custom destination path template for downloaded artifacts |
-as [url] | Alternative Applitools server (default: eyes.applitools.com) |
-dv | Disable SSL certificate validation |
Eyes Utilities uses the proxy defined at the system level — no additional configuration is needed.
Output path templates
Destination paths passed with -d are templates, so bulk downloads land organized. The default is:
{workdir_root}/Artifacts/{batch_id}/{test_id}/{step_index}_{step_tag}_{artifact_type}.{file_ext}
Available variables:
{user_root}, {workdir_root}, {batch_id}, {test_id}, {test_name}, {test_status}, {batch_name}, {app_name}, {os}, {hostapp}, {viewport}, {branch_name}, {step_index}, {step_tag}, {artifact_type}, {file_ext}