sentry-tool 0.3.0

CLI tool for querying and managing Sentry issues

Sentry Tool

CLI tool for querying and managing Sentry issues.

Overview

Sentry Tool provides a command-line interface for interacting with Sentry's API to query issues, view events, and analyze error patterns. It's designed for DevOps engineers, developers, and SREs who need quick CLI access to Sentry data.

Features

• List issues: View recent issues in a project or across all projects
• Show issue details: Get comprehensive information about specific issues
• View events: Examine event details and stacktraces
• List events: See recent events for an issue
• Tag analysis: Analyze tag distributions across issues
• List projects: View all projects in an organization
• Open in browser: Quick-launch Sentry web UI
• Multi-instance support: TOML-based profiles for multiple Sentry instances
• Configuration management: Validate connectivity, list projects across profiles

Installation

Requirements

• Python >= 3.13
• uv package manager

Setup

# Clone or navigate to the sentry-tool directory
cd sentry-tool

# Install dependencies
uv sync

# Install dev dependencies (optional)
uv sync --group dev

Configuration

Sentry Tool supports a TOML-based profile system for managing multiple Sentry instances, with environment variable overrides for flexibility.

Profile Configuration (Recommended)

Create a TOML configuration file at ~/.config/sentry-tool/config.toml:

default_profile = "my-sentry"

[profiles.my-sentry]
url = "https://sentry.example.com"
org = "my-org"
project = "my-project"
auth_token = "sntrys_..."

[profiles.cloud]
url = "https://sentry.io"
org = "my-cloud-org"
project = "web-app"
auth_token = "sntrys_..."

Each profile defines:

Field	Description	Default
url	Sentry instance URL	https://sentry.io
org	Organization slug	sentry
project	Default project slug	(none)
auth_token	API authentication token	(required)

Environment Variable Overrides

Environment variables override profile values. This is useful for CI/CD or temporary overrides.

Variable	Overrides	Description
SENTRY_AUTH_TOKEN	auth_token	API authentication token
SENTRY_URL	url	Sentry instance URL
SENTRY_ORG	org	Organization slug
SENTRY_PROJECT	project	Default project slug
SENTRY_PROFILE	(profile selection)	Use this profile instead of default

Getting a Sentry Auth Token

1. Log into your Sentry instance
2. Navigate to Settings > Account > API > Auth Tokens
3. Create a new token with appropriate scopes (at minimum: project:read, event:read)
4. Add the token to your profile configuration or set SENTRY_AUTH_TOKEN

Verifying Configuration

# Show current configuration and all profiles
sentry-tool config show

# Verify connectivity to all profiles
sentry-tool config validate

Global Flags

These flags are available on the root command and apply to all subcommands.

Flag	Short	Description
--profile	-P	Use a named profile from config
--project	-p	Override the project slug from the active profile

Most commands also accept:

Flag	Short	Values	Description
--format	-f	table, json	Output format (default: table)

Usage

list - List Recent Issues

List recent issues in a project. Use --all-projects/-A to list across all projects.

sentry-tool list
sentry-tool list -p my-project -n 5
sentry-tool list -s unresolved
sentry-tool list -A
sentry-tool list --format json

Flag	Short	Description	Default
--project	-p	Project slug	profile default
--all-projects	-A	List issues across all projects (mutually exclusive with -p)
--max	-n	Maximum issues to show	10
--status	-s	Filter by status: resolved, unresolved, muted
--format	-f	Output format: table, json	table

---

show - Show Issue Details

Show comprehensive details for a specific issue.

sentry-tool show 24
sentry-tool show OTEL-COLLECTOR-Q
sentry-tool show 24 --format json

Argument	Description
ISSUE_ID	Issue ID (numeric like 24 or short ID like OTEL-COLLECTOR-Q)

Flag	Short	Description	Default
--format	-f	Output format: table, json	table

Output includes: Title, Status, Level, Priority, Event count, First/Last seen, Tags, Release info, Permalink

---

