Sentry Cli

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 checking .sentryclirc config files, scanning for DSNs in .env files and source code, and matching 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

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
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 (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.

# 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 })

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/"

Manage Releases

# Create a release — version must match Sentry.init({ release }) exactly
sentry release create my-org/1.0.0 --project my-project

# Associate commits via repository integration (needs local git checkout)
sentry release set-commits my-org/1.0.0 --auto

# Or read commits from local git history (no integration needed)
sentry release set-commits my-org/1.0.0 --local

# Mark the release as finalized
sentry release finalize my-org/1.0.0

# Record a production deploy
sentry release deploy my-org/1.0.0 production

Key details:

• The positional is <org-slug>/<version>. In sentry release create sentry/1.0.0, sentry is the org and 1.0.0 is the version — the slash separates org from version, it is not part of the version string.
• The version must match the release value in Sentry.init(). If your SDK uses "1.0.0", the command must use org/1.0.0.
• --auto requires a Sentry repository integration (GitHub/GitLab/Bitbucket) and a local git checkout. It matches your origin remote against Sentry's repo list. Without a checkout, use --local.
• With no flag, set-commits tries --auto first and falls back to --local on failure.

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:

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:

# 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

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.

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 .sentryclirc config files, DSNs, env vars, 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 and sentry issue view --json already include shortId, title, count, userCount, priority, level, status, permalink, and other fields at the top level. When using --fields to select specific fields like count or userCount, the CLI automatically ensures these fields are present in the API response. 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

# Or install via npm/pnpm/bun
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 Sentry
• sentry auth logout — Log out of Sentry
• sentry auth refresh — Refresh your authentication token
• sentry auth status — View authentication status
• sentry auth token — Print the stored authentication token
• sentry auth whoami — Show the currently authenticated identity

→ Full flags and examples: references/auth.md

Org

Work with Sentry organizations

• sentry org list — List organizations
• sentry org view <org> — View details of an organization

→ Full flags and examples: references/org.md

Project

Work with Sentry projects

• sentry project create <name> <platform> — Create a new project
• sentry project delete <org/project> — Delete a project
• sentry project list <org/project> — List projects
• sentry project view <org/project> — View details of a project

→ Full flags and examples: references/project.md

Issue

Manage Sentry issues

• sentry issue list <org/project> — List issues in a project
• sentry issue events <issue> — List events for a specific issue
• sentry issue explain <issue> — Analyze an issue's root cause using Seer AI
• sentry issue plan <issue> — Generate a solution plan using Seer AI
• sentry issue view <issue> — View details of a specific issue
• sentry issue resolve <issue> — Mark an issue as resolved
• sentry issue unresolve <issue> — Reopen a resolved issue
• sentry issue archive <issue> — Archive (ignore) an issue
• sentry issue merge <issue...> — Merge 2+ issues into a single canonical group

→ Full flags and examples: references/issue.md

Event

View, list, and send Sentry events

• sentry event view <org/project/event-id...> — View details of one or more events
• sentry event list <issue> — List events for an issue
• sentry event send <args...> — Send a Sentry event

→ Full flags and examples: references/event.md

API

Make an authenticated API request

• sentry api <endpoint> — Make an authenticated API request

→ Full flags and examples: references/api.md

Alert

Manage Sentry alert rules

• sentry alert issues list <org/project> — List issue alert rules
• sentry alert issues view <org/project/rule-id-or-name> — View an issue alert rule
• sentry alert issues create <target> — Create an issue alert rule
• sentry alert issues delete <org/project/rule-id-or-name> — Delete an issue alert rule
• sentry alert issues edit <org/project/rule-id-or-name> — Edit an issue alert rule
• sentry alert metrics list <target> — List metric alert rules
• sentry alert metrics view <org/rule-id-or-name> — View a metric alert rule
• sentry alert metrics create <org> — Create a metric alert rule
• sentry alert metrics delete <org/rule-id-or-name> — Delete a metric alert rule
• sentry alert metrics edit <org/rule-id-or-name> — Edit a metric alert rule

→ Full flags and examples: references/alert.md

CLI

CLI-related commands

• sentry cli defaults <key value...> — View and manage default settings
• sentry cli feedback <message...> — Send feedback about the CLI
• sentry cli fix — Diagnose and repair CLI database issues
• sentry cli import — Import settings from legacy .sentryclirc files
• sentry cli setup — Configure shell integration
• sentry cli uninstall — Uninstall Sentry CLI
• sentry cli upgrade <version> — Update the Sentry CLI to the latest version

→ Full flags and examples: references/cli.md

Code-mappings

Manage code mappings for stack trace linking

• sentry code-mappings upload <path> — Upload code mappings for stack trace linking

→ Full flags and examples: references/code-mappings.md

Dart-symbol-map

Work with Dart/Flutter symbol maps

• sentry dart-symbol-map upload <path> — Upload a Dart/Flutter symbol map to Sentry

→ Full flags and examples: references/dart-symbol-map.md

Dashboard

Manage Sentry dashboards

• sentry dashboard list <org/title-filter...> — List dashboards
• sentry dashboard view <org/project/dashboard...> — View a dashboard
• sentry dashboard create <org/project/title...> — Create a dashboard
• sentry dashboard widget add <org/project/dashboard/title...> — Add a widget to a dashboard
• sentry dashboard widget edit <org/project/dashboard...> — Edit a widget in a dashboard
• sentry dashboard widget delete <org/project/dashboard...> — Delete a widget from a dashboard
• sentry dashboard revisions <org/dashboard...> — List dashboard revisions
• sentry dashboard restore <org/dashboard...> — Restore a dashboard revision

→ Full flags and examples: references/dashboard.md

Proguard

Work with ProGuard/R8 mapping files

• sentry proguard upload <path...> — Upload ProGuard/R8 mapping files to Sentry
• sentry proguard uuid <path> — Compute the UUID for a ProGuard mapping file

→ Full flags and examples: references/proguard.md

Replay

Search and inspect Session Replays

• sentry replay list <org/project> — List recent Session Replays
• sentry replay view <replay-id-or-url...> — View a Session Replay

→ Full flags and examples: references/replay.md

Release

Work with Sentry releases

• sentry release list <org/project> — List releases with adoption and health metrics
• sentry release view <org/version> — View release details with health metrics
• sentry release create <org/version> — Create a release
• sentry release finalize <org/version> — Finalize a release
• sentry release delete <org/version> — Delete a release
• sentry release archive <org/version> — Archive a release
• sentry release restore <org/version> — Restore an archived release
• sentry release deploy <org/version> <environment> <name> — Create a deploy for a release
• sentry release deploys <org/version> — List deploys for a release
• sentry release set-commits <org/version> — Set commits for a release
• sentry release propose-version — Propose a release version

→ Full flags and examples: references/release.md

Repo

Work with Sentry repositories

• sentry repo list <org/project> — List repositories

→ Full flags and examples: references/repo.md

Team

Work with Sentry teams

• sentry team list <org/project> — List teams

→ Full flags and examples: references/team.md

Explore

Query aggregate event data (Explore)

• sentry explore <target> — Query aggregate event data (Explore)

→ Full flags and examples: references/explore.md

Log

View Sentry logs

• sentry log list <org/project-or-trace-id...> — List logs from a project
• sentry log view <org/project/log-id...> — View details of one or more log entries

→ Full flags and examples: references/log.md

Monitor

Work with Sentry cron monitors

• sentry monitor run <monitor-slug command...> — Wrap a command with cron monitor check-ins
• sentry monitor list <org/project> — List cron monitors

→ Full flags and examples: references/monitor.md

Sourcemap

Manage sourcemaps

• sentry sourcemap inject <directory> — Inject debug IDs into JavaScript files and sourcemaps
• sentry sourcemap upload <directory> — Upload sourcemaps to Sentry
• sentry sourcemap resolve <directory> — Resolve and report sourcemap linkage for JavaScript files

→ Full flags and examples: references/sourcemap.md

Span

List and view spans in projects or traces

• sentry span list <org/project/trace-id...> — List spans in a project or trace
• sentry span view <trace-id/span-id...> — View details of specific spans

→ Full flags and examples: references/span.md

Trace

View distributed traces

• sentry trace list <org/project> — List recent traces in a project
• sentry trace view <org/project/trace-id...> — View details of a specific trace
• sentry trace logs <org/project/trace-id...> — View logs associated with a trace

→ Full flags and examples: references/trace.md

Trial

Manage product trials

• sentry trial list <org> — List product trials
• sentry trial start <name> <org> — Start a product trial

→ Full flags and examples: references/trial.md

Init

Initialize Sentry in your project (experimental)

• sentry init <target> <directory> — Initialize Sentry in your project (experimental)

→ Full flags and examples: references/init.md

Local

Sentry for local development

• sentry local serve — Start the local dev server and tail events
• sentry local run <command...> — Run a command with the local dev server enabled

→ Full flags and examples: references/local.md

Schema

Browse the Sentry API schema

• sentry schema <resource...> — Browse the Sentry API schema

→ Full flags and examples: references/schema.md

Global Options

All commands support the following global options:

• --help - Show help for the command
• --version - Show CLI version
• --log-level <level> - Set log verbosity (error, warn, log, info, debug, trace). Overrides SENTRY_LOG_LEVEL
• --verbose - Shorthand for --log-level debug

Output Formats

JSON Output

Most list and view commands support --json flag for JSON output, making it easy to integrate with other tools:

sentry org list --json | jq '.[] | .slug'

Opening in Browser

View commands support -w or --web flag to open the resource in your browser:

sentry issue view PROJ-123 -w

Alert Commands

Manage Sentry alert rules

sentry alert issues list <org/project>

List issue alert rules

Flags:

• -w, --web - Open in browser
• -n, --limit <value> - Maximum number of issue alert rules to list - (default: "25")
• -q, --query <value> - Filter rules by name
• -c, --cursor <value> - Pagination cursor (use "next" for next page, "prev" for previous)
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

# List issue alert rules for a project
sentry alert issues list my-org/my-project

# Filter rules by name
sentry alert issues list my-org/my-project --query "spike"

sentry alert issues view <org/project/rule-id-or-name>

View an issue alert rule

Flags:

• -w, --web - Open issue alert rules page in browser

Examples:

# View by ID
sentry alert issues view my-org/my-project/12345

# View by name
sentry alert issues view my-org/my-project/"Error Spike"

sentry alert issues create <target>

Create an issue alert rule

Flags:

• --name <value> - Rule name
• -c, --condition <value>... - Condition object JSON (repeatable, or pass one JSON array)
• -a, --action <value>... - Action object JSON (repeatable, or pass one JSON array)
• -m, --action-match <value> - Condition/action match mode: all or any
• --frequency <value> - Frequency in minutes (default: 30) - (default: 30)
• --environment <value> - Environment filter
• --filter <value>... - Filter object JSON (repeatable, or pass one JSON array)
• --filter-match <value> - Filter match mode: all or any
• --owner <value> - Owner (team:user style value accepted by Sentry API)
• -n, --dry-run - Show what would happen without making changes

Examples:

# Create an issue alert rule with inline JSON condition/action
sentry alert issues create my-org/my-project \
  --name "Error Spike" \
  --condition '{"id":"sentry.rules.conditions.first_seen_event.FirstSeenEventCondition"}' \
  --action '{"id":"sentry.mail.actions.NotifyEmailAction","targetType":"Team","targetIdentifier":1}' \
  --action-match any

sentry alert issues delete <org/project/rule-id-or-name>

Delete an issue alert rule

Flags:

• -y, --yes - Skip confirmation prompt
• -f, --force - Force the operation without confirmation
• -n, --dry-run - Show what would happen without making changes

Examples:

# Delete with preview
sentry alert issues delete my-org/my-project/12345 --dry-run

sentry alert issues edit <org/project/rule-id-or-name>

Edit an issue alert rule

Flags:

• --name <value> - New rule name
• --status <value> - Rule status: active or disabled
• -c, --condition <value>... - Condition object JSON (repeatable, or pass one JSON array)
• -a, --action <value>... - Action object JSON (repeatable, or pass one JSON array)
• -m, --action-match <value> - Condition/action match mode: all or any
• --frequency <value> - Frequency in minutes
• --environment <value> - Environment value (pass empty string to clear)
• --filter <value>... - Filter object JSON (repeatable, or pass one JSON array)
• --filter-match <value> - Filter match mode: all or any
• --owner <value> - Owner value (pass empty string to clear)

Examples:

# Edit issue alert name/status
sentry alert issues edit my-org/my-project/12345 --name "Prod Error Spike" --status disabled

sentry alert metrics list <target>

List metric alert rules

Flags:

• -w, --web - Open in browser
• -n, --limit <value> - Maximum number of metric alert rules to list - (default: "25")
• -q, --query <value> - Filter rules by name
• -c, --cursor <value> - Pagination cursor (use "next" for next page, "prev" for previous)
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

# List metric alert rules for an organization
sentry alert metrics list my-org/

sentry alert metrics view <org/rule-id-or-name>

View a metric alert rule

Flags:

• -w, --web - Open metric alert rules page in browser

Examples:

# View by ID
sentry alert metrics view my-org/67890

# View by name
sentry alert metrics view my-org/"P95 latency alert"

sentry alert metrics create <org>

Create a metric alert rule

Flags:

• --name <value> - Rule name
• --query <value> - Metric query filter string
• --aggregate <value> - Aggregate expression (for example count(), p95(transaction.duration))
• --dataset <value> - Dataset (errors, transactions, sessions, events, spans, metrics)
• --time-window <value> - Evaluation window in minutes
• -t, --trigger <value>... - Trigger object JSON (repeatable, or pass one JSON array)
• -p, --project <value>... - Project slug filter (repeatable or comma-separated)
• --environment <value> - Environment filter
• --owner <value> - Owner value accepted by Sentry API
• -n, --dry-run - Show what would happen without making changes

Examples:

# Create an organization metric alert rule
sentry alert metrics create my-org \
  --name "P95 Latency" \
  --query "environment:prod" \
  --aggregate "p95(transaction.duration)" \
  --dataset transactions \
  --time-window 5 \
  --trigger '{"alertThreshold":500,"actions":[{"id":"sentry.mail.actions.NotifyEmailAction","targetType":"Team","targetIdentifier":1}]}'

sentry alert metrics delete <org/rule-id-or-name>

Delete a metric alert rule

Flags:

• -y, --yes - Skip confirmation prompt
• -f, --force - Force the operation without confirmation
• -n, --dry-run - Show what would happen without making changes

Examples:

# Delete without prompt
sentry alert metrics delete my-org/67890 --yes

sentry alert metrics edit <org/rule-id-or-name>

Edit a metric alert rule

Flags:

• --name <value> - New rule name
• --status <value> - active or disabled
• --query <value> - Metric query filter
• --aggregate <value> - Aggregate expression
• --dataset <value> - Dataset (errors, transactions, sessions, events, spans, metrics)
• --time-window <value> - Evaluation window in minutes
• -t, --trigger <value>... - Trigger object JSON (repeatable, or pass one JSON array)
• -p, --project <value>... - Project slug filter (repeatable or comma-separated)
• --environment <value> - Environment value (pass empty string to clear)
• --owner <value> - Owner value (pass empty string to clear)

Examples:

# Edit metric alert query/window
sentry alert metrics edit my-org/67890 --query "environment:prod event.type:error" --time-window 15

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

API Commands

Make an authenticated API request

sentry api <endpoint>

Make an authenticated API request

Flags:

• -X, --method <value> - The HTTP method for the request - (default: "GET")
• -d, --data <value> - Inline JSON body for the request (like curl -d)
• -F, --field <value>... - Add a typed parameter (key=value, key[sub]=value, key[]=value)
• -f, --raw-field <value>... - Add a string parameter without JSON parsing
• -H, --header <value>... - Add a HTTP request header in key:value format
• --input <value> - The file to use as body for the HTTP request (use "-" to read from standard input)
• --silent - Do not print the response body
• --verbose - Include full HTTP request and response in the output
• -n, --dry-run - Show the resolved request without sending it

Examples:

# List organizations
sentry api organizations/

# Get a specific issue
sentry api issues/123456789/

# Create a release
sentry api organizations/my-org/releases/ \
  -X POST -F version=1.0.0

# With inline JSON body
sentry api issues/123456789/ \
  -X POST -d '{"status": "resolved"}'

# Update an issue status
sentry api issues/123456789/ \
  -X PUT -F status=resolved

# Assign an issue
sentry api issues/123456789/ \
  -X PUT --field assignedTo="user@example.com"

sentry api projects/my-org/my-project/ -X DELETE

# Add custom headers
sentry api organizations/ -H "X-Custom: value"

# Read body from a file
sentry api projects/my-org/my-project/releases/ -X POST --input release.json

# Verbose mode (shows full HTTP request/response)
sentry api organizations/ --verbose

# Preview the request without sending
sentry api organizations/ --dry-run

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Auth Commands

Authenticate with Sentry

sentry auth login

Authenticate with Sentry

Flags:

• --token <value> - Authenticate using an API token instead of OAuth
• --timeout <value> - Timeout for OAuth flow in seconds (default: 900) - (default: "900")
• --force - Re-authenticate without prompting
• --url <value> - Sentry instance URL to authenticate against (e.g. https://sentry.example.com). Required for self-hosted; defaults to SaaS (https://sentry.io).
• --read-only - Request only read-only OAuth scopes (project:read, org:read, event:read, member:read, team:read). Useful for handing tokens to AI agents or CI jobs that should not be able to mutate Sentry state.
• -s, --scope <value>... - Request specific OAuth scopes (repeatable, comma-separated). E.g. --scope project:read --scope org:read. Overrides the default scope set.

Examples:

sentry auth login

sentry auth login --token YOUR_SENTRY_API_TOKEN

SENTRY_URL=https://sentry.example.com sentry auth login

SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN

sentry auth logout

Log out of Sentry

Examples:

sentry auth logout

sentry auth refresh

Refresh your authentication token

Flags:

• --force - Force refresh even if token is still valid
• --read-only - Re-authenticate with read-only OAuth scopes (project:read, org:read, event:read, member:read, team:read)
• -s, --scope <value>... - Re-authenticate with specific OAuth scopes (repeatable, comma-separated). E.g. --scope project:read --scope org:read

Examples:

sentry auth refresh

sentry auth status

View authentication status

Flags:

• --show-token - Show the stored token (masked by default)
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

sentry auth status

# Show the raw token
sentry auth status --show-token

# View current user
sentry auth whoami

sentry auth token

Print the stored authentication token

Examples:

sentry auth token

sentry auth whoami

Show the currently authenticated identity

Flags:

• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

CLI Commands

CLI-related commands

sentry cli defaults <key value...>

View and manage default settings

Flags:

• --clear - Clear the specified default, or all defaults if no key is given
• -y, --yes - Skip confirmation prompt
• -f, --force - Force the operation without confirmation

Examples:

# Show all current defaults
sentry cli defaults

# Set default organization
sentry cli defaults org my-org

# Set default project
sentry cli defaults project my-project

# Set default Sentry URL (self-hosted)
sentry cli defaults url https://sentry.example.com

# Set custom HTTP headers (self-hosted, e.g. for IAP/proxies)
sentry cli defaults headers "X-IAP: token"

# Set a custom CA certificate (self-hosted, behind a TLS proxy)
sentry cli defaults ca-cert /path/to/ca.pem

# Disable telemetry
sentry cli defaults telemetry off

# Clear a single default
sentry cli defaults org --clear

# Clear all defaults
sentry cli defaults --clear

sentry cli feedback <message...>

Send feedback about the CLI

Examples:

# Send positive feedback
sentry cli feedback i love this tool

# Report an issue
sentry cli feedback the issue view is confusing

sentry cli fix

Diagnose and repair CLI database issues

Flags:

• --dry-run - Show what would be fixed without making changes

Examples:

sentry cli fix

sentry cli import

Import settings from legacy .sentryclirc files

Flags:

• -y, --yes - Skip confirmation prompt
• -n, --dry-run - Show what would happen without making changes
• --url <value> - Explicitly trust this URL (bypasses same-file trust check)
• --skip-validation - Skip token validation against the Sentry API

Examples:

# Auto-detect and import .sentryclirc
sentry cli import

# Preview what would be imported
sentry cli import --dry-run

# Skip confirmation prompt
sentry cli import --yes

# Explicitly trust a self-hosted URL
sentry cli import --url https://sentry.example.com

# Skip API validation of the imported token
sentry cli import --skip-validation

sentry cli setup

Configure shell integration

Flags:

• --install - Install the binary from a temp location to the system path
• --method <value> - Installation method (curl, npm, pnpm, bun, yarn)
• --channel <value> - Release channel to persist (stable or nightly)
• --no-modify-path - Skip PATH modification
• --no-completions - Skip shell completion installation
• --no-agent-skills - Skip agent skill installation for AI coding assistants
• --quiet - Suppress output (for scripted usage)

Examples:

# Run full setup (PATH, completions, agent skills)
sentry cli setup

# Skip agent skill installation
sentry cli setup --no-agent-skills

# Skip PATH and completion modifications
sentry cli setup --no-modify-path --no-completions

sentry cli uninstall

Uninstall Sentry CLI

Flags:

• --keep-config - Keep the config directory (~/.sentry) and auth tokens
• -y, --yes - Skip confirmation prompt
• -f, --force - Force the operation without confirmation
• -n, --dry-run - Show what would happen without making changes

Examples:

# Show what would be removed (dry run)
sentry cli uninstall --dry-run

# Uninstall, keeping config directory
sentry cli uninstall --yes --keep-config

# Full uninstall with confirmation
sentry cli uninstall

sentry cli upgrade <version>

Update the Sentry CLI to the latest version

Flags:

• --check - Check for updates without installing
• --force - Force upgrade even if already on the latest version
• --offline - Upgrade using only cached version info and patches (no network)
• --method <value> - Installation method to use (curl, brew, npm, pnpm, bun, yarn)

Examples:

sentry cli upgrade --check

# Upgrade to latest stable
sentry cli upgrade

# Upgrade to a specific version
sentry cli upgrade 0.5.0

# Force re-download
sentry cli upgrade --force

# Switch to nightly builds
sentry cli upgrade nightly

# Switch back to stable
sentry cli upgrade stable

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Code-mappings Commands

Manage code mappings for stack trace linking

sentry code-mappings upload <path>

Upload code mappings for stack trace linking

Flags:

• --repo <value> - Repository name (e.g., owner/repo). Auto-detected from git remote if omitted.
• --default-branch <value> - Default branch name. Auto-detected from git remote HEAD if omitted.

Examples:

# Upload code mappings from a JSON file
sentry code-mappings upload mappings.json

# Specify repository explicitly
sentry code-mappings upload mappings.json --repo owner/repo

# Specify repository and default branch
sentry code-mappings upload mappings.json --repo owner/repo --default-branch develop

# Output as JSON
sentry code-mappings upload mappings.json --json

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Dart-symbol-map Commands

Work with Dart/Flutter symbol maps

sentry dart-symbol-map upload <path>

Upload a Dart/Flutter symbol map to Sentry

Flags:

• -d, --debug-id <value> - Debug ID (UUID) from the companion native debug file
• --no-upload - Validate the file without uploading (dry-run)

Examples:

# Upload a dart symbol map with a debug ID
sentry dart-symbol-map upload --debug-id 12345678-1234-1234-1234-123456789abc mapping.json

# Validate without uploading
sentry dart-symbol-map upload --debug-id 12345678-1234-1234-1234-123456789abc mapping.json --no-upload

# Output as JSON
sentry dart-symbol-map upload --debug-id 12345678-1234-1234-1234-123456789abc mapping.json --json

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Dashboard Commands

Manage Sentry dashboards

sentry dashboard list <org/title-filter...>

List dashboards

Flags:

• -w, --web - Open in browser
• -n, --limit <value> - Maximum number of dashboards to list - (default: "25")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

Examples:

# List all dashboards
sentry dashboard list

# Filter by name pattern
sentry dashboard list "Backend*"

# Open dashboard list in browser
sentry dashboard list -w

sentry dashboard view <org/project/dashboard...>

View a dashboard

Flags:

• -w, --web - Open in browser
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -r, --refresh <value> - Auto-refresh interval in seconds (default: 60, min: 10)
• -t, --period <value> - Time range: "7d", "2026-05-01..2026-06-01", ">=2026-05-01"

Examples:

# View by title
sentry dashboard view 'Frontend Performance'

# View by ID
sentry dashboard view 12345

# Auto-refresh every 30 seconds
sentry dashboard view "Backend Performance" --refresh 30

# Open in browser
sentry dashboard view 12345 -w

sentry dashboard create <org/project/title...>

Create a dashboard

Examples:

sentry dashboard create 'Frontend Performance'

sentry dashboard widget add <org/project/dashboard/title...>

Add a widget to a dashboard

Flags:

• -d, --display <value> - Display type (big_number, line, area, bar, table, stacked_area, top_n, text, categorical_bar, details, wheel, rage_and_dead_clicks, server_tree, agents_traces_table)
• --dataset <value> - Widget dataset (default: spans). Accepts canonical names and API synonyms: spans, error-events/errors, transaction-like/transactions, tracemetrics/metrics, logs, issue, discover
• -q, --query <value>... - Aggregate expression (e.g. count, p95:span.duration)
• -w, --where <value> - Search conditions filter (e.g. is:unresolved)
• -g, --group-by <value>... - Group-by column (repeatable)
• -s, --sort <value> - Order by (prefix - for desc, e.g. -count)
• -n, --limit <value> - Result limit
• -x, --col <value> - Grid column position (0-based, 0–5)
• -y, --row <value> - Grid row position (0-based)
• --width <value> - Widget width in grid columns (1–6)
• --height <value> - Widget height in grid rows (min 1)
• -l, --layout <value> - Layout mode: sequential (append in order) or dense (fill gaps) - (default: "sequential")

Examples:

# Simple counter widget
sentry dashboard widget add 'My Dashboard' "Error Count" \
  --display big_number --query count

# Line chart with group-by
sentry dashboard widget add 'My Dashboard' "Errors by Browser" \
  --display line --query count --group-by browser.name

# Table with multiple aggregates, sorted descending
sentry dashboard widget add 'My Dashboard' "Top Endpoints" \
  --display table \
  --query count --query p95:span.duration \
  --group-by transaction \
  --sort -count --limit 10

# With search filter
sentry dashboard widget add 'My Dashboard' "Slow Requests" \
  --display bar --query p95:span.duration \
  --where "span.op:http.client" \
  --group-by span.description

sentry dashboard widget edit <org/project/dashboard...>

Edit a widget in a dashboard

Flags:

• -i, --index <value> - Widget index (0-based)
• -t, --title <value> - Widget title to match
• --new-title <value> - New widget title
• -d, --display <value> - Display type (big_number, line, area, bar, table, stacked_area, top_n, text, categorical_bar, details, wheel, rage_and_dead_clicks, server_tree, agents_traces_table)
• --dataset <value> - Widget dataset (default: spans). Accepts canonical names and API synonyms: spans, error-events/errors, transaction-like/transactions, tracemetrics/metrics, logs, issue, discover
• -q, --query <value>... - Aggregate expression (e.g. count, p95:span.duration)
• -w, --where <value> - Search conditions filter (e.g. is:unresolved)
• -g, --group-by <value>... - Group-by column (repeatable)
• -s, --sort <value> - Order by (prefix - for desc, e.g. -count)
• -n, --limit <value> - Result limit
• -x, --col <value> - Grid column position (0-based, 0–5)
• -y, --row <value> - Grid row position (0-based)
• --width <value> - Widget width in grid columns (1–6)
• --height <value> - Widget height in grid rows (min 1)

Examples:

# Change display type
sentry dashboard widget edit 12345 --title 'Error Count' --display bar

# Rename a widget
sentry dashboard widget edit 'My Dashboard' --index 0 --new-title 'Total Errors'

# Change the query
sentry dashboard widget edit 12345 --title 'Error Rate' --query p95:span.duration

sentry dashboard widget delete <org/project/dashboard...>

Delete a widget from a dashboard

Flags:

• -i, --index <value> - Widget index (0-based)
• -t, --title <value> - Widget title to match
• -y, --yes - Skip confirmation prompt
• -f, --force - Force the operation without confirmation
• -n, --dry-run - Show what would happen without making changes

Examples:

# Delete by title
sentry dashboard widget delete 'My Dashboard' --title 'Error Count'

# Delete by index
sentry dashboard widget delete 12345 --index 2

sentry dashboard revisions <org/dashboard...>

List dashboard revisions

Flags:

• -n, --limit <value> - Maximum number of revisions to list - (default: "25")
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

Examples:

# List revisions by dashboard title
sentry dashboard revisions 'Frontend Performance'

# List revisions by dashboard ID
sentry dashboard revisions 12345

# With explicit org
sentry dashboard revisions my-org 12345

sentry dashboard restore <org/dashboard...>

Restore a dashboard revision

Flags:

• -r, --revision <value> - Revision ID to restore

Examples:

# Restore by dashboard title and revision number
sentry dashboard restore 'Frontend Performance' --revision 3

# Restore by dashboard ID
sentry dashboard restore 12345 --revision 1

# With explicit org
sentry dashboard restore my-org 12345 --revision 1

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Event Commands

View, list, and send Sentry events

sentry event view <org/project/event-id...>

View details of one or more events

Flags:

• -w, --web - Open in browser
• --spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

sentry event view abc123def456abc123def456abc12345

# Open in browser
sentry event view abc123def456abc123def456abc12345 -w

sentry event list <issue>

List events for an issue

Flags:

• -n, --limit <value> - Number of events (1-1000) - (default: "25")
• -q, --query <value> - Search query (Sentry search syntax)
• --full - Include full event body (stacktraces)
• -t, --period <value> - Time range: "7d", "2026-05-01..2026-06-01", ">=2026-05-01" - (default: "7d")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

JSON Fields (use --json --fields to select specific fields):

Examples:

# List events for an issue (using short ID)
sentry event list PROJ-ABC

# List events for an issue (using numeric ID)
sentry event list 123456789

# Filter by search query
sentry event list PROJ-ABC --query "browser:Chrome"

# Include full event bodies (stacktraces)
sentry event list PROJ-ABC --full

# Limit results and time range
sentry event list PROJ-ABC --limit 50 --period 24h

# Paginate through results
sentry event list PROJ-ABC -c next
sentry event list PROJ-ABC -c prev

# Output as JSON
sentry event list PROJ-ABC --json

sentry event send <args...>

Send a Sentry event

Flags:

• --dsn <value> - DSN to send events to (overrides SENTRY_DSN env var)
• -m, --message <value>... - Event message (repeat for multi-line)
• -a, --message-arg <value>... - Arguments for message template (repeat for multiple)
• -l, --level <value> - Event severity level - (default: "error")
• -r, --release <value> - Release version
• -d, --dist <value> - Distribution identifier
• -E, --env <value> - Environment name (e.g. production, staging)
• -p, --platform <value> - Platform identifier (default: other)
• -t, --tag <value>... - Tag as KEY:VALUE (repeat for multiple)
• -e, --extra <value>... - Extra data as KEY:VALUE (repeat for multiple)
• -u, --user <value>... - User info as KEY:VALUE — id, email, username, ip_address, or custom
• -f, --fingerprint <value>... - Custom fingerprint part (repeat for multiple)
• --timestamp <value> - Event timestamp (Unix epoch, ISO 8601, or RFC 2822)
• --no-environ - Do not include environment variables in the event
• --logfile <value> - Path to a log file — last 100 lines are attached as breadcrumbs
• --with-categories - Parse 'CATEGORY: message' prefixes from logfile breadcrumbs
• --raw - Send file contents as-is without parsing

Examples:

# Send an error event (default level)
sentry event send -m "Something went wrong"

# Specify level, release, and environment
sentry event send -m "Deploy check" -l info -r 1.0.0 -E production

# Add tags and extra data
sentry event send -m "Payment failed" --tag env:prod --tag region:us-east --extra amount:99.99

# Set user context
sentry event send -m "Login error" --user id:42 --user email:alice@example.com

# Custom fingerprint to group related events together
sentry event send -m "DB timeout" --fingerprint db-timeout --fingerprint {{ default }}

# Send a serialized Sentry Event object
sentry event send ./crash.json

# Send without re-parsing (raw mode — also supports pre-built envelopes)
sentry event send --raw ./crash.json
sentry event send --raw ./captured.envelope

# Explicit DSN
sentry event send -m "Test" --dsn "https://key@o123.ingest.us.sentry.io/456"

# Via environment variable
export SENTRY_DSN="https://key@o123.ingest.us.sentry.io/456"
sentry event send -m "Test"

sentry send-event    # same as: sentry event send

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Explore Commands

Query aggregate event data (Explore)

sentry explore <target>

Query aggregate event data (Explore)

Flags:

• -F, --field <value>... - API field or aggregate (repeatable). E.g., title, "count()", "p50(transaction.duration)"
• -m, --metric <value> - Metric name for --dataset metrics. Auto-resolves type/unit via API.
• --agg <value> - Aggregation for --metric (sum, avg, count, p50, p95, etc.) - (default: "sum")
• -d, --dataset <value> - Dataset to query (errors, spans, metrics, logs, replays) - (default: "errors")
• -q, --query <value> - Search query (Sentry search syntax)
• -s, --sort <value> - Sort field (prefix with - for desc, e.g., "-count()")
• -e, --environment <value>... - Replay environment filter for --dataset replays (repeatable, comma-separated)
• -n, --limit <value> - Number of rows (1-1000) - (default: "25")
• -t, --period <value> - Time range: "7d", "2026-05-01..2026-06-01", ">=2026-05-01" - (default: "24h")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

Examples:

# Top errors in the last 24 hours, scoped to a project
sentry explore my-org/cli

# All projects in an org
sentry explore my-org/

# Bare project slug (searches across orgs)
sentry explore cli

# Auto-detect from DSN/config
sentry explore

# Errors with user impact for a specific UTC window
sentry explore my-org/cli -F title -F "count()" -F "count_unique(user)" \
  --period "2024-01-15T00:00:00Z/2024-01-16T00:00:00Z"

# Filter by specific error type (combines with auto-injected project filter)
sentry explore my-org/cli -F title -F "count()" \
  -q "error.type:TypeError" --period 1h

# Span operation latency by route
sentry explore my-org/cli -F span.op -F "p50(span.duration)" \
  -F "p95(span.duration)" --dataset spans --period 1h

# Top spans by count
sentry explore my-org/cli -F span.op -F "count()" \
  --dataset spans --sort "-count()"

# Sum a custom metric (e.g., LLM token usage) across an org
sentry explore my-org/ -m llm.token_usage --dataset metrics --period 7d

# Break down by a tag column (e.g., model name)
sentry explore my-org/seer -F gen_ai.request.model \
  -m llm.token_usage --dataset metrics --period 7d

# Use a different aggregation (default is sum)
sentry explore my-org/ -m cache.hit_rate --agg avg --dataset metrics

sentry explore my-org/ \
  -F "sum(value,llm.token_usage,distribution,none)" \
  --dataset metrics --period 7d

# Log severity counts in the last hour
sentry explore my-org/cli -F severity -F "count()" \
  --dataset logs --period 1h

# Pipe to jq for filtering
sentry explore my-org/cli -F title -F "count()" --json | jq '.data[:5]'

# Get raw data for analysis
sentry explore my-org/cli -F title -F "count()" -F "count_unique(user)" \
  --json --limit 100

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Init Commands

Initialize Sentry in your project (experimental)

sentry init <target> <directory>

Initialize Sentry in your project (experimental)

Flags:

• -y, --yes - Accept non-interactive defaults (requires --features outside a TTY)
• -n, --dry-run - Show what would happen without making changes
• --features <value>... - Features to enable: errors,tracing,logs,replay,metrics,profiling,sourcemaps,crons,ai-monitoring,user-feedback
• -t, --team <value> - Team slug to create the project under
• --app <value> - App to initialize in a monorepo (required with --yes when multiple apps are detected)
• --tui - Use the Ink-based interactive UI (default). Pass --no-tui to fall back to plain log output.

Examples:

# Interactive setup
sentry init

# Non-interactive agent/CI setup
sentry init --yes --features errors,tracing,replay

# Dry run to preview changes
sentry init --dry-run

# Target a subdirectory
sentry init ./my-app

# Use a specific org (auto-detect project)
sentry init acme/

# Use a specific org and project
sentry init acme/my-app

# Assign a team when creating a new project
sentry init acme/ --team backend

# Enable specific features
sentry init --features profiling,replay

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Issue Commands

Manage Sentry issues

sentry issue list <org/project>

List issues in a project

Flags:

• -q, --query <value> - Search query (Sentry syntax, implicit AND, no OR operator)
• -n, --limit <value> - Maximum number of issues to list - (default: "25")
• -s, --sort <value> - Sort by: date, new, freq, user - (default: "date")
• -t, --period <value> - Time range: "7d", "2026-05-01..2026-06-01", ">=2026-05-01" - (default: "90d")
• -c, --cursor <value> - Pagination cursor (use "next" for next page, "prev" for previous)
• --compact - Single-line rows for compact output (auto-detects if omitted)
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

JSON Fields (use --json --fields to select specific fields):

Examples:

# List issues in a specific project
sentry issue list my-org/frontend

# All projects in an org
sentry issue list my-org/

# Search for a project across organizations
sentry issue list frontend

# Show only unresolved issues
sentry issue list my-org/frontend --query "is:unresolved"

# Show resolved issues
sentry issue list my-org/frontend --query "is:resolved"

# Sort by frequency
sentry issue list my-org/frontend --sort freq --limit 20

# Multiple filters (space-separated = implicit AND)
sentry issue list --query "is:unresolved level:error assigned:me"

# Negation and wildcards
sentry issue list --query "!browser:Chrome message:*timeout*"

# Match multiple values for one key (in-list syntax)
sentry issue list --query "browser:[Chrome,Firefox]"

sentry issue events <issue>

List events for a specific issue

Flags:

• -n, --limit <value> - Number of events (1-1000) - (default: "25")
• -q, --query <value> - Search query (Sentry search syntax)
• --full - Include full event body (stacktraces)
• -t, --period <value> - Time range: "7d", "2026-05-01..2026-06-01", ">=2026-05-01" - (default: "7d")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

JSON Fields (use --json --fields to select specific fields):

Examples:

# List recent events for an issue
sentry issue events FRONT-ABC

# Filter events by search query
sentry issue events FRONT-ABC --query "browser:Chrome"

# Show full event details
sentry issue events FRONT-ABC --full

# Limit results and filter by time period
sentry issue events FRONT-ABC --limit 50 --period 24h

# Paginate through results
sentry issue events FRONT-ABC -c next

sentry issue explain <issue>

Analyze an issue's root cause using Seer AI

Flags:

• --force - Force new analysis even if one exists
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

# View the most recent issue
sentry issue view @latest

# Explain the most frequently occurring issue
sentry issue explain @most_frequent

# Generate a fix plan for the latest issue
sentry issue plan @latest

# Analyze root cause (may take a few minutes for new issues)
sentry issue explain 123456789

# By short ID with org prefix
sentry issue explain my-org/MYPROJECT-ABC

# Force a fresh analysis
sentry issue explain 123456789 --force

# Generate a fix plan (automatically runs explain if needed)
sentry issue plan 123456789

# Force a fresh plan even if one already exists
sentry issue plan 123456789 --force

sentry issue plan <issue>

Generate a solution plan using Seer AI

Flags:

• --force - Force new plan even if one exists
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

sentry issue view <issue>

View details of a specific issue

Flags:

• -w, --web - Open in browser
• --spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

JSON Fields (use --json --fields to select specific fields):

Examples:

sentry issue view FRONT-ABC

# Open in browser
sentry issue view FRONT-ABC -w

# GitHub-style identifiers work too (the "#" replaces the final slash)
sentry issue view my-org/my-project#FRONT-ABC
sentry issue view my-project#FRONT-ABC

sentry issue resolve <issue>

Mark an issue as resolved

Flags:

• -i, --in <value> - Resolve in a release, next release, or commit ('<version>' | '@next' | '@commit' | '@commit:<repo>@<sha>')

Examples:

# Resolve immediately (no regression tracking)
sentry issue resolve CLI-G5

# Resolve in a specific release — future events on newer releases are
# regression-flagged
sentry issue resolve CLI-G5 --in 0.26.1

# Monorepo-style releases work too (no special parsing)
sentry issue resolve CLI-G5 --in spotlight@1.2.3

# Resolve in the next release (tied to current HEAD)
sentry issue resolve CLI-G5 --in @next
sentry issue resolve CLI-G5 -i @next

# Resolve in the current git HEAD — auto-detects the Sentry repo from
# your git origin remote (hard-errors if it can't)
sentry issue resolve CLI-G5 --in @commit

# Explicit commit + repo (no git inspection; repo must be registered in Sentry)
sentry issue resolve CLI-G5 --in @commit:getsentry/cli@abc123def

# Reopen a resolved issue
sentry issue unresolve CLI-G5
sentry issue reopen CLI-G5   # alias

sentry issue unresolve <issue>

Reopen a resolved issue

sentry issue archive <issue>

Archive (ignore) an issue

Flags:

• -u, --until <value> - Condition for unarchival: forever, auto, 30m, 10x, 10u, 10x/5m, etc.

Examples:

# Archive forever (fully silenced)
sentry issue archive CLI-G5

# Smart detection — unarchives when Sentry detects a spike in event frequency
sentry issue archive CLI-G5 --until auto

# Duration-based
sentry issue archive CLI-G5 --until 1h    # 1 hour
sentry issue archive CLI-G5 --until 7d    # 7 days
sentry issue archive CLI-G5 --until 2026-12-31  # specific date

# Count-based — unarchive after N more events
sentry issue archive CLI-G5 --until 100x

# User-based — unarchive after N more users affected
sentry issue archive CLI-G5 --until 10u

# Compound — count within a time window
sentry issue archive CLI-G5 --until 100x/1h   # 100 events within 1 hour
sentry issue archive CLI-G5 --until 10u/1d    # 10 users within 1 day

# Verbose forms also work
sentry issue archive CLI-G5 --until 10events/2hours

# 'ignore' is an alias for 'archive'
sentry issue ignore CLI-G5 --until auto

sentry issue merge <issue...>

Merge 2+ issues into a single canonical group

Flags:

• -i, --into <value> - Prefer this issue as the canonical parent (must match one of the provided IDs)

Examples:

# Let Sentry auto-pick the parent (typically the largest by event count)
sentry issue merge CLI-K9 CLI-15H CLI-15N

# Pin the canonical parent explicitly — accepts the same formats as
# positional args, including org-qualified and project-alias forms
sentry issue merge CLI-K9 CLI-15H CLI-15N --into CLI-K9
sentry issue merge my-org/CLI-K9 my-org/CLI-15H --into my-org/CLI-K9
sentry issue merge cli-k9 cli-15h --into cli-k9    # alias form

# Cross-org merges are rejected — all issues must share an organization
# Non-error issue types (performance, info, etc.) cannot be merged

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Local Commands

Sentry for local development

sentry local serve

Start the local dev server and tail events

Flags:

• -p, --port <value> - Port to listen on (default 8969) - (default: "8969")
• -H, --host <value> - Hostname to bind to (default localhost) - (default: "localhost")
• -q, --quiet - Suppress per-envelope tail output
• -f, --filter <value>... - Only show items of this type (repeatable: error, transaction, log, ai)
• -F, --format <value> - Output format: human (default) or json (NDJSON) - (default: "human")

sentry local run <command...>

Run a command with the local dev server enabled

Flags:

• -p, --port <value> - Port for the local server (default 8969) - (default: "8969")
• --host <value> - Hostname for the local server (default localhost) - (default: "localhost")
• -V, --verify - Verify SDK sends events, then exit
• -t, --timeout <value> - Kill the child after N seconds (0 = no timeout; defaults to 30 s in --verify mode) - (default: "0")

Examples:

# Start the server and tail events (default)
sentry local

# Run your app with the local server auto-enabled
sentry local run -- npm run dev
sentry local run -- python manage.py runserver

# Use a custom port
sentry local --port 9000

# Only show errors and logs (filter out transactions)
sentry local -f error -f log

# Run quietly (suppress per-envelope tail output)
sentry local --quiet

sentry local -f error -f log    # only errors and logs

sentry local -f ai          # only AI/agent spans
sentry local -f ai -f error # agent spans and errors

sentry local --format json

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Log Commands

View Sentry logs

sentry log list <org/project-or-trace-id...>

List logs from a project

Flags:

• -n, --limit <value> - Number of log entries (1-1000) - (default: "100")
• -q, --query <value> - Filter query (e.g., "level:error", "project:backend", "project:[a,b]")
• -f, --follow <value> - Stream logs (optionally specify poll interval in seconds)
• -t, --period <value> - Time range: "7d", "2026-05-01..2026-06-01", ">=2026-05-01"
• -s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")
• --fresh - Bypass cache, re-detect projects, and fetch fresh data

JSON Fields (use --json --fields to select specific fields):

Examples:

# List last 100 logs (default)
sentry log list

# Show only error logs
sentry log list -q 'level:error'

# Filter by message content
sentry log list -q 'database'

# Limit results
sentry log list --limit 50

# Stream with default 2-second poll interval
sentry log list -f

# Stream with custom 5-second poll interval
sentry log list -f 5

# Stream error logs from a specific project
sentry log list my-org/backend -f -q 'level:error'

sentry log list --json | jq '.data[] | select(.severity == "error")'

sentry log view <org/project/log-id...>

View details of one or more log entries

Flags:

• -w, --web - Open in browser
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

sentry log view 968c763c740cfda8b6728f27fb9e9b01

# With explicit project
sentry log view my-org/backend 968c763c740cfda8b6728f27fb9e9b01

# Open in browser
sentry log view 968c763c740cfda8b6728f27fb9e9b01 -w

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Monitor Commands

Work with Sentry cron monitors

sentry monitor run <monitor-slug command...>

Wrap a command with cron monitor check-ins

Flags:

• --dsn <value> - DSN to send check-ins to (overrides SENTRY_DSN env var)
• -e, --environment <value> - Environment of the monitor - (default: "production")
• -s, --schedule <value> - Upsert the monitor with this crontab schedule (e.g. '0 * * * *')
• --check-in-margin <value> - Minutes after the expected check-in before it is missed (requires --schedule)
• --max-runtime <value> - Minutes a check-in may run before timing out (requires --schedule)
• --timezone <value> - Timezone of the schedule, tz database string (requires --schedule)
• --failure-issue-threshold <value> - Consecutive failures before an issue is created (requires --schedule)
• --recovery-threshold <value> - Consecutive successes before an issue is resolved (requires --schedule)

sentry monitor list <org/project>

List cron monitors

Flags:

• -n, --limit <value> - Maximum number of monitors to list - (default: "25")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

JSON Fields (use --json --fields to select specific fields):

Examples:

# Wrap a command with cron monitor check-ins (DSN-based)
SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 \
  sentry monitor run nightly-job -- python manage.py cron

# The -- separator is optional when the command has no flags
sentry monitor run nightly-job npm run task

# Create/update the monitor on the first check-in via --schedule (crontab)
sentry monitor run nightly-job -s "0 0 * * *" --max-runtime 30 --timezone UTC -- ./backup.sh

# List cron monitors in an org
sentry monitor list my-org/

# Paginate through monitors
sentry monitor list my-org/ -c next

# Output as JSON
sentry monitor list --json

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Org Commands

Work with Sentry organizations

sentry org list

List organizations

Flags:

• -n, --limit <value> - Maximum number of organizations to list - (default: "25")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

sentry org view <org>

View details of an organization

Flags:

• -w, --web - Open in browser
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

# List organizations
sentry org list

# View organization details
sentry org view my-org

# Open in browser
sentry org view my-org -w

# JSON output
sentry org list --json

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Proguard Commands

Work with ProGuard/R8 mapping files

sentry proguard upload <path...>

Upload ProGuard/R8 mapping files to Sentry

Flags:

• --uuid <value> - Force a specific UUID instead of computing from file content (only valid with a single file)
• --no-upload - Compute and print UUIDs without uploading (dry-run)
• --require-one - Require at least one mapping file (error if none provided)

sentry proguard uuid <path>

Compute the UUID for a ProGuard mapping file

Examples:

# Compute the UUID for a ProGuard/R8 mapping file
sentry proguard uuid ./app/build/outputs/mapping/release/mapping.txt

# Output as JSON (includes the file path)
sentry proguard uuid mapping.txt --json

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Project Commands

Work with Sentry projects

sentry project create <name> <platform>

Create a new project

Flags:

• -t, --team <value> - Team to create the project under
• -n, --dry-run - Show what would happen without making changes

Examples:

# Create a new project
sentry project create my-new-app javascript-nextjs

# Create under a specific org and team
sentry project create my-org/my-new-app python --team backend-team

# Preview without creating
sentry project create my-new-app node --dry-run

sentry project delete <org/project>

Delete a project

Flags:

• -y, --yes - Skip confirmation prompt
• -f, --force - Force the operation without confirmation
• -n, --dry-run - Show what would happen without making changes

Examples:

# Delete a project (will prompt for confirmation)
sentry project delete my-org/old-project

# Delete without confirmation
sentry project delete my-org/old-project --yes

sentry project list <org/project>

List projects

Flags:

• -n, --limit <value> - Maximum number of projects to list - (default: "25")
• -p, --platform <value> - Filter by platform (e.g., javascript, python)
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

sentry project view <org/project>

View details of a project

Flags:

• -w, --web - Open in browser
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

# List all projects in an org
sentry project list my-org/

# Filter by platform
sentry project list my-org/ --platform javascript

# View project details
sentry project view my-org/frontend

# Open project in browser
sentry project view my-org/frontend -w

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Release Commands

Work with Sentry releases

sentry release list <org/project>

List releases with adoption and health metrics

Flags:

• -n, --limit <value> - Maximum number of releases to list - (default: "25")
• -s, --sort <value> - Sort: date, sessions, users, crash_free_sessions (cfs), crash_free_users (cfu) - (default: "date")
• -e, --environment <value>... - Filter by environment (repeatable, comma-separated)
• -t, --period <value> - Health stats period (e.g., 24h, 7d, 14d, 90d) - (default: "90d")
• --status <value> - Filter by status: open (default) or archived - (default: "open")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

sentry release view <org/version>

View release details with health metrics

Flags:

• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

sentry release create <org/version>

Create a release

Flags:

• -p, --project <value> - Associate with project(s), comma-separated
• --finalize - Immediately finalize the release (set dateReleased)
• --ref <value> - Git ref (branch or tag name)
• --url <value> - URL to the release source
• -n, --dry-run - Show what would happen without making changes

sentry release finalize <org/version>

Finalize a release

Flags:

• --released <value> - Custom release timestamp (ISO 8601). Defaults to now.
• --url <value> - URL for the release
• -n, --dry-run - Show what would happen without making changes

sentry release delete <org/version>

Delete a release

Flags:

• -y, --yes - Skip confirmation prompt
• -f, --force - Force the operation without confirmation
• -n, --dry-run - Show what would happen without making changes

sentry release archive <org/version>

Archive a release

Flags:

• -n, --dry-run - Show what would happen without making changes

sentry release restore <org/version>

Restore an archived release

Flags:

• -n, --dry-run - Show what would happen without making changes

sentry release deploy <org/version> <environment> <name>

Create a deploy for a release

Flags:

• --url <value> - URL for the deploy
• --started <value> - Deploy start time (ISO 8601)
• --finished <value> - Deploy finish time (ISO 8601)
• -t, --time <value> - Deploy duration in seconds (sets started = now - time, finished = now)
• -n, --dry-run - Show what would happen without making changes

sentry release deploys <org/version>

List deploys for a release

sentry release set-commits <org/version>

Set commits for a release

Flags:

• --auto - Auto-discover commits via repository integration (needs local git checkout)
• --local - Read commits from local git history
• --clear - Clear all commits from the release
• --commit <value> - Explicit commit as REPO@SHA or REPO@PREV..SHA (comma-separated)
• --initial-depth <value> - Number of commits to read with --local - (default: "20")

sentry release propose-version

Propose a release version

Examples:

# List releases (auto-detect org)
sentry release list

# List releases in a specific org
sentry release list my-org/

# View release details
sentry release view 1.0.0
sentry release view my-org/1.0.0

# Create and finalize a release
sentry release create 1.0.0 --finalize

# Create a release, then finalize separately
sentry release create 1.0.0
sentry release set-commits 1.0.0 --auto
sentry release finalize 1.0.0

# Set commits from local git history
sentry release set-commits 1.0.0 --local

# Create a deploy
sentry release deploy 1.0.0 production
sentry release deploy 1.0.0 staging "Deploy #42"

# Propose a version from git HEAD
sentry release create $(sentry release propose-version)

# List deploys for a release
sentry release deploys 1.0.0
sentry release deploys my-org/1.0.0

# Archive a release (hide it from the default list, but keep it)
sentry release archive 1.0.0
sentry release archive my-org/1.0.0 --dry-run   # Preview without archiving

# Restore a previously archived release
sentry release restore 1.0.0
sentry release restore my-org/1.0.0

# Delete a release
sentry release delete my-org/1.0.0
sentry release delete my-org/1.0.0 --yes        # Skip confirmation
sentry release delete my-org/1.0.0 --dry-run    # Preview without deleting

# Output as JSON
sentry release list --json
sentry release view 1.0.0 --json

# Full release workflow with explicit org
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

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Replay Commands

Search and inspect Session Replays

sentry replay list <org/project>

List recent Session Replays

Flags:

• -n, --limit <value> - Number of replays (1-1000) - (default: "25")
• -q, --query <value> - Search query (Sentry replay search syntax)
• -e, --environment <value>... - Filter by environment (repeatable, comma-separated)
• -s, --sort <value> - Sort by: date, oldest, duration, errors, activity, or a raw replay sort field - (default: "date")
• -t, --period <value> - Time range: "7d", "2026-05-01..2026-06-01", ">=2026-05-01" - (default: "7d")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

JSON Fields (use --json --fields to select specific fields):

Examples:

# List recent replays for a project
sentry replay list my-org/frontend

# Search across all projects in an org
sentry replay list my-org/ --query "environment:production"

# Change the time window and sort
sentry replay list my-org/frontend --period 24h --sort errors

# Paginate through results
sentry replay list my-org/frontend -c next
sentry replay list my-org/frontend -c prev

# Output machine-readable data
sentry replay list my-org/frontend --json

sentry replay view <replay-id-or-url...>

View a Session Replay

Flags:

• -w, --web - Open in browser
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

JSON Fields (use --json --fields to select specific fields):

Examples:

# View a replay by ID using auto-detected org/project context
sentry replay view 346789a703f6454384f1de473b8b9fcc

# View a replay with an explicit org
sentry replay view my-org/346789a703f6454384f1de473b8b9fcc

# View a replay with explicit org/project context
sentry replay view my-org/frontend/346789a703f6454384f1de473b8b9fcc

# Open a replay in the browser
sentry replay view my-org/346789a703f6454384f1de473b8b9fcc --web

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Repo Commands

Work with Sentry repositories

sentry repo list <org/project>

List repositories

Flags:

• -n, --limit <value> - Maximum number of repositories to list - (default: "25")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

JSON Fields (use --json --fields to select specific fields):

Examples:

# List repositories (auto-detect org)
sentry repo list

# List repos in a specific org with pagination
sentry repo list my-org/ -c next

# Output as JSON
sentry repo list --json

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Schema Commands

Browse the Sentry API schema

sentry schema <resource...>

Browse the Sentry API schema

Flags:

• --all - Show all endpoints in a flat list
• -q, --search <value> - Search endpoints by keyword

Examples:

# List all API resources
sentry schema

# Browse issue endpoints
sentry schema issues

# View details for a specific operation
sentry schema issues list

# Search for monitoring-related endpoints
sentry schema --search monitor

# Flat list of every endpoint
sentry schema --all

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Sourcemap Commands

Manage sourcemaps

sentry sourcemap inject <directory>

Inject debug IDs into JavaScript files and sourcemaps

Flags:

• --ext <value> - Comma-separated file extensions to process (default: .js,.cjs,.mjs)
• --ignore <value> - Comma-separated glob patterns to exclude (gitignore-style)
• --ignore-file <value> - Path to a file with gitignore-style patterns to exclude
• --dry-run - Show what would be modified without writing
• --allow-empty - Exit successfully when no JS + sourcemap pairs are found (default: error out to catch silent build misconfigurations)

Examples:

# Inject debug IDs into all JS files in dist/
sentry sourcemap inject ./dist

# Preview changes without writing
sentry sourcemap inject ./dist --dry-run

# Only process specific extensions
sentry sourcemap inject ./build --ext .js,.mjs

sentry sourcemap upload <directory>

Upload sourcemaps to Sentry

Flags:

• --release <value> - Release version to associate with the upload
• --dist <value> - Distribution identifier to disambiguate builds within a release
• --url-prefix <value> - URL prefix for uploaded files (default: ~/) - (default: "~/")
• --ext <value> - Comma-separated file extensions to process (default: .js,.cjs,.mjs)
• --ignore <value> - Comma-separated glob patterns to exclude (gitignore-style)
• --ignore-file <value> - Path to a file with gitignore-style patterns to exclude
• --strip-prefix <value> - Strip a prefix from uploaded file paths (e.g. 'build/')
• --strip-common-prefix - Automatically strip the longest common path prefix from all files
• --no-rewrite - Upload files as-is without injecting debug IDs
• --allow-empty - Exit successfully when no JS + sourcemap pairs are found (default: error out to catch silent build misconfigurations)

Examples:

# Upload sourcemaps from dist/
sentry sourcemap upload ./dist

# Associate with a release
sentry sourcemap upload ./dist --release 1.0.0

# Set a custom URL prefix
sentry sourcemap upload ./dist --url-prefix '~/static/js/'

sentry sourcemap upload ./dist --allow-empty

sentry sourcemap resolve <directory>

Resolve and report sourcemap linkage for JavaScript files

Flags:

• --ext <value> - Comma-separated file extensions to process (default: .js,.cjs,.mjs)
• --ignore <value> - Comma-separated glob patterns to exclude (gitignore-style)
• --ignore-file <value> - Path to a file with gitignore-style patterns to exclude

Examples:

# Report how each JS file's sourcemap resolves and whether a debug ID
# has been injected (read-only — never modifies files)
sentry sourcemap resolve ./dist

# Machine-readable output
sentry sourcemap resolve ./dist --json

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Span Commands

List and view spans in projects or traces

sentry span list <org/project/trace-id...>

List spans in a project or trace

Flags:

• -n, --limit <value> - Number of spans (<=1000) - (default: "25")
• -q, --query <value> - Filter spans (e.g., "op:db", "project:backend", "project:[cli,api]")
• -s, --sort <value> - Sort order: date, duration - (default: "date")
• -t, --period <value> - Time range: "7d", "2026-05-01..2026-06-01", ">=2026-05-01" - (default: "7d")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

JSON Fields (use --json --fields to select specific fields):

Examples:

# List recent spans in the current project
sentry span list

# Find all DB spans
sentry span list -q "op:db"

# Slow spans in the last 24 hours
sentry span list -q "duration:>100ms" --period 24h

# List spans within a specific trace
sentry span list abc123def456abc123def456abc12345

# Paginate through results
sentry span list -c next

# Show only spans from one project within a trace
sentry span list my-org/cli-server/abc123def456abc123def456abc12345

# Or use --query to filter by project
sentry span list abc123def456abc123def456abc12345 -q "project:cli-server"

# Multiple projects at once
sentry span list abc123def456abc123def456abc12345 -q "project:[cli-server,api]"

sentry span view <trace-id/span-id...>

View details of specific spans

Flags:

• --spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

# View a single span
sentry span view abc123def456abc123def456abc12345 a1b2c3d4e5f67890

# View multiple spans at once
sentry span view abc123def456abc123def456abc12345 a1b2c3d4e5f67890 b2c3d4e5f6789012

# With explicit org/project
sentry span view my-org/backend/abc123def456abc123def456abc12345 a1b2c3d4e5f67890

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Team Commands

Work with Sentry teams

sentry team list <org/project>

List teams

Flags:

• -n, --limit <value> - Maximum number of teams to list - (default: "25")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

JSON Fields (use --json --fields to select specific fields):

Examples:

# List teams
sentry team list my-org/

# Paginate through teams
sentry team list my-org/ -c next

# Output as JSON
sentry team list --json

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Trace Commands

View distributed traces

sentry trace list <org/project>

List recent traces in a project

Flags:

• -n, --limit <value> - Number of traces (1-1000) - (default: "25")
• -q, --query <value> - Search query (Sentry search syntax)
• -s, --sort <value> - Sort by: date, duration - (default: "date")
• -t, --period <value> - Time range: "7d", "2026-05-01..2026-06-01", ">=2026-05-01" - (default: "7d")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data
• -c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)

JSON Fields (use --json --fields to select specific fields):

Examples:

# List last 20 traces (default)
sentry trace list

# Sort by slowest first
sentry trace list --sort duration

# Filter by transaction name, last 24 hours
sentry trace list -q "transaction:GET /api/users" --period 24h

# Paginate through results
sentry trace list my-org/backend -c next

sentry trace view <org/project/trace-id...>

View details of a specific trace

Flags:

• -w, --web - Open in browser
• --full - Fetch full span attributes (auto-enabled with --json)
• --spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

# View trace details with span tree
sentry trace view abc123def456abc123def456abc12345

# Open trace in browser
sentry trace view abc123def456abc123def456abc12345 -w

# Auto-recover from an issue short ID
sentry trace view PROJ-123

# Filter trace view to one project's spans
sentry trace view my-org/cli-server/abc123def456abc123def456abc12345

# Full trace across all projects (default)
sentry trace view my-org/abc123def456abc123def456abc12345

# Filter trace logs by project
sentry trace logs my-org/cli-server/abc123def456abc123def456abc12345

# Multiple projects via --query
sentry trace logs abc123def456abc123def456abc12345 -q "project:[cli-server,api]"

sentry trace logs <org/project/trace-id...>

View logs associated with a trace

Flags:

• -w, --web - Open trace in browser
• -t, --period <value> - Time range: "7d", "2026-05-01..2026-06-01", ">=2026-05-01" - (default: "14d")
• -n, --limit <value> - Number of log entries (<=1000) - (default: "100")
• -q, --query <value> - Filter query (e.g., "level:error", "project:backend", "project:[a,b]")
• -s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")
• -f, --fresh - Bypass cache, re-detect projects, and fetch fresh data

Examples:

# View logs for a trace
sentry trace logs abc123def456abc123def456abc12345

# Search with a longer time window
sentry trace logs --period 30d abc123def456abc123def456abc12345

# Filter logs within a trace
sentry trace logs -q 'level:error' abc123def456abc123def456abc12345

All commands also support --json, --fields, --help, --log-level, and --verbose flags.

Trial Commands

Manage product trials

sentry trial list <org>

List product trials

JSON Fields (use --json --fields to select specific fields):

sentry trial start <name> <org>

Start a product trial

Examples:

# List all trials for the current org
sentry trial list

# List trials for a specific org
sentry trial list my-org

# Start a Seer trial
sentry trial start seer

# Start a trial for a specific org
sentry trial start replays my-org

# Start a Business plan trial (opens browser)
sentry trial start plan

All commands also support --json, --fields, --help, --log-level, and --verbose flags.