Snapshots (CLI)
Upload snapshot images to Sentry with sentry-cli for visual diffing and GitHub status checks.
This feature is currently in Beta. Beta features are still in progress and may have bugs. We recognize the irony.
The sentry-cli snapshots upload command uploads a directory of images to Snapshots for visual diffing against a base build.
sentry-cli snapshots upload is experimental. The command is subject to breaking changes, including removal, in any Sentry CLI release.
sentry-cliversion 3.5.0 or later. See Installation.- A Sentry auth token with
project:writescope (personal) ororg:ciscope (org-level). See Configuration. - A directory of
.pngor.jpegimages, optionally with.jsonsidecar metadata. See Uploading Snapshots for the directory layout.
With SENTRY_AUTH_TOKEN, SENTRY_ORG, and SENTRY_PROJECT configured:
sentry-cli snapshots upload ./snapshots --app-id web-frontend
sentry-cli snapshots upload ./snapshots --app-id web-frontend
--app-id identifies your app or bundle (for example, web-frontend, ios-app). Keep it consistent across uploads — Sentry uses it to match head and base snapshots.
The <PATH> argument is the directory containing images. Images may be nested in subdirectories; subdirectory paths become part of each snapshot's filename in the Sentry UI.
When run in a supported CI environment, sentry-cli automatically detects:
--head-sha— the current commit SHA.--base-sha— the merge-base against the remote tracking branch (PR builds only).--vcs-provider— inferred from the git remote (for example,github).--head-repo-name/--base-repo-name— inferred from the git remote.--head-ref/--base-ref— current and base branch names.--pr-number— detected from GitHub Actions environment variables onpull_requestworkflows.
Pass any of these flags explicitly to override auto-detection, or use:
--no-git-metadatato skip detection entirely (for example, when uploading snapshots not tied to a commit).--force-git-metadatato require detection outside CI (for example, when testing CI behavior locally).
For PRs from forks, set --base-repo-name to the upstream repository so Sentry can locate the base build.
If you only upload a subset of your snapshots per CI run — for example, because you run only affected tests — pass --selective:
sentry-cli snapshots upload ./snapshots --app-id web-frontend --selective
sentry-cli snapshots upload ./snapshots --app-id web-frontend --selective
When an upload is marked as selective, Sentry only diffs the snapshots you uploaded. Any snapshot that exists in the base build but was not included in the upload is treated as unchanged rather than removed. Removals and renames cannot be detected when using --selective, because Sentry cannot distinguish a deliberately deleted snapshot from one that was not part of the subset.
Use --diff-threshold to ignore sub-pixel or anti-aliasing noise. The value is a float between 0.0 and 1.0 representing the fraction of pixels that must change before Sentry reports an image as changed:
sentry-cli snapshots upload ./snapshots --app-id web-frontend --diff-threshold 0.01
sentry-cli snapshots upload ./snapshots --app-id web-frontend --diff-threshold 0.01
With a value of 0.01, images with less than 1% of pixels changed are reported as unchanged.
sentry-cli snapshots upload [OPTIONS] --app-id <APP_ID> <PATH>
sentry-cli snapshots upload [OPTIONS] --app-id <APP_ID> <PATH>
| Flag | Description |
|---|---|
<PATH> | Directory containing .png or .jpeg images (and optional .json sidecars). |
--app-id <APP_ID> | Identifier for the app or bundle (for example, web-frontend, ios-app). Must be consistent across uploads — Sentry uses it to match head and base snapshots. Max 255 chars. |
--auth-token <TOKEN> | Sentry auth token. Can also be set via SENTRY_AUTH_TOKEN. |
-o, --org <ORG> | Sentry organization slug. Can also be set via SENTRY_ORG. |
-p, --project <PROJECT> | Sentry project slug. Can also be set via SENTRY_PROJECT. |
--selective | Mark the upload as a subset. Use when uploading only a portion of your snapshots (for example, affected tests only). |
--diff-threshold <THRESHOLD> | Float between 0.0 and 1.0. Sentry only reports images as changed if the percentage of changed pixels exceeds this value. |
--head-sha <SHA> | Commit SHA for the upload. Auto-detected in CI. |
--base-sha <SHA> | Base commit SHA for comparison (PR only). Auto-detected from merge-base. |
--vcs-provider <PROVIDER> | VCS provider (for example, github). Auto-detected from the git remote. |
--head-repo-name <OWNER/REPO> | Repository in owner/repo format. Auto-detected from the git remote. |
--base-repo-name <OWNER/REPO> | Base repository in owner/repo format (required for PRs from forks). |
--head-ref <BRANCH> | Head branch name. Auto-detected in CI. |
--base-ref <BRANCH> | Base branch name (PR only). Auto-detected from the remote tracking branch. |
--pr-number <NUMBER> | Pull request number. Auto-detected in GitHub Actions pull_request workflows. |
--no-git-metadata | Skip automatic git metadata detection. |
--force-git-metadata | Force git metadata collection outside CI. |
--log-level <LEVEL> | Logging verbosity: trace, debug, info, warn, or error. |
--quiet | Suppress output while preserving exit codes. Alias: --silent. |
sentry-cli snapshots download downloads baseline snapshot images from Sentry to a local directory.
sentry-cli snapshots download --app-id web-frontend
sentry-cli snapshots download --app-id web-frontend
| Flag | Description |
|---|---|
--app-id <APP_ID> | Resolve the latest baseline snapshot for this app. Mutually exclusive with --snapshot-id. |
--snapshot-id <ID> | Download a specific snapshot by artifact ID. Mutually exclusive with --app-id. |
--branch <BRANCH> | Filter by git branch when using --app-id. |
--output <DIR> | Destination directory for extracted images. Default: ./snapshots-base/. |
-o, --org <ORG> | Sentry organization slug. Can also be set via SENTRY_ORG. |
-p, --project <PROJECT> | Sentry project slug (numeric ID required with org auth tokens). Can also be set via SENTRY_PROJECT. |
--auth-token <TOKEN> | Sentry auth token. Can also be set via SENTRY_AUTH_TOKEN. |
--quiet | Suppress output while preserving exit codes. |
sentry-cli snapshots diff compares two directories of snapshot images locally using odiff and outputs JSON with per-image results.
sentry-cli snapshots diff ./snapshots-base ./snapshots-head
sentry-cli snapshots diff ./snapshots-base ./snapshots-head
On first run, sentry-cli downloads the odiff binary and caches it at ~/.sentry-cli/odiff/.
| Flag | Description |
|---|---|
<BASE_DIR> | Path to the baseline image directory. |
<HEAD_DIR> | Path to the head image directory. |
--output <DIR> | Directory for diff mask images. Default: ./diff-output/. |
--threshold <FLOAT> | Pixel color difference threshold (0.0–1.0). Default: 0.01. |
--fail-on-diff | Exit with code 1 if any differences are found. |
--no-antialiasing | Disable antialiasing detection. |
--selective | Treat images in the base directory but missing from head as skipped instead of removed. |
--quiet | Suppress output while preserving exit codes. |
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").