sentry-cli

A command-line tool to fetch Sentry error data and provide context to Claude Code for reviewing and fixing errors.

Overview

This CLI connects to Sentry's REST API to retrieve issues, events, and stacktraces in a format optimized for AI-assisted debugging. It's designed to give Claude Code the context it needs to understand and help fix production errors.

Installation

From Source (Development)

# Clone the repository
git clone <repo-url>
cd sentry-cli

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies and the package in development mode
uv sync

# Verify installation
uv run sentry-cli --help

From PyPI (Coming Soon)

uv add sentry-cli
# or
pip install sentry-cli

Configuration

Environment Variables

Variable	Required	Description
SENTRY_AUTH_TOKEN	Yes	Sentry API authentication token
SENTRY_ORG	Yes	Sentry organization slug
SENTRY_PROJECT	No	Default project slug (can be overridden per command)
SENTRY_URL	No	Sentry base URL (defaults to https://sentry.io)

Getting a Sentry Auth Token

1. Go to Sentry.io (or your self-hosted instance)
2. Navigate to Settings → Auth Tokens
3. Click Create New Token
4. Select the following scopes:
   • project:read
   • org:read
   • event:read
   • issue:read
5. Copy the token and set it as SENTRY_AUTH_TOKEN

Example Setup

export SENTRY_AUTH_TOKEN="sntrys_your_token_here"
export SENTRY_ORG="your-organization"
export SENTRY_PROJECT="your-project"  # optional default

Or create a .env file in your project root:

SENTRY_AUTH_TOKEN=sntrys_your_token_here
SENTRY_ORG=your-organization
SENTRY_PROJECT=your-project

Commands

sentry-cli issues list

List recent issues from a Sentry project.

# List issues from default project
sentry-cli issues list

# List issues from a specific project
sentry-cli issues list --project my-project

# Filter by status
sentry-cli issues list --status unresolved
sentry-cli issues list --status resolved
sentry-cli issues list --status ignored

# Limit results
sentry-cli issues list --limit 10

# Output as JSON (for piping to other tools)
sentry-cli issues list --json

Options:

• --project, -p - Project slug (overrides SENTRY_PROJECT)
• --status, -s - Filter by status: unresolved, resolved, ignored (default: unresolved)
• --limit, -l - Number of issues to fetch (default: 25, max: 100)
• --query, -q - Search query (Sentry search syntax)
• --json - Output raw JSON

sentry-cli issues get <ISSUE_ID>

Get detailed information about a specific issue, including recent events and stacktraces.

# Get issue details
sentry-cli issues get 12345

# Include more events
sentry-cli issues get 12345 --events 5

# Output as JSON
sentry-cli issues get 12345 --json

Options:

• --events, -e - Number of recent events to include (default: 1)
• --json - Output raw JSON

Output includes:

• Issue title and metadata
• First seen / last seen timestamps
• Error count and affected users
• Tags and environment info
• Stacktrace from the most recent event(s)
• Breadcrumbs (recent actions before the error)
• Request data (if applicable)

sentry-cli events list <ISSUE_ID>

List events (occurrences) for a specific issue.

# List events for an issue
sentry-cli events list 12345

# Limit results
sentry-cli events list 12345 --limit 10

# Output as JSON
sentry-cli events list 12345 --json

Options:

• --limit, -l - Number of events to fetch (default: 25)
• --json - Output raw JSON

sentry-cli events get <EVENT_ID>

Get detailed information about a specific event.

# Get event details (requires project)
sentry-cli events get abc123def456 --project my-project

# Output as JSON
sentry-cli events get abc123def456 --project my-project --json

Options:

• --project, -p - Project slug (required)
• --json - Output raw JSON

Output includes:

• Full stacktrace with source context
• Exception details
• Breadcrumbs
• Request/response data
• User context
• Tags and extra data

sentry-cli projects list

List available projects in your organization.

sentry-cli projects list

# Output as JSON
sentry-cli projects list --json

sentry-cli context <ISSUE_ID>

Generate a comprehensive context document optimized for Claude Code. This is the primary command for AI-assisted debugging.

# Generate context for an issue
sentry-cli context 12345

# Include source code snippets (if available via source maps)
sentry-cli context 12345 --with-source

# Copy to clipboard
sentry-cli context 12345 | pbcopy

Options:

• --with-source - Include source code snippets if available
• --events, -e - Number of events to analyze (default: 3)

Output format:

## Sentry Issue: <title>

### Summary
- **Issue ID**: 12345
- **First Seen**: 2024-01-15 10:30:00 UTC
- **Last Seen**: 2024-01-15 14:22:00 UTC
- **Events**: 47
- **Users Affected**: 12

### Environment
- **Environment**: production
- **Release**: v1.2.3
- **Platform**: python

### Exception
<exception type and message>

### Stacktrace
<formatted stacktrace with file paths and line numbers>

### Breadcrumbs
<recent actions/events leading up to the error>

### Request Context
<HTTP request details if applicable>

### Tags
<relevant tags>

Development

Setup

# Clone and install
git clone <repo-url>
cd sentry-cli
uv sync

# Install pre-commit hooks
uv run pre-commit install

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=sentry_cli --cov-report=term-missing

# Run specific test file
uv run pytest tests/test_issues.py

Linting and Formatting

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Fix auto-fixable issues
uv run ruff check --fix .

# Type checking
uv run mypy src/sentry_cli

Building

# Build the package
uv build

# This creates:
# - dist/sentry_cli-<version>.tar.gz
# - dist/sentry_cli-<version>-py3-none-any.whl

Project Structure

sentry-cli/
├── src/
│   └── sentry_cli/
│       ├── __init__.py
│       ├── cli.py           # Main CLI entry point
│       ├── client.py        # Sentry API client
│       ├── commands/
│       │   ├── __init__.py
│       │   ├── issues.py    # Issues commands
│       │   ├── events.py    # Events commands
│       │   ├── projects.py  # Projects commands
│       │   └── context.py   # Context generation
│       ├── formatters/
│       │   ├── __init__.py
│       │   ├── text.py      # Human-readable output
│       │   └── markdown.py  # Markdown output for AI
│       └── models.py        # Data models
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_client.py
│   ├── test_issues.py
│   ├── test_events.py
│   └── test_formatters.py
├── pyproject.toml
├── README.md
└── .env.example

Usage with Claude Code

Workflow

1. Identify an issue in Sentry you want to fix
2. Generate context using the CLI:

   sentry-cli context 12345 > /tmp/sentry-issue.md

3. Share with Claude Code:

   I need help fixing this Sentry error. Here's the context:
   
   <paste context or reference file>
   

4. Claude Code analyzes the stacktrace, breadcrumbs, and context
5. Implement the fix with Claude Code's guidance

Tips

• Use sentry-cli context for the most AI-friendly output
• Include multiple events (--events 3) to see if there are patterns
• The breadcrumbs often reveal what the user was doing before the error
• Tags can help identify specific environments or user segments affected

API Reference

This CLI uses the Sentry Web API. Key endpoints used:

• GET /api/0/organizations/{org}/issues/ - List issues
• GET /api/0/organizations/{org}/issues/{issue_id}/ - Get issue details
• GET /api/0/organizations/{org}/issues/{issue_id}/events/ - List issue events
• GET /api/0/projects/{org}/{project}/events/{event_id}/ - Get event details
• GET /api/0/organizations/{org}/projects/ - List projects

License

MIT