---
title: "Uploading Snapshots"
description: "Structure your snapshot directory and upload from CI with sentry-cli."
url: https://docs.sentry.io/product/snapshots/uploading-snapshots/
---

# Uploading Snapshots

This feature is currently in Beta. Beta features are still in progress and may have bugs. We recognize the irony.

Snapshots is most effective when part of your CI pipeline. To set up, follow our guide on [integrating into CI](https://docs.sentry.io/product/snapshots/integrating-into-ci.md).

Snapshots works for any platform with a frontend. You can view specific platform examples [here](https://docs.sentry.io/product/snapshots.md#supported-platforms). This page covers the general upload structure and metadata schema.

## [Upload command](https://docs.sentry.io/product/snapshots/uploading-snapshots.md#upload-command)

You upload snapshots with the `sentry-cli snapshots upload` command, which takes a directory of images and optional JSON metadata files.

```bash
sentry-cli snapshots upload <output-dir> \
  --auth-token "$SENTRY_AUTH_TOKEN" \
  --app-id <app-id> \
  --project <project-slug> \
```

For the full command reference, including auto-detected git metadata, see [Snapshots (CLI)](https://docs.sentry.io/cli/snapshots.md). For an end-to-end CI setup, see [Integrating Into CI](https://docs.sentry.io/product/snapshots/integrating-into-ci.md).

### [Upload Structure](https://docs.sentry.io/product/snapshots/uploading-snapshots.md#upload-structure)

Each snapshot consists of two files: a `.png` image and an optional `.json` metadata file with the same base name and path. You can optionally organize snapshots into subdirectories. If using subdirectories, the filename property in the Sentry UX will include the subdirectory path.

```bash
snapshots/
├── homepage.png
├── homepage.json
├── settings/
│   ├── profile.png
│   ├── profile.json
│   ├── billing.png
│   └── billing.json
```

Filenames are the identity key for each snapshot. Keep them stable across runs so Sentry can accurately diff head against base.

### [JSON Metadata](https://docs.sentry.io/product/snapshots/uploading-snapshots.md#json-metadata)

You can include an optional JSON file to add metadata to each image:

```json
{
  "display_name": "Billing Page",
  "group": "Settings",
  "tags": {
    "surface": "billing",
    "team": "growth"
  },
  "diff_threshold": 0.01,
  "context": {
    "component": "BillingPage",
    "variant": {
      "plan": "team",
      "trial": true
    }
  }
}
```

| Field            | Type   | Description                                                                                                                                                            |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `display_name`   | string | Human-readable label shown in the comparison viewer.                                                                                                                   |
| `group`          | string | Groups related snapshots in the UI sidebar.                                                                                                                            |
| `tags`           | object | Key-value string labels attached to the snapshot. Use them to filter and group snapshots in the viewer, for example by theme, viewport, or component variant.          |
| `diff_threshold` | number | Value from `0.0` to `1.0`. Sentry reports the image as changed only when the share of changed pixels is greater than this value. `0.01` ignores changes of 1% or less. |
| `context`        | object | Arbitrary key-value context that tools and LLMs can use to help diagnose changes. Values can be strings, numbers, booleans, or nested objects.                         |

### [Supported Formats](https://docs.sentry.io/product/snapshots/uploading-snapshots.md#supported-formats)

Snapshots supports the following image formats:

* PNG
* JPEG

## [Selective Testing](https://docs.sentry.io/product/snapshots/uploading-snapshots.md#selective-testing)

If you only generate a subset of your snapshots per CI run — for example, because you run only affected tests — pass the `--selective` flag:

```bash
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** (skipped) rather than removed.

Because Sentry cannot distinguish a deliberately deleted snapshot from one that was not part of the subset, removals and renames cannot be detected when using `--selective`.

For the full `sentry-cli snapshots upload` flag reference, see [Snapshots (CLI)](https://docs.sentry.io/cli/snapshots.md).