Commands

release

Work with Sentry releases

Commands

`sentry release list [<org/project>]`

List releases with adoption and health metrics

Arguments:

Argument	Description
`[<org/project>]`	<org>/ (all projects), <org>/<project>, or <project> (search)

Options:

Option	Description
`-n, --limit <limit>`	Maximum number of releases to list (default: "25")
`-s, --sort <sort>`	Sort: date, sessions, users, crash_free_sessions (cfs), crash_free_users (cfu) (default: "date")
`-e, --environment <environment>...`	Filter by environment (repeatable, comma-separated)
`-t, --period <period>`	Health stats period (e.g., 24h, 7d, 14d, 90d) (default: "90d")
`--status <status>`	Filter by status: open (default) or archived (default: "open")
`-f, --fresh`	Bypass cache, re-detect projects, and fetch fresh data
`-c, --cursor <cursor>`	Navigate pages: "next", "prev", "first" (or raw cursor string)

Examples:

# List releases (project auto-detected)
sentry release list

# List all releases in an organization
sentry release list my-org/

# List releases for one project
sentry release list my-org/my-project

# Sort by crash-free sessions
sentry release list --sort cfs

# Filter by environment
sentry release list --environment production

# Show the last 7 days of health data
sentry release list --period 7d

# Output as JSON
sentry release list --json

# Fetch the next page
sentry release list my-org/ -c next

`sentry release view <org/version>`

View release details with health metrics

Arguments:

Argument	Description
`<org/version>`	[<org>/]<version> - Release version to view

Options:

Option	Description
`-f, --fresh`	Bypass cache, re-detect projects, and fetch fresh data

Examples:

# View release details
sentry release view 1.0.0

# View a release in an explicit organization
sentry release view my-org/1.0.0

# View a release whose version contains a package name
sentry release view "sentry-cli@0.24.0"

# Output as JSON
sentry release view 1.0.0 --json

`sentry release create <org/version>`

Create a release

Arguments:

Argument	Description
`<org/version>`	[<org>/]<version> - Release version to create

Options:

Option	Description
`-p, --project <project>`	Associate with project(s), comma-separated
`--finalize`	Immediately finalize the release (set dateReleased)
`--ref <ref>`	Git ref (branch or tag name)
`--url <url>`	URL to the release source
`-n, --dry-run`	Show what would happen without making changes

Examples:

# Create a release
sentry release create 1.0.0

# Create a release in an explicit organization
sentry release create my-org/1.0.0

# Create and finalize a release
sentry release create 1.0.0 --finalize

# Create a release for specific projects
sentry release create 1.0.0 --project proj-a,proj-b

# Typical CI release: create, associate commits, finalize, and record a deploy
sentry release create my-org/1.0.0 --project my-project
sentry release set-commits my-org/1.0.0 --auto
sentry release finalize my-org/1.0.0
sentry release deploy my-org/1.0.0 production

# Create a release from a proposed version
sentry release create "$(sentry release propose-version --json | jq -r .version)"

# Set the release ref and URL
sentry release create 1.0.0 --ref main --url https://github.com/org/repo/releases/tag/1.0.0

# Preview without creating
sentry release create 1.0.0 --dry-run

`sentry release finalize <org/version>`

Finalize a release

Arguments:

Argument	Description
`<org/version>`	[<org>/]<version> - Release version to finalize

Options:

Option	Description
`--released <released>`	Custom release timestamp (ISO 8601). Defaults to now.
`--url <url>`	URL for the release
`-n, --dry-run`	Show what would happen without making changes

Examples:

# Finalize a release
sentry release finalize 1.0.0

# Finalize a release in an explicit organization
sentry release finalize my-org/1.0.0

# Set a custom release timestamp
sentry release finalize 1.0.0 --released 2025-01-01T00:00:00Z

# Preview without finalizing
sentry release finalize 1.0.0 --dry-run

`sentry release delete <org/version>`

Delete a release

Arguments:

Argument	Description
`<org/version>`	[<org>/]<version> - Release version to delete

Options:

Option	Description
`-y, --yes`	Skip confirmation prompt
`-f, --force`	Force the operation without confirmation
`-n, --dry-run`	Show what would happen without making changes

Examples:

# Delete a release (prompts for confirmation)
sentry release delete my-org/1.0.0

# Skip confirmation
sentry release delete my-org/1.0.0 --yes

# Preview without deleting
sentry release delete my-org/1.0.0 --dry-run

`sentry release archive <org/version>`

Archive a release

Arguments:

Argument	Description
`<org/version>`	[<org>/]<version> - Release version to archive

Options:

Option	Description
`-n, --dry-run`	Show what would happen without making changes

Examples:

# Archive a release (hide it from the default list, but keep it)
sentry release archive 1.0.0

# Archive a release in an explicit organization
sentry release archive my-org/1.0.0

# Preview without archiving
sentry release archive my-org/1.0.0 --dry-run

`sentry release restore <org/version>`

Restore an archived release

Arguments:

Argument	Description
`<org/version>`	[<org>/]<version> - Release version to restore

Options:

Option	Description
`-n, --dry-run`	Show what would happen without making changes

Examples:

# Restore a previously archived release
sentry release restore 1.0.0

# Restore a release in an explicit organization
sentry release restore my-org/1.0.0

# Preview without restoring
sentry release restore 1.0.0 --dry-run

`sentry release deploy <org/version> <environment> [<name>]`

Create a deploy for a release

Arguments:

Argument	Description
`<org/version>`	[<org>/]<version> - Release version
`<environment>`	Deploy environment (e.g. production)
`[<name>]`	Optional deploy name (quote multi-word names, e.g. "Deploy #42")

Options:

Option	Description
`--url <url>`	URL for the deploy
`--started <started>`	Deploy start time (ISO 8601)
`--finished <finished>`	Deploy finish time (ISO 8601)
`-t, --time <time>`	Deploy duration in seconds (sets started = now - time, finished = now)
`-n, --dry-run`	Show what would happen without making changes

Examples:

# Create a deploy
sentry release deploy 1.0.0 production

# Create a named deploy in an explicit organization
sentry release deploy my-org/1.0.0 staging "Deploy #42"

# Attach a deploy URL
sentry release deploy 1.0.0 production --url https://example.com

# Record a deploy duration in seconds
sentry release deploy 1.0.0 production --time 120

# Preview without creating
sentry release deploy 1.0.0 production --dry-run

`sentry release deploys <org/version>`

List deploys for a release

Arguments:

Argument	Description
`<org/version>`	[<org>/]<version> - Release version

Examples:

# List deploys for a release
sentry release deploys 1.0.0

# List deploys for a release in an explicit organization
sentry release deploys my-org/1.0.0

# Output as JSON
sentry release deploys 1.0.0 --json

`sentry release set-commits <org/version>`

Set commits for a release

Arguments:

Argument	Description
`<org/version>`	[<org>/]<version> - Release version

Options:

Option	Description
`--auto`	Auto-discover commits via repository integration (needs a git checkout or CI repository variables)
`--local`	Read commits from local git history
`--clear`	Clear all commits from the release
`--commit <commit>`	Explicit commit as REPO@SHA or REPO@PREV..SHA (comma-separated)
`--path <path>`	Filter commits to these paths (comma-separated). Implies --local.
`--from <from>`	Read the local range ..HEAD (e.g. previous release tag). Implies --local.
`--initial-depth <initial-depth>`	Number of commits to read with --local (default: "20")

Examples:

# Associate commits using the repository integration
sentry release set-commits 1.0.0 --auto

# Set commits from local git history
sentry release set-commits my-org/1.0.0 --local

# Read up to 50 local commits
sentry release set-commits 1.0.0 --local --initial-depth 50

# Only include commits that touch specific paths
sentry release set-commits 1.0.0 --path apps/mobile,packages/shared-ui

# Read local commits since a previous release tag
sentry release set-commits 1.0.0 --from v0.9.0

# Set an explicit commit range
sentry release set-commits 1.0.0 --commit owner/repo@abc123..def456

# Clear the release's commits
sentry release set-commits 1.0.0 --clear

`sentry release propose-version`

Propose a release version

Examples:

# Propose a version from git HEAD
sentry release propose-version

# Output as JSON
sentry release propose-version --json

# Create a release named after the proposed version
sentry release create "$(sentry release propose-version --json | jq -r .version)"

All commands support --json for machine-readable output and --fields to select specific JSON fields.

Release workflow

A typical CI release creates the release, associates commits, finalizes it, and records a deploy. The sentry release create examples above show the full sequence.

Important Notes

Version matching: The release version must match the release value in your Sentry.init() call. If your SDK uses "1.0.0", create the release as sentry release create org/1.0.0 (version = 1.0.0), not sentry release create org/myapp/1.0.0.
The org/ prefix is the org slug: In sentry release create sentry/1.0.0, sentry is the org slug and 1.0.0 is the version. The / separates org from version — it is not part of the version string.
--auto needs a git checkout or CI variables: The --auto flag lists repos from the Sentry API and matches against your local origin remote URL. Without one (for example, Docker builds that exclude .git), it uses the repository and commit from the CI provider: GitHub Actions, GitLab CI, Bitbucket Pipelines, Vercel production builds, Render, Railway, CircleCI, Buildkite, Netlify, and Azure Pipelines. Otherwise, pass --commit owner/repo@<sha>.
Commits need a repository in Sentry: --auto and --commit only work for repositories that a source code integration (GitHub, GitLab, Bitbucket, Azure DevOps) added to your Sentry org. --commit takes the name that sentry repo list shows. When a name only differs from Sentry's (for example in case), the CLI uses Sentry's name and prints a warning. If your org has no repositories, connect an integration in Sentry under Settings → Integrations; the CLI cannot install integrations yet. Until then, --local reads commits from local git history.
Default mode tries --auto first: When neither --auto nor --local is specified, set-commits tries auto-discovery first and falls back to local git history if the integration isn't configured.