Agent Guidance

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

Key Principles

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 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 — most commands work without explicit targets by scanning for DSNs in .env files and source code.

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 --fields id,title,status on list commands to reduce output size
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
Verify the org/project context is correct before mutations — use sentry auth status to check defaults
Never store or log authentication tokens — use sentry auth login and let the CLI manage credentials
When in doubt about the target org/project, use explicit <org>/<project> arguments instead of auto-detection

Workflow Patterns

Investigate an Issue

# 1. Find the issue
sentry issue list my-org/my-project --query "is:unresolved" --limit 5

# 2. Get details
sentry issue view PROJECT-123

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

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

Explore Traces and Performance

# 1. List recent traces
sentry trace list my-org/my-project --limit 5

# 2. View a specific trace with span tree
sentry trace view my-org/my-project/abc123def456...

# 3. View spans for a trace
sentry span list my-org/my-project/abc123def456...

# 4. View logs associated with a trace
sentry trace logs my-org/abc123def456...

Stream Logs

# Stream logs in real-time
sentry log list my-org/my-project --follow

# Filter logs by severity
sentry log list my-org/my-project --query "severity:error"

Explore the API Schema

# Browse all API resource categories
sentry schema

# Search for endpoints related to a resource
sentry schema issues

# Get details about a specific endpoint
sentry schema "GET /api/0/organizations/{organization_id_or_slug}/issues/"

Arbitrary API Access

# GET request (default)
sentry api /api/0/organizations/my-org/

# POST request with data
sentry api /api/0/organizations/my-org/projects/ --method POST --data '{"name":"new-project","platform":"python"}'

Dashboard Layout

Sentry dashboards use a 6-column grid. When adding widgets, aim to fill complete rows (widths should sum to 6).

Display types with default sizes:

Display Type	Width	Height	Category	Notes
`big_number`	2	1	common	Compact KPI — place 3 per row (2+2+2=6)
`line`	3	2	common	Half-width chart — place 2 per row (3+3=6)
`area`	3	2	common	Half-width chart — place 2 per row
`bar`	3	2	common	Half-width chart — place 2 per row
`table`	6	2	common	Full-width — always takes its own row
`stacked_area`	3	2	specialized	Stacked area chart
`top_n`	3	2	specialized	Top N ranked list
`categorical_bar`	3	2	specialized	Categorical bar chart
`text`	3	2	specialized	Static text/markdown widget
`details`	3	2	internal	Detail view
`wheel`	3	2	internal	Pie/wheel chart
`rage_and_dead_clicks`	3	2	internal	Rage/dead click visualization
`server_tree`	3	2	internal	Hierarchical tree display
`agents_traces_table`	3	2	internal	Agents traces table

Use common types for general dashboards. Use specialized only when specifically requested. Avoid internal types unless the user explicitly asks.

Available datasets: spans (default, covers most use cases), discover, issue, error-events, transaction-like, metrics, logs, tracemetrics, preprod-app-size.

Run sentry dashboard widget --help for the full list including aggregate functions.

Row-filling examples:

# 3 KPIs filling one row (2+2+2 = 6)
sentry dashboard widget add <dashboard> "Error Count" --display big_number --query count
sentry dashboard widget add <dashboard> "P95 Duration" --display big_number --query p95:span.duration
sentry dashboard widget add <dashboard> "Throughput" --display big_number --query epm

# 2 charts filling one row (3+3 = 6)
sentry dashboard widget add <dashboard> "Errors Over Time" --display line --query count
sentry dashboard widget add <dashboard> "Latency Over Time" --display line --query p95:span.duration

# Full-width table (6 = 6)
sentry dashboard widget add <dashboard> "Top Endpoints" --display table \
  --query count --query p95:span.duration \
  --group-by transaction --sort -count --limit 10

Common Mistakes

Wrong issue ID format: Use PROJECT-123 (short ID), not the numeric ID 123456789. The short ID includes the project prefix.
Forgetting authentication: Run sentry auth login before any other command. Check with sentry auth status.
Missing --json for piping: Human-readable output includes formatting. Use --json when parsing output programmatically.
Org/project ambiguity: Auto-detection scans for DSNs in .env files and source code. If the project is ambiguous, specify explicitly: sentry issue list my-org/my-project.
Confusing --query syntax: The --query flag uses Sentry search syntax (e.g., is:unresolved, assigned:me), not free text search.
Not using --web: View commands support -w/--web to open the resource in the browser — useful for sharing links.
Fetching API schemas instead of using the CLI: Prefer sentry schema to browse the API and sentry api to make requests — the CLI handles authentication and endpoint resolution, so there's rarely a need to download OpenAPI specs separately.