Table of Contents

  1. Introduction
  2. Why Use Sentry‑CLI?
  3. Installation & Initial Setup
  4. Authentication Strategies
  5. Core Commands Overview
  6. Integrating Sentry‑CLI into CI/CD Pipelines
  7. Advanced Features
  8. Common Pitfalls & Troubleshooting
  9. Best Practices & Recommendations
  10. Conclusion
  11. Resources

Introduction

Error monitoring has become a cornerstone of modern software development. Among the many tools available, Sentry stands out for its rich feature set, real‑time alerting, and deep integration with a variety of languages and frameworks. While the Sentry web UI provides a powerful way to view and triage issues, the Sentry Command‑Line Interface (sentry‑cli) brings that capability directly into your terminal and automation pipelines.

In this article we’ll dive deep into sentry‑cli: what it is, why you should care, how to install and configure it, and how to leverage its full power in everyday development and continuous‑integration workflows. By the end, you’ll be equipped to:

  • Create and manage releases programmatically.
  • Upload source maps, debug symbols, and other artifacts automatically.
  • Track deployments across environments.
  • Automate issue triage, releases, and rollbacks.

Whether you’re a front‑end engineer fighting “minified code” stack traces, a mobile developer needing native symbolication, or a DevOps specialist building robust CI pipelines, sentry‑cli can streamline your workflow and improve error visibility.

Why Use Sentry‑CLI?

“If you’re already using Sentry in production, you’re missing out on the automation that sentry‑cli provides.” – Sentry Team

Sentry‑CLI is more than a simple wrapper around the Sentry API. It offers several tangible benefits:

BenefitDescription
AutomationIntegrate release creation, source‑map upload, and deployment tagging directly into build scripts.
SpeedUpload large bundles (source maps, symbol files) via multipart streaming, avoiding API throttling.
ConsistencyEnforce a single source of truth for release versioning across all environments.
SecurityUse auth tokens scoped to specific projects, reducing the risk of credential leakage.
ExtensibilityHook into Sentry’s API for custom workflows (e.g., auto‑resolve issues on successful deploy).

In short, sentry‑cli turns Sentry from a passive observability platform into an active participant in your release pipeline.

Installation & Initial Setup

System Requirements

  • Operating Systems – macOS, Linux, Windows (via PowerShell or WSL).
  • Supported Architectures – x86_64, arm64 (official binaries).
  • Dependencies – None. The binary is statically compiled and bundled with all required libraries.

Installing the Binary

The easiest way is to use the official installer script:

curl -sL https://sentry.io/get-cli/ | bash

On macOS with Homebrew:

brew install getsentry/tools/sentry-cli

For Windows PowerShell:

iwr https://sentry.io/get-cli/ -OutFile install.ps1
.\install.ps1

Note: The script automatically detects the OS and architecture, downloads the appropriate tarball/zip, and places sentry-cli in /usr/local/bin (or $HOME/.local/bin on Linux). Ensure the directory is on your $PATH.

Verifying the Installation

$ sentry-cli --version
sentry-cli 2.30.0

If you see the version printed, you’re ready to move on.

Authentication Strategies

Sentry‑CLI authenticates using auth tokens (also called “DSN tokens”). Tokens can be scoped to a single project, an organization, or specific API scopes (e.g., project:write, event:write). The recommended approach is to create a project‑level token with at least the following scopes:

  • project:read
  • project:write
  • org:read
  • org:write

Creating a Token

  1. Log into your Sentry organization.
  2. Navigate to Settings → Developer Settings → Auth Tokens.
  3. Click Create New Token, give it a descriptive name (e.g., “CI/CD Release Bot”), select the required scopes, and click Create Token.
  4. Copy the generated token; you’ll never see it again.

Storing the Token Securely

  • Local Development – Add the token to your shell profile:

    export SENTRY_AUTH_TOKEN=your_generated_token_here

  • CI/CD – Store the token as a secret variable:

    • GitHub Actions: SENTRY_AUTH_TOKEN secret.
    • GitLab CI: SENTRY_AUTH_TOKEN variable (masked).
    • Jenkins: Credential of type “Secret text”.

Security Tip: Never hard‑code the token in source files or commit it to version control. Use the environment variable approach or secret‑management tools (e.g., HashiCorp Vault).

Configuring the Default Organization & Project

You can set defaults in a .sentryclirc file at the repository root:

[defaults]
org = my-org
project = my-webapp

Or you can pass them explicitly on each command using --org and --project.

Core Commands Overview

Sentry‑CLI provides a rich set of sub‑commands. Below we’ll focus on the most frequently used ones, grouped by functional area.

Creating & Managing Releases

A release in Sentry is a logical version identifier (e.g., v1.2.3, 2024-09-15.1). Releases enable source‑map resolution, release health tracking, and deployment notifications.

1. Create a Release

sentry-cli releases new -p my-webapp 2024.09.15
  • -p flags associate the release with a project (multiple -p allowed).
  • The release identifier can be any string but should be unique across the organization.

2. Set Release Commits

If your repository is hosted on GitHub, GitLab, or Bitbucket, you can automatically attach commit metadata:

sentry-cli releases set-commits \
  --auto \
  --repo my-org/my-webapp \
  2024.09.15
  • --auto discovers commits between the previous release (or the first commit) and HEAD.
  • This data powers Release Health dashboards (crash-free sessions, error rate).

3. Finalize a Release

After uploading all artifacts, you should finalize the release to mark it as ready for consumption:

sentry-cli releases finalize 2024.09.15

Finalizing makes the release immutable and triggers any post‑release hooks you’ve configured in Sentry.

4. Delete a Release (Caution)

sentry-cli releases delete 2024.09.15

Only use this for stale or test releases; deleting a release removes all associated artifacts and metrics.

Uploading Source Maps & Artifacts

Why Upload Source Maps?

Minified JavaScript loses original variable names and line numbers, making stack traces unreadable. Source maps map the minified code back to the original source files, enabling Sentry to display the exact line and file that threw an error.

Upload Command

sentry-cli releases files 2024.09.15 upload-sourcemaps \
  ./dist \
  --url-prefix '~/static/js' \
  --validate
  • ./dist – Directory containing the minified files and their .map counterparts.
  • --url-prefix – The path that will be used in the filename field of the stack trace (~/static/js).
  • --validate – Checks that each source map correctly references an existing file.

Uploading Debug Symbols (Native)

For native platforms (iOS, Android, C/C++), you upload debug symbol files (.dSYM, .so, .pdb) so that native stack traces can be symbolicated.

sentry-cli upload-dif -p my-native-app ./build/Release-iphoneos/MyApp.app.dSYM
  • upload-dif stands for “Debug Information Files”.

Deployments & Environment Tracking

Sentry can track which environment (e.g., production, staging) a particular release was deployed to, and when. This is crucial for release health analysis.

sentry-cli releases deploys 2024.09.15 new \
  -e production \
  --name "Deploy #42"
  • new indicates a fresh deployment, as opposed to finished (for rollbacks).
  • -e sets the environment.
  • The --name flag is optional but useful for audit logs.

Marking a Deploy as Finished

If you use a “deployment start” / “deployment finish” model (common in blue‑green deployments), you can later mark the deploy as finished:

sentry-cli releases deploys 2024.09.15 finished \
  -e production

Issue Management from the CLI

You can also interact with Sentry issues directly:

  • List unresolved issues for a release:

    sentry-cli issues list --query 'release:"2024.09.15" is:unresolved'

  • Resolve an issue by ID:

    sentry-cli issues resolve 1234567890abcdef

  • Assign an issue to a team or user:

    sentry-cli issues assign 1234567890abcdef --team my-team

These commands are handy for automated triage scripts (e.g., auto‑resolve non‑critical errors after a successful deploy).

Integrating Sentry‑CLI into CI/CD Pipelines

Automation is where sentry‑cli shines. Below are concrete examples for the most popular CI providers.

GitHub Actions Example

Create a workflow file .github/workflows/release.yml:

name: Release

on:
  push:
    tags:
      - 'v*'   # Trigger on version tags like v1.2.3

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    env:
      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Node
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build assets
        run: npm run build

      - name: Install sentry-cli
        run: curl -sL https://sentry.io/get-cli/ | bash

      - name: Create Sentry release
        id: create_release
        run: |
          VERSION=${GITHUB_REF#refs/tags/}
          echo "VERSION=$VERSION" >> $GITHUB_ENV
          sentry-cli releases new -p my-webapp $VERSION
          sentry-cli releases set-commits --auto --repo my-org/my-webapp $VERSION

      - name: Upload source maps
        run: |
          sentry-cli releases files $VERSION upload-sourcemaps ./dist \
            --url-prefix '~/static/js' \
            --validate

      - name: Finalize Release
        run: sentry-cli releases finalize $VERSION

      - name: Deploy notification
        run: |
          sentry-cli releases deploys $VERSION new \
            -e production \
            --name "GitHub Actions Deploy $VERSION"

Key points:

  • The workflow triggers on Git tags (v*).
  • The release identifier is derived from the tag (VERSION).
  • All steps (create, upload, finalize, deploy) are executed sequentially, guaranteeing atomicity.

GitLab CI Example

.gitlab-ci.yml snippet for a Node.js project:

stages:
  - build
  - release

variables:
  SENTRY_ORG: my-org
  SENTRY_PROJECT: my-webapp
  SENTRY_AUTH_TOKEN: $SENTRY_AUTH_TOKEN   # Set in CI/CD Settings

build:
  stage: build
  image: node:20-alpine
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

release:
  stage: release
  image: alpine:latest
  dependencies:
    - build
  before_script:
    - apk add --no-cache curl bash
    - curl -sL https://sentry.io/get-cli/ | bash
  script:
    - export VERSION=$(git describe --tags --abbrev=0)
    - sentry-cli releases new -p $SENTRY_PROJECT $VERSION
    - sentry-cli releases set-commits --auto --repo $CI_PROJECT_PATH $VERSION
    - sentry-cli releases files $VERSION upload-sourcemaps dist/ --url-prefix '~/static/js' --validate
    - sentry-cli releases finalize $VERSION
    - sentry-cli releases deploys $VERSION new -e production --name "GitLab CI Deploy $VERSION"

Jenkins & CircleCI

Both platforms support shell steps, so the same series of commands can be placed in a sh block. For Jenkins declarative pipelines:

pipeline {
    agent any
    environment {
        SENTRY_AUTH_TOKEN = credentials('sentry-token')
        SENTRY_ORG = 'my-org'
        SENTRY_PROJECT = 'my-webapp'
    }
    stages {
        stage('Build') {
            steps {
                sh 'npm ci && npm run build'
                archiveArtifacts artifacts: 'dist/**', fingerprint: true
            }
        }
        stage('Release') {
            steps {
                sh '''
                VERSION=$(git describe --tags --abbrev=0)
                curl -sL https://sentry.io/get-cli/ | bash
                sentry-cli releases new -p $SENTRY_PROJECT $VERSION
                sentry-cli releases set-commits --auto --repo $GIT_URL $VERSION
                sentry-cli releases files $VERSION upload-sourcemaps dist/ --url-prefix '~/static/js' --validate
                sentry-cli releases finalize $VERSION
                sentry-cli releases deploys $VERSION new -e production --name "Jenkins Deploy $VERSION"
                '''
            }
        }
    }
}

Takeaway: The same core command set works across any CI engine; you only need to adapt environment variable handling and artifact persistence.

Advanced Features

Beyond the standard workflow, sentry‑cli offers advanced capabilities that can further improve observability.

Debug Symbols for Native Applications

For iOS/macOS, you typically generate a .dSYM bundle during the Xcode build. Upload it like this:

sentry-cli upload-dif -p my-ios-app ./build/Release-iphoneos/MyApp.app.dSYM

For Android, you can upload ProGuard mapping files:

sentry-cli upload-proguard --org my-org --project my-android-app ./app/build/outputs/mapping/release/mapping.txt

These uploads enable Sentry to de‑obfuscate native stack traces automatically.

Performance Monitoring & Transaction Uploads

Sentry’s performance monitoring captures transactions (e.g., HTTP requests, background jobs). While most SDKs handle this automatically, you can also manually upload transaction data for batch processing:

sentry-cli upload-transactions --org my-org --project my-webapp ./transactions.json

transactions.json must follow the Sentry Transaction API format. This is useful for offline processing of logs from edge devices.

Custom Scripts & Hooks

You can hook into Sentry’s release webhook system to trigger downstream actions (e.g., Slack notifications, feature flag toggles). While this is configured on the Sentry UI, you can also create a local script that runs after a release is finalized:

#!/usr/bin/env bash
set -euo pipefail

VERSION=$1
WEBHOOK_URL="https://hooks.slack.com/services/XXXXX/XXXXX/XXXXX"

payload=$(cat <<EOF
{
  "text": "🚀 New Sentry release *$VERSION* deployed to *production*",
  "attachments": [
    {
      "title": "View Release",
      "title_link": "https://sentry.io/organizations/$SENTRY_ORG/releases/$VERSION/",
      "color": "#36a64f"
    }
  ]
}
EOF
)

curl -X POST -H "Content-Type: application/json" -d "$payload" "$WEBHOOK_URL"

You could invoke it from CI:

sentry-cli releases finalize $VERSION && ./notify-slack.sh $VERSION

Common Pitfalls & Troubleshooting

Even seasoned engineers encounter hiccups. Below are frequent issues and their solutions.

1. “Invalid Auth Token” Errors

  • Cause: Token missing, expired, or not scoped correctly.
  • Fix: Verify SENTRY_AUTH_TOKEN is exported and matches the token created in Sentry. Ensure the token includes project:write and org:read scopes.

2. Source Maps Not Resolving

  • Symptoms: Errors in Sentry still show minified stack traces.
  • Checklist:
    1. Confirm the --url-prefix matches the script tag’s src attribute exactly (including leading ~/).
    2. Verify that source maps are included in the upload directory (*.map files alongside minified files).
    3. Ensure the release identifier used in the upload matches the one attached to the event (check the event’s “Release” field in Sentry UI).

3. “Release Not Found” After Deploy

  • Cause: Deploy command executed before the release was finalized.
  • Resolution: Always run sentry-cli releases finalize <release> before sentry-cli releases deploys. You can also use --wait flag on the finalize command to block until processing completes.

4. Large Artifact Uploads Fail

  • Symptoms: Timeout or “Request Entity Too Large”.
  • Solutions:
    • Use --chunk-size to split uploads (default 5 MB). Example: --chunk-size 10.
    • Enable HTTP keep‑alive: export SENTRY_HTTP_KEEP_ALIVE=1.
    • If using a corporate proxy, ensure HTTPS_PROXY is set correctly.

5. Missing Commits in Release Health

  • Reason: set-commits command not run, or repository not linked.

  • Fix: Add the repository in Sentry Settings → Source Maps & Repositories, then run:

    sentry-cli releases set-commits --auto --repo my-org/my-webapp <release>

6. Debug Symbols Not Symbolicating

  • Cause: Wrong debug-id or missing debug-id in the upload.
  • Fix: For iOS, use sentry-cli upload-dif which automatically extracts the debug ID. For Android, ensure ProGuard mapping files are uploaded (upload-proguard). Verify the debug-id matches the one reported in the crash event (found under “Debug Information”).

Diagnostic Commands

  • List all releases: sentry-cli releases list.
  • Show release details: sentry-cli releases info <release>.
  • Inspect upload status: sentry-cli releases files <release> list.

Use these to verify the state of your release pipeline.

Best Practices & Recommendations

  1. Versioning Discipline

    • Adopt a deterministic version scheme (e.g., YYYY.MM.DD or SemVer).
    • Store the version in a single source (e.g., package.json or a VERSION file) and reference it in CI scripts.

  2. Automate End‑to‑End

    • Keep the entire release flow in CI: create → set‑commits → upload artifacts → finalize → deploy.
    • This ensures that no manual step can be missed, reducing “human error” incidents.

  3. Separate Environments

    • Use distinct Sentry environments (production, staging, preview).
    • In CI, set SENTRY_ENVIRONMENT accordingly; you can also pass -e to the deploys command.

  4. Validate Source Maps Before Upload

    • Enable --validate flag to catch mismatched paths early.
    • Consider running a local verification script that checks for duplicate source map entries.

  5. Keep Release Artifacts Small

    • Exclude unnecessary files (e.g., vendor libraries already hosted on CDN).
    • Use .sentrycliignore similar to .gitignore to filter uploads.

  6. Leverage Release Health

    • Enable Release Health in Sentry to monitor crash‑free users, session counts, and performance metrics per release.
    • Combine with sentry-cli releases set-commits for accurate commit attribution.

  7. Secure Tokens

    • Rotate tokens regularly (e.g., every 90 days).
    • Use organization‑wide tokens only for administrative scripts; for per‑project pipelines, generate project‑scoped tokens.

  8. Monitor CLI Errors

    • Add a step in CI to capture sentry-cli exit codes and log output.
    • Fail the pipeline on non‑zero exit status to avoid silent failures.

  9. Document the Release Process

    • Keep a README.release.md in your repository that outlines the CLI flow, required environment variables, and troubleshooting tips.
    • This aids onboarding new team members and ensures consistency.

  10. Stay Updated

    • Sentry‑CLI receives frequent updates (performance improvements, new flags).
    • Pin the CLI version in your CI (e.g., curl -sL https://sentry.io/get-cli/ | bash -s -- -v 2.30.0) to avoid breaking changes, but schedule periodic upgrades.

By following these guidelines, you’ll not only reduce the operational overhead of error monitoring but also gain richer insights into the health of each release you ship.

Conclusion

Sentry‑CLI transforms Sentry from a passive observability dashboard into an integral part of your software delivery pipeline. By automating release creation, source‑map upload, deployment tracking, and even issue triage, you gain:

  • Faster feedback loops – errors surface with full context immediately after a deploy.
  • Higher reliability – rollbacks can be tied to Sentry’s release health, preventing faulty code from lingering.
  • Better developer experience – developers see meaningful stack traces in the UI, reducing time spent debugging minified or obfuscated code.

Implementing sentry‑cli may initially require a modest investment in CI configuration and token management, but the payoff—clearer insights, fewer manual steps, and more confidence in releases—pays dividends quickly. Whether you’re shipping a single‑page React app, a complex native mobile suite, or a micro‑service architecture, the CLI’s flexible command set scales to meet your needs.

Take the concepts and examples from this guide, adapt them to your stack, and let Sentry become a first‑class citizen in your deployment workflow. Happy monitoring!

Resources