Sentry CLI

Sentry CLI Usage Guide

Help users interact with Sentry from the command line using the sentry CLI.

Core rule for agents: just run the command. The sentry CLI auto-detects your org and project (from .sentryclirc, DSNs in .env/source, and the directory name), so do not list organizations and then list their projects to work out which one this checkout maps to — that manual discovery only duplicates work the CLI already does on every command. Pass an explicit <org>/<project> only when the CLI reports it can't detect the target or picks the wrong one.

Agent Guidance

Best practices and operational guidance for AI coding agents using the Sentry CLI.

Key Principles

• Just run the command — the CLI handles authentication and org/project detection automatically. Don't pre-authenticate or look up org/project before running commands. The CLI prompts for login if needed.
• Prefer CLI commands over raw API calls — the CLI has dedicated commands for most tasks. Reach for sentry issue view, sentry issue list, sentry trace view, etc. before constructing API calls manually or fetching external documentation.
• Use `sentry docs` for setup questions — if you need to know how to configure a Sentry SDK or feature, run sentry docs "your question" to query the documentation directly. This is faster and more accurate than fetching docs externally.
• Use `sentry schema` to explore the API — if you need to discover API endpoints, run sentry schema to browse interactively or sentry schema <resource> to search. This is faster than fetching OpenAPI specs externally.
• Use `sentry issue view <id>` to investigate issues — when asked about a specific issue (e.g., CLI-G5, PROJECT-123), use sentry issue view directly.
• Use `--json` for machine-readable output — pipe through jq for filtering. Human-readable output includes formatting that is hard to parse.
• The CLI auto-detects org/project — don't discover it yourself — most commands work without explicit targets by checking .sentryclirc config files, scanning for DSNs in .env files and source code, and matching directory names. Do not run sentry org list and then sentry project list to figure out which project this checkout belongs to — that manual fan-out just replicates the detection the CLI already runs on every command. Only specify <org>/<project> when the CLI reports it can't detect the target or detects the wrong one.

Design Principles

The sentry CLI follows conventions from well-known tools — if you're familiar with them, that knowledge transfers directly:

• `gh` (GitHub CLI) conventions: The sentry CLI uses the same <noun> <verb> command pattern (e.g., sentry issue list, sentry org view). Flags follow gh conventions: --json for machine-readable output, --fields to select specific fields, -w/--web to open in browser, -q/--query for filtering, -n/--limit for result count.
• `sentry api` mimics `curl`: The sentry api command provides direct API access with a curl-like interface — --method for HTTP method, --data for request body, --header for custom headers. It handles authentication automatically. If you know how to call a REST API with curl, the same patterns apply.

Context Window Tips

• Use --json --fields to select specific fields and reduce output size. Run <command> --help to see available fields. Example: sentry issue list --json --fields shortId,title,priority,level,status
• Use --json when piping output between commands or processing programmatically
• Use --limit to cap the number of results (default is usually 10–100)
• Prefer sentry issue view PROJECT-123 over listing and filtering manually
• Use sentry api for endpoints not covered by dedicated commands

Safety Rules

• Always confirm with the user before running destructive commands: project delete, trial start
• For mutations, verify the org/project context looks correct in the command output before proceeding with further changes
• Never store or log authentication tokens — the CLI manages credentials automatically
• If the CLI reports the wrong org/project, override with explicit <org>/<project> arguments

Exit Codes

The CLI uses semantic exit codes. Key ranges for agents:

See Exit Codes for the complete reference.

Workflow Patterns

Investigate an Issue

# 1. Find the issue (auto-detects org/project from DSN or config)
sentry issue list --query "is:unresolved" --limit 5

# 2. Get details. For agents, prefer --json — it includes the full issue plus
# the latest event under `event`, so you get everything in one call.
sentry issue view PROJECT-123 --json

# 3. Get AI root cause analysis
sentry issue explain PROJECT-123

# 4. Get a fix plan
sentry issue plan PROJECT-123

sentry issue view <SHORT-ID> --json is the fastest way to get an agent up to speed on an issue. Select just the fields you need with --fields instead of consuming the whole payload — the latest event's request entry can carry live session data (cookies, headers, body), so extract named fields rather than dumping the entire object:

# Top-level issue fields
sentry issue view PROJECT-123 --json --fields shortId,title,culprit,count,userCount,permalink

# Named fields from the latest event — avoids pulling the full request/session blob
sentry issue view PROJECT-123 --json --fields event.id,event.title,event.dateCreated

# Just the request URL and method (not the whole request entry). Event data
# lives under event.entries[], each tagged with a `type` and `data` payload.
sentry issue view PROJECT-123 --json | jq '.event.entries[] | select(.type == "request") | .data | {url, method}'

Explore Traces and Performance

# 1. List recent traces (auto-detects org/project)
sentry trace list --limit 5

# 2. View a specific trace with span tree
sentry trace view abc123def456...

# 3. View spans for a trace
sentry span list abc123def456...

# 4. View logs associated with a trace
sentry trace logs abc123def456...

Stream Logs

# Stream logs in real-time (auto-detects org/project)
sentry log list --follow

# Filter logs by severity
sentry log list --query "severity:error"

Capture Events Locally (Spotlight)

# Run the app with the local server auto-enabled; tail errors/traces/logs.
# No DSN needed — with no DSN, events go ONLY to the local server (nothing
# reaches the user's Sentry org, no production quota). With a DSN set, the
# SDK sends to both.
sentry local run -- npm run dev          # or: python manage.py runserver, etc.

# From a CLI source checkout, run the Local UI in a second terminal, then open it.
pnpm --filter local dev
sentry local run --open -- npm run dev

# Watch only AI/agent (gen_ai, mcp) spans while iterating on an agent.
sentry local -f ai

# Server-side SDKs read SENTRY_SPOTLIGHT automatically. The CLI also injects
# the URL under every framework client prefix (NEXT_PUBLIC_, VITE_, PUBLIC_,
# NUXT_PUBLIC_, REACT_APP_, VUE_APP_, GATSBY_). Until the browser SDK reads
# these automatically (getsentry/sentry-javascript#18198), reference the var
# matching your framework in the client config:
# Sentry.init({ spotlight: process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT ?? false })

Query Sentry Documentation

# Ask a documentation question
sentry docs "How do I configure tracing in Next.js?"

# Search the documentation index
sentry docs list "source maps"