Sentry CLI Usage Guide
Help users interact with Sentry from the command line using the sentry CLI.
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. If auth is needed, the CLI prompts interactively.
- 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, source code, config defaults, and directory names. 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
Workflow Patterns
Investigate an Issue
sentry issue list --query "is:unresolved" --limit 5
sentry issue view PROJECT-123
sentry issue explain PROJECT-123
sentry issue plan PROJECT-123
Explore Traces and Performance
sentry trace list --limit 5
sentry trace view abc123def456...
sentry span list abc123def456...
sentry trace logs abc123def456...
Stream Logs
sentry log list --follow
sentry log list --query "severity:error"
Explore the API Schema
sentry schema
sentry schema issues
sentry schema "GET /api/0/organizations/{organization_id_or_slug}/issues/"
Arbitrary API Access
sentry api /api/0/organizations/my-org/
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), tracemetrics, discover, issue, error-events, logs. Run sentry dashboard widget --help for dataset descriptions, query formats, and examples.
Row-filling examples:
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
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
sentry dashboard widget add <dashboard> "Top Endpoints" --display table \
--query count --query p95:span.duration \
--group-by transaction --sort -count --limit 10
Quick Reference
Time filtering
Use --period (alias: -t) to filter by time window:
sentry trace list --period 1h
sentry span list --period 24h
sentry span list -t 7d
Scoping to an org or project
Org and project are positional arguments following gh CLI conventions:
sentry trace list my-org/my-project
sentry issue list my-org/my-project
sentry span list my-org/my-project/abc123def456...
Listing spans in a trace
Pass the trace ID as a positional argument to span list:
sentry span list abc123def456...
sentry span list my-org/my-project/abc123def456...
Dataset names for the Events API
When querying the Events API (directly or via sentry api), valid dataset values are: spans, transactions, logs, errors, discover.
Release Workflow
The sentry release command group manages Sentry releases for tracking deploys and associating commits with errors. A typical CI workflow:
sentry release create my-org/1.0.0 --project my-project
sentry release set-commits my-org/1.0.0 --auto
sentry release finalize my-org/1.0.0
sentry release deploy my-org/1.0.0 production
Key details:
- The
org/version positional is <org-slug>/<version>, NOT a version prefix. sentry release create sentry/1.0.0 means org=sentry, version=1.0.0. This is how org is specified — not via SENTRY_ORG.
- The release version (e.g.,
1.0.0) must match the release value in your Sentry.init() call. If your SDK uses bare semver, the release must be bare semver too.
--auto requires both a Sentry repository integration (GitHub/GitLab/Bitbucket) and a local git checkout. It lists repos from the API and matches against your local origin remote URL, then sends the HEAD commit SHA. Without a checkout, use --local instead.- When neither
--auto nor --local is specified, the CLI tries --auto first and falls back to --local on failure.
CI/CD Setup Notes
- The
sentry npm package requires Node.js >= 22. CI runners like ubuntu-latest ship Node.js 20 — add actions/setup-node@v6 with node-version: 22.
- If
SENTRY_AUTH_TOKEN is scoped to a GitHub environment (e.g., production), set environment: production on the job.
- A full git checkout (
fetch-depth: 0) is needed for --auto to discover the remote URL and HEAD.
set-commits --auto has continue-on-error in most workflows because it requires a working repository integration. If the integration isn't configured, the step fails but the rest of the release workflow succeeds.
Common Mistakes
- Wrong issue ID format: Use
PROJECT-123 (short ID), not the numeric ID 123456789. The short ID includes the project prefix.
- Pre-authenticating unnecessarily: Don't run
sentry auth login before every command. The CLI detects missing/expired auth and prompts automatically. Only run sentry auth login if you need to switch accounts.
- Missing
--json for piping: Human-readable output includes formatting. Use --json when parsing output programmatically.
- Specifying org/project when not needed: Auto-detection resolves org/project from DSNs, env vars, config defaults, and directory names. Let it work first — only add
<org>/<project> if the CLI says it can't detect the target or detects the wrong one.
- 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.
- Release version mismatch: The
org/version positional is <org-slug>/<version>, where org/ is the org, not part of the version. sentry release create sentry/1.0.0 creates version 1.0.0 in org sentry. If your Sentry.init() uses release: "1.0.0", this is correct. Don't double-prefix like sentry/myapp/1.0.0.
- Running
set-commits --auto without a git checkout: --auto needs a local git repo to discover the origin remote URL and HEAD commit. In CI, ensure actions/checkout with fetch-depth: 0 runs before set-commits --auto.
- Using
sentry api when CLI commands suffice: sentry issue list --json already includes shortId, title, priority, level, status, permalink, and other fields at the top level. Some fields like count, userCount, firstSeen, and lastSeen may be null depending on the issue. Use --fields to select specific fields and --help to see all available fields. Only fall back to sentry api for data the CLI doesn't expose.
Prerequisites
The CLI must be installed and authenticated before use.
Installation
curl https://cli.sentry.dev/install -fsS | bash
curl https://cli.sentry.dev/install -fsS | bash -s -- --version nightly
npm install -g sentry
Authentication
sentry auth login
sentry auth login --token YOUR_SENTRY_API_TOKEN
sentry auth status
sentry auth logout
Command Reference
Auth
Authenticate with Sentry
sentry auth login — Authenticate with Sentrysentry auth logout — Log out of Sentrysentry auth refresh — Refresh your authentication tokensentry auth status — View authentication statussentry auth token — Print the stored authentication tokensentry auth whoami — Show the currently authenticated user
→ Full flags and examples: references/auth.md
Org
Work with Sentry organizations
sentry org list — List organizationssentry org view <org> — View details of an organization
<
