Sentry CLI

3.3.5 · active · verified Thu Apr 16

sentry-cli is a powerful command-line utility for interacting with Sentry, enabling tasks like creating releases, uploading source maps, managing projects, and configuring your Sentry instance. The Python package primarily serves as a convenient wrapper to install and execute the Rust-based binary. It is actively maintained with frequent snapshot builds and regular stable releases.

Common errors

```
sentry-cli: command not found
```
cause The `sentry-cli` executable is not in your system's PATH, or the installation failed.

fix Ensure `sentry-cli` is installed (`pip install sentry-cli` or `curl -sL https://sentry.io/get-cli/ | bash`) and that your shell's PATH includes the directory where the executable resides (e.g., `~/.local/bin` for pip installs).
```
error: You need to login first. (sentry-cli.login.not-logged-in)
```
cause sentry-cli cannot authenticate with Sentry. This usually means no Auth Token is set, or it's invalid/expired.

fix Run `sentry-cli login` interactively and follow the prompts, or set a valid Sentry Auth Token in the `SENTRY_AUTH_TOKEN` environment variable for non-interactive environments (e.g., CI/CD).
```
error: Missing required argument `--org`
```
cause The command requires a Sentry organization slug, but it was not provided.

fix Add `--org <YOUR_ORG_SLUG>` to your command, or set the `SENTRY_ORG` environment variable, or configure it in a `.sentryclirc` file in your project or home directory.
```
error: Missing required argument `--project`
```
cause The command requires a Sentry project slug, but it was not provided.

fix Add `--project <YOUR_PROJECT_SLUG>` to your command, or set the `SENTRY_PROJECT` environment variable, or configure it in a `.sentryclirc` file in your project or home directory.

Warnings

gotcha sentry-cli is not a Python library meant for direct `import` statements. The Python `sentry-cli` package is a wrapper to install the `sentry-cli` binary. Attempting to `import sentry_cli` will likely fail or lead to confusion.
Fix: Use `sentry-cli` directly from your shell or invoke it via Python's `subprocess` module for programmatic control. For Python application integration, use `sentry-sdk`.
breaking Sentry CLI versions 2.x and earlier relied on an older authentication method (API keys). Versions 3.x strongly recommend using Auth Tokens for better security and granular permissions.
Fix: Upgrade to `sentry-cli` version 3.x and ensure you are using a Sentry Auth Token. Set it as `SENTRY_AUTH_TOKEN` environment variable or use `sentry-cli login`.
gotcha Sourcemap uploading can be tricky if paths or release names don't match exactly between your build process and Sentry. Incorrect configurations lead to un-minified stack traces.
Fix: Ensure `sentry-cli upload-sourcemaps` commands correctly specify the `--url-prefix` to match how your assets are served, and that the `--release` parameter matches the release ID associated with your reported events. Validate sourcemaps in Sentry's developer tools after uploading.
gotcha Many `sentry-cli` commands require specifying the Sentry organization and project. Forgetting these, or providing incorrect values, often leads to authentication or permissions errors.
Fix: Always include `--org <ORG_SLUG>` and `--project <PROJECT_SLUG>` arguments, or configure them globally via environment variables (`SENTRY_ORG`, `SENTRY_PROJECT`) or a `.sentryclirc` file.

Install

pip install sentry-cli Install via pip (installs binary)
curl -sL https://sentry.io/get-cli/ | bash Install standalone binary (recommended)

Imports

sentry_cli
wrong:
```
import sentry_cli
```
correct:
```
This package is not intended for direct Python import as a library with an API.
```
sentry-cli is a command-line tool (a binary), not a Python library with an importable API. Its Python package primarily manages the binary installation. For Python application error reporting, use the `sentry-sdk` library. To run `sentry-cli` from Python, use `subprocess`.

Quickstart

This quickstart demonstrates how to programmatically interact with `sentry-cli` from Python using the `subprocess` module. It includes examples for checking the version, creating, and finalizing a Sentry release. Ensure you have `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` environment variables configured or set `sentry-cli login` interactively. Replace placeholder slugs with your actual Sentry organization and project details.

import os
import subprocess

# Ensure SENTRY_AUTH_TOKEN is set for non-interactive use (e.g., CI/CD)
# It can be obtained from your Sentry 'API Keys' settings.
# For interactive use, run 'sentry-cli login' once in your terminal.
os.environ['SENTRY_AUTH_TOKEN'] = os.environ.get('SENTRY_AUTH_TOKEN', '')
os.environ['SENTRY_ORG'] = os.environ.get('SENTRY_ORG', 'your-org-slug') # Replace with your Sentry organization slug
os.environ['SENTRY_PROJECT'] = os.environ.get('SENTRY_PROJECT', 'your-project-slug') # Replace with your Sentry project slug

def run_sentry_cli_command(command_args):
    full_command = ['sentry-cli'] + command_args
    print(f"\nRunning: {' '.join(full_command)}")
    try:
        result = subprocess.run(
            full_command,
            capture_output=True,
            text=True,
            check=True, # Raises CalledProcessError for non-zero exit codes
            env=os.environ # Pass current environment including SENTRY_AUTH_TOKEN
        )
        print("STDOUT:\n" + result.stdout)
        if result.stderr:
            print("STDERR:\n" + result.stderr)
        return result.stdout
    except subprocess.CalledProcessError as e:
        print(f"Error executing command: {e.cmd}")
        print(f"Return Code: {e.returncode}")
        print(f"STDOUT:\n{e.stdout}")
        print(f"STDERR:\n{e.stderr}")
        raise # Re-raise the error to stop execution
    except FileNotFoundError:
        print("Error: 'sentry-cli' command not found. Please ensure it's installed and in your system PATH.")
        print("You can install it via 'pip install sentry-cli' or by following instructions at https://docs.sentry.io/product/cli/installation/")
        raise

if __name__ == "__main__":
    try:
        # 1. Check the Sentry CLI version
        run_sentry_cli_command(['--version'])

        # 2. Get the current organization's status
        run_sentry_cli_command(['info'])

        # 3. Create a Sentry release (replace with your actual release name)
        release_name = f"my-app@{os.getenv('BUILD_VERSION', '1.0.0-test')}"
        run_sentry_cli_command(['releases', 'new', release_name])

        # 4. Set the release to committed (optional, for connecting to SCM)
        # run_sentry_cli_command(['releases', 'set-commits', release_name, '--auto'])

        # 5. Finalize the release
        run_sentry_cli_command(['releases', 'finalize', release_name])

        print("\nSentry CLI commands executed successfully!")

    except Exception as e:
        print(f"\nAn error occurred during quickstart execution: {e}")

view raw JSON →