sentry-cli

name

sentry-cli

description

Read Sentry issues and events from the terminal via the Sentry HTTP API, so an alert (Slack/Grafana/Vercel/etc.) can be investigated straight to its root-cause issue without the web UI. Use when the user references a Sentry issue, a production 5xx/error spike, or asks to check what an error is. Commands: `issues "<query>"` (search by tag), `issue <id>`, `latest <id>` (latest event's tags + exception text), `projects`, `whoami`.

Sentry CLI

Terminal reader for Sentry, at ~/.claude/skills/sentry-cli/sentry_cli.py. Mirrors what the web issue stream shows, but pipeable (--json) so only the projection you need enters context.

Running

uv run ~/.claude/skills/sentry-cli/sentry_cli.py <command> [options]

Authentication

Needs a Sentry auth token with scopes event:read, project:read, org:read. Create one at https://<your-org>.sentry.io/settings/account/api/auth-tokens/.

Token is read from, in order:

1. SENTRY_AUTH_TOKEN env var
2. ~/.config/sentry-cli/config.json — {"token","org","project","base_url"}

The token is never printed and never passed on argv.

Org and project have no built-in defaults — supply them via the config file, the SENTRY_ORG / SENTRY_PROJECT env vars, or the --org / --project flags.

Example ~/.config/sentry-cli/config.json (chmod 600):

{ "token": "sntryu_...", "org": "your-org-slug", "project": "your-project-slug" }

Sentry SaaS is region-pinned. If commands 404 or redirect, set the region host in the config base_url (e.g. https://us.sentry.io/api/0 or https://de.sentry.io/api/0) or via the SENTRY_URL env var.

Verify setup with:

uv run ~/.claude/skills/sentry-cli/sentry_cli.py whoami

Commands

Command	What it does
issues "<query>" [--period 24h] [--sort freq] [--json]	List issues matching a Sentry search query. Tag search works (any setTag key), e.g. route:api, level:error, environment:production. Combine freely; add is:unresolved/is:resolved or drop it to see all.
issue <issue_id> [--json]	One issue's detail: counts, first/last seen, permalink.
latest <issue_id> [--json]	The issue's most recent event — tags + exception type/message (the root-cause view).
projects [--json]	List projects in the org (discover exact slugs/ids).
whoami	Verify the token; print the authenticated identity.

Global: --org <slug> / --project <slug> override the config/env values.

Typical alert → root-cause flow

# 1. Widen search around the alert window, by whatever tags the app sets in code.
uv run ~/.claude/skills/sentry-cli/sentry_cli.py issues "level:error" --period 24h --json

# 2. Read the top issue's latest event to see the actual exception + tags.
uv run ~/.claude/skills/sentry-cli/sentry_cli.py latest <issue_id>

Search by any custom tag your app attaches via Sentry.setTag(...) (e.g. a route, reason, status, or request-scoped identifier). The latest command surfaces the full tag set plus the exception text for that event.