Snapshots (CLI)
Upload snapshot images to Sentry with sentry-cli for visual diffing and GitHub status checks.
This feature is available only if you're in the Early Adopter program. Features available to Early Adopters are still in-progress and may have bugs. We recognize the irony.
The sentry-cli build snapshots command uploads a directory of images to Snapshots for visual diffing against a base build.
sentry-cli build snapshots is experimental. The command is subject to breaking changes, including removal, in any Sentry CLI release.
sentry-cliversion 3.4.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 build snapshots ./snapshots --app-id web-frontend
sentry-cli build snapshots ./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 build snapshots ./snapshots --app-id web-frontend --selective
sentry-cli build snapshots ./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 build snapshots ./snapshots --app-id web-frontend --diff-threshold 0.01
sentry-cli build snapshots ./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 build snapshots [OPTIONS] --app-id <APP_ID> <PATH>
sentry-cli build snapshots [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. |
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").