--- title: "Snapshots (CLI)" description: "Upload snapshot images to Sentry with sentry-cli for visual diffing and GitHub status checks." url: https://docs.sentry.io/cli/snapshots/ --- # Snapshots (CLI) This feature is available only if you're in the [Early Adopter program](https://docs.sentry.io/organization/early-adopter-features.md). 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](https://docs.sentry.io/product/snapshots.md) 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. ## [Requirements](https://docs.sentry.io/cli/snapshots.md#requirements) * `sentry-cli` version 3.4.0 or later. See [Installation](https://docs.sentry.io/cli/installation.md). * A Sentry auth token with `project:write` scope (personal) or `org:ci` scope (org-level). See [Configuration](https://docs.sentry.io/cli/configuration.md#to-authenticate-manually). * A directory of `.png` or `.jpeg` images, optionally with `.json` sidecar metadata. See [Uploading Snapshots](https://docs.sentry.io/product/snapshots/uploading-snapshots.md) for the directory layout. ## [Basic Usage](https://docs.sentry.io/cli/snapshots.md#basic-usage) With `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` configured: **bash** ```bash 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 `` 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. ## [Git Metadata](https://docs.sentry.io/cli/snapshots.md#git-metadata) 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 on `pull_request` workflows. Pass any of these flags explicitly to override auto-detection, or use: * `--no-git-metadata` to skip detection entirely (for example, when uploading snapshots not tied to a commit). * `--force-git-metadata` to 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. ## [Selective Uploads](https://docs.sentry.io/cli/snapshots.md#selective-uploads) If you only upload a subset of your snapshots per CI run — for example, because you run only affected tests — pass `--selective`: **bash** ```bash 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. ## [Diff Threshold](https://docs.sentry.io/cli/snapshots.md#diff-threshold) 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: **bash** ```bash 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. ## [Flag Reference](https://docs.sentry.io/cli/snapshots.md#flag-reference) **bash** ```bash sentry-cli build snapshots [OPTIONS] --app-id ``` | Flag | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `` | Directory containing `.png` or `.jpeg` images (and optional `.json` sidecars). | | `--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 ` | Sentry auth token. Can also be set via `SENTRY_AUTH_TOKEN`. | | `-o`, `--org ` | Sentry organization slug. Can also be set via `SENTRY_ORG`. | | `-p`, `--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 ` | Float between `0.0` and `1.0`. Sentry only reports images as changed if the percentage of changed pixels exceeds this value. | | `--head-sha ` | Commit SHA for the upload. Auto-detected in CI. | | `--base-sha ` | Base commit SHA for comparison (PR only). Auto-detected from merge-base. | | `--vcs-provider ` | VCS provider (for example, `github`). Auto-detected from the git remote. | | `--head-repo-name ` | Repository in `owner/repo` format. Auto-detected from the git remote. | | `--base-repo-name ` | Base repository in `owner/repo` format (required for PRs from forks). | | `--head-ref ` | Head branch name. Auto-detected in CI. | | `--base-ref ` | Base branch name (PR only). Auto-detected from the remote tracking branch. | | `--pr-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 ` | Logging verbosity: `trace`, `debug`, `info`, `warn`, or `error`. | | `--quiet` | Suppress output while preserving exit codes. Alias: `--silent`. |