event - Show Event Details

Show event details for an issue. By default shows the latest event.

sentry-tool event 24
sentry-tool event OTEL-COLLECTOR-Q
sentry-tool event 24 -e abc123...
sentry-tool event 24 -c
sentry-tool event 24 --format json

Argument	Description
ISSUE_ID	Issue ID (numeric or short ID)

Flag	Short	Description	Default
--event	-e	Specific event ID	latest
--context	-c	Show only context/stacktrace
--format	-f	Output format: table, json	table

Output includes: Event ID, Title, Message, Date, Server, SDK info, Release, Context, Exception with stacktrace

---

events - List Recent Events

List recent events for an issue.

sentry-tool events 24
sentry-tool events OTEL-COLLECTOR-Q -n 5
sentry-tool events 24 --format json

Argument	Description
ISSUE_ID	Issue ID (numeric or short ID)

Flag	Short	Description	Default
--max	-n	Maximum events to show	10
--format	-f	Output format: table, json	table

Output: Table with Event ID, Date, Server

---

tags - Show Tag Values

Show tag values for an issue. Lists available tags when no tag key is provided.

sentry-tool tags OTEL-COLLECTOR-14
sentry-tool tags OTEL-COLLECTOR-14 server_name
sentry-tool tags OTEL-COLLECTOR-14 release
sentry-tool tags 14 server_name --format json

Argument	Description
ISSUE_ID	Issue ID (numeric or short ID)
TAG_KEY	(optional) Tag key to show values for (e.g., server_name, release)

Flag	Short	Description	Default
--format	-f	Output format: table, json	table

Output:

• Without TAG_KEY: Table of available tags with unique value counts
• With TAG_KEY: Table showing tag values with count and percentage distribution

---

list-projects - List Projects

List all projects in the configured organization.

sentry-tool list-projects
sentry-tool list-projects --format json

Flag	Short	Description	Default
--format	-f	Output format: table, json	table

---

open - Open in Browser

Open Sentry web UI in the default browser. Without arguments, opens the organization dashboard. With an issue ID, opens that issue directly.

sentry-tool open
sentry-tool open 24

Argument	Description
ISSUE_ID	(optional) Issue ID to open directly

---

config - Configuration Management

Subcommands for managing and verifying configuration.

config show

Display current configuration including active profile and all configured profiles.

sentry-tool config show
sentry-tool config show --format json

config profiles

List configured profile names with default marked.

sentry-tool config profiles
sentry-tool config profiles --format json

config list-projects

Enumerate Sentry projects for each configured profile. Profiles with missing auth tokens are skipped.

sentry-tool config list-projects
sentry-tool config list-projects --format json

config validate

Verify connectivity to all configured profiles by querying projects. Useful after initial setup.

sentry-tool config validate
sentry-tool config validate --format json

All config subcommands accept --format/-f (table or json, default: table).

---

Common Workflows

Investigate a New Issue:

# 1. List recent unresolved issues
sentry-tool list -s unresolved

# 2. Show details for an issue
sentry-tool show OTEL-COLLECTOR-14

# 3. See the latest event with stack trace
sentry-tool event OTEL-COLLECTOR-14

# 4. Check which servers are affected
sentry-tool tags OTEL-COLLECTOR-14 server_name

Cross-Instance Investigation:

# List issues across all projects on a specific instance
sentry-tool -P production list -A

# Compare the same project on different instances
sentry-tool -P staging -p web-app list
sentry-tool -P production -p web-app list

Export Data for Analysis:

# Get issue details as JSON
sentry-tool show OTEL-COLLECTOR-14 --format json > issue.json

# Get event details as JSON
sentry-tool event OTEL-COLLECTOR-14 --format json > event.json

Development

See CONTRIBUTING.md for development workflow, testing, and contribution guidelines.

Quick Start

# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest

# Type checking
uv run mypy src

# Linting
uv run ruff check src tests

# Format code
uv run ruff format src tests

License

MIT License - see LICENSE file for details.