sentry-cli

Sentry CLI is the official command-line interface for Sentry, the error-tracking and application-monitoring platform. Written in Rust, it’s distributed as @sentry/cli on npm — wrapping a set of precompiled per-platform binaries pulled in via optionalDependencies — as well as on PyPI, Homebrew, Docker, and direct binary downloads, so the actual work happens in a native binary rather than JavaScript. It focuses on the operational side of shipping an app: uploading source maps and debug symbols so Sentry can produce readable stack traces, creating and finalizing releases, associating commits and deploys, and sending custom events, logs, and metrics.

Most teams never invoke it directly by hand — build plugins for webpack, Vite, Next.js, and mobile toolchains (Xcode, Gradle) shell out to sentry-cli under the hood during CI to upload artifacts right after a build. Sentry licenses the CLI under FSL-1.1-MIT (a ‘fair source’ license, not OSI open source) and is actively steering users toward a newer Rust/AI-oriented CLI (cli.sentry.dev) as its eventual successor, though this project remains the actively supported tool for CI/CD pipelines today.

What You Get

• A single static binary (fetched via npm optionalDependencies per-platform, or via pip/Homebrew/Docker/direct download) with no runtime dependencies once installed.
• Subcommands for uploading source maps and debug symbols (sourcemaps, debug-files, upload-dif, upload-dsym, upload-proguard) so stack traces resolve to real source in Sentry.
• Release management commands (releases new/finalize/deploys/set-commits) that tie a Sentry release to the exact commit and deploy that shipped it.
• A thin JS wrapper (the SentryCli class in lib/index.ts) exposing releases and sourceMaps namespaces for scripting the CLI from Node instead of shelling out.
• Direct event/issue/log/metric ingestion commands (send-event, send-envelope, issues, logs, send-metric) for use outside a full SDK integration.

Common Use Cases

• Uploading JS/TS source maps during a webpack, Vite, or Next.js production build so minified stack traces map back to real source lines.
• Uploading dSYMs/Proguard mappings as a post-build step in iOS (Xcode) and Android (Gradle) CI pipelines.
• Creating a Sentry release and attaching the associated commits in a CI job, then marking it deployed once the rollout finishes.
• Sending a one-off event, log line, or custom metric to Sentry from a shell script without adding a full SDK.

Under The Hood

Architecture sentry-cli’s Rust core is organized as flat, purpose-built modules: a two-line main.rs delegates to commands::main(), which drives roughly thirty subcommand modules (releases, sourcemaps, debug_files, react_native, monitors, proguard, and more) registered through an each_subcommand! macro so the dispatcher, help text, and completion generation stay in sync without hand-written boilerplate. Cross-cutting concerns live in dedicated layers — api/ for HTTP calls to the Sentry backend, config.rs for resolving auth tokens and .sentryclirc properties, and utils/ for artifact-specific processing (chunked uploads, dif/dsym handling, sourcemap rewriting, snapshot testing helpers). The npm-facing half is a deliberately thin JS wrapper: bin/sentry-cli spawns the platform-appropriate compiled binary as a child process, while lib/index.ts’s SentryCli class offers releases/sourceMaps namespaces for callers who want to script the same binary from Node rather than shell out directly.

Tech Stack The core is Rust (edition 2021, pinned toolchain via rust-toolchain.toml), built on clap v4 (derive-based arg parsing with shell-completion generation), curl for HTTP, git2 for reading commit/repo metadata, and format-specific crates (plist, proguard, elementtree) for parsing Apple property lists, Android mapping files, and XML respectively; indicatif/console drive terminal progress bars and output. The npm package (@sentry/cli) doesn’t ship Rust source to consumers — it resolves one of eight platform-specific optionalDependencies packages (darwin, linux x64/arm/arm64/i686, win32 x64/i686/arm64) at install time via scripts/install.js, and TypeScript (tsc) compiles the thin JS wrapper. The project is also published to PyPI (setup.py/pyproject.toml) and as an Alpine-based Docker image, with Sentry’s own craft tool (.craft.yml) coordinating the multi-registry release process.

Code Quality Coverage is extensive on both sides: the Rust core has unit tests alongside source plus a large tests/integration/ suite built on the trycmd crate, which snapshot-tests full CLI invocations per subcommand (releases/, deploys/, sourcemaps/, debug_files/, react_native/, and more) against mocked HTTP responses and on-disk fixtures, with explicit #[cfg(windows)] variants where platform behavior diverges. The JS wrapper has its own Jest suite with mocks. CI (GitHub Actions) runs a version/platform matrix across ci.yml, test.yml, test_node.yml, and a dedicated Swift workflow for the Xcode-wrapping bits, plus clippy lint enforcement, ESLint/Prettier for JS, and CodeQL scanning. Errors are handled explicitly through anyhow::Result rather than panics in command paths, and AGENTS.md codifies a strict Conventional-Commits-style message format.

API Design Rather than one novel technique, sentry-cli’s value is unifying a fragmented set of platform-specific artifact formats — JS/TS source maps, Apple dSYMs, Android Proguard/R8 mappings, React Native bundles, Dart symbol maps — behind one command surface and one auth/config model (--auth-token, layered .sentryclirc/env vars). Ergonomics are mature rather than groundbreaking: consistent per-subcommand --help, shell-completion generation, an update nagger that warns when a newer CLI is available, and (per the README) an explicit compatibility table mapping CLI versions to supported self-hosted Sentry server versions so upgrades don’t silently break older on-prem installs.