> ## Documentation Index > Fetch the complete documentation index at: https://meganharrisonconsulting.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # sentry-cli > Guide for using the Sentry CLI to interact with Sentry from the command line. Use when the user asks about viewing issues, events, projects, organizations, making API calls, or authenticating with Sentry via CLI. This page is generated from the actual `SKILL.md` file on disk. ## Metadata | Field | Value | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Source group | User Skills | | Source root | `/Users/meganharrison/.agents/skills` | | Relative skill path | `sentry-cli/SKILL.md` | | Actual file | `/Users/meganharrison/.agents/skills/sentry-cli/SKILL.md` | | Description | Guide for using the Sentry CLI to interact with Sentry from the command line. Use when the user asks about viewing issues, events, projects, organizations, making API calls, or authenticating with Sentry via CLI. | | Docs overview | [User Skills](/skills/user-skills) | ## Why this exists Use this page when you want to review the real instructions behind a skill without leaving the docs site. The content below is copied from the actual `SKILL.md` file, not rewritten by hand. ## Raw SKILL.md ````md theme={null} --- name: sentry-cli version: 0.34.0 description: Guide for using the Sentry CLI to interact with Sentry from the command line. Use when the user asks about viewing issues, events, projects, organizations, making API calls, or authenticating with Sentry via CLI. requires: bins: ["sentry"] auth: true --- # 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 ` to search. This is faster than fetching OpenAPI specs externally. - **Use `sentry issue view ` 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 `/` 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 ` ` 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 ` --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 `/` arguments ### Exit Codes The CLI uses semantic exit codes. Key ranges for agents: | Range | Meaning | Agent Action | |-------|---------|-------------| | 0 | Success | Proceed normally | | 10–19 | Auth error | Prompt user to run `sentry auth login` | | 20–29 | Input error | Check command arguments and retry | | 30–39 | API error | Retry or report to user | | 40–49 | Feature unavailable | Inform user about plan/settings | | 50–59 | Operation error | Report to user | | 60–69 | Command-specific | Check stderr for details | See [Exit Codes](/exit-codes/) for the complete reference. ### Workflow Patterns #### Investigate an Issue ```bash # 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 ```bash # 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 ```bash # Stream logs in real-time (auto-detects org/project) sentry log list --follow # Filter logs by severity sentry log list --query "severity:error" ``` #### Explore the API Schema ```bash # 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 ```bash # 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 `/`. 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 ```bash # GET request (default) sentry api /api/0/organizations/my-org/ # POST request with data sentry api /api/0/organizations/my-org/projects/ --method POST --data '{"name":"new-project","platform":"python"}' ``` ### Dashboard Layout Sentry dashboards use a **6-column grid**. When adding widgets, aim to fill complete rows (widths should sum to 6). Display types with default sizes: | Display Type | Width | Height | Category | Notes | |---|---|---|---|---| | `big_number` | 2 | 1 | common | Compact KPI — place 3 per row (2+2+2=6) | | `line` | 3 | 2 | common | Half-width chart — place 2 per row (3+3=6) | | `area` | 3 | 2 | common | Half-width chart — place 2 per row | | `bar` | 3 | 2 | common | Half-width chart — place 2 per row | | `table` | 6 | 2 | common | Full-width — always takes its own row | | `stacked_area` | 3 | 2 | specialized | Stacked area chart | | `top_n` | 3 | 2 | specialized | Top N ranked list | | `categorical_bar` | 3 | 2 | specialized | Categorical bar chart | | `text` | 3 | 2 | specialized | Static text/markdown widget | | `details` | 3 | 2 | internal | Detail view | | `wheel` | 3 | 2 | internal | Pie/wheel chart | | `rage_and_dead_clicks` | 3 | 2 | internal | Rage/dead click visualization | | `server_tree` | 3 | 2 | internal | Hierarchical tree display | | `agents_traces_table` | 3 | 2 | internal | Agents traces table | Use **common** types for general dashboards. Use **specialized** only when specifically requested. Avoid **internal** types unless the user explicitly asks. Available datasets: `spans` (default), `tracemetrics`, `discover`, `issue`, `error-events`, `logs`. Run `sentry dashboard widget --help` for dataset descriptions, query formats, and examples. **Row-filling examples:** ```bash # 3 KPIs filling one row (2+2+2 = 6) sentry dashboard widget add "Error Count" --display big_number --query count sentry dashboard widget add "P95 Duration" --display big_number --query p95:span.duration sentry dashboard widget add "Throughput" --display big_number --query epm # 2 charts filling one row (3+3 = 6) sentry dashboard widget add "Errors Over Time" --display line --query count sentry dashboard widget add "Latency Over Time" --display line --query p95:span.duration # Full-width table (6 = 6) sentry dashboard widget add "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: ```bash 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: ```bash 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`: ```bash 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 `/` 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 `/`, 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 ```bash 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 ```bash 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 ` — View details of an organization → Full flags and examples: `references/org.md` ### Project Work with Sentry projects - `sentry project create ` — Create a new project - `sentry project delete ` — Delete a project - `sentry project list ` — List projects - `sentry project view ` — View details of a project → Full flags and examples: `references/project.md` ### Issue Manage Sentry issues - `sentry issue list ` — List issues in a project - `sentry issue events ` — List events for a specific issue - `sentry issue explain ` — Analyze an issue's root cause using Seer AI - `sentry issue plan ` — Generate a solution plan using Seer AI - `sentry issue view ` — View details of a specific issue - `sentry issue resolve ` — Mark an issue as resolved - `sentry issue unresolve ` — Reopen a resolved issue - `sentry issue archive ` — Archive (ignore) an issue - `sentry issue merge ` — Merge 2+ issues into a single canonical group → Full flags and examples: `references/issue.md` ### Event View and list Sentry events - `sentry event view ` — View details of one or more events - `sentry event list ` — List events for an issue → Full flags and examples: `references/event.md` ### API Make an authenticated API request - `sentry api ` — Make an authenticated API request → Full flags and examples: `references/api.md` ### CLI CLI-related commands - `sentry cli defaults ` — View and manage default settings - `sentry cli feedback ` — Send feedback about the CLI - `sentry cli fix` — Diagnose and repair CLI database issues - `sentry cli setup` — Configure shell integration - `sentry cli upgrade ` — Update the Sentry CLI to the latest version → Full flags and examples: `references/cli.md` ### Dashboard Manage Sentry dashboards - `sentry dashboard list ` — List dashboards - `sentry dashboard view ` — View a dashboard - `sentry dashboard create ` — Create a dashboard - `sentry dashboard widget add ` — Add a widget to a dashboard - `sentry dashboard widget edit ` — Edit a widget in a dashboard - `sentry dashboard widget delete ` — Delete a widget from a dashboard - `sentry dashboard revisions ` — List dashboard revisions - `sentry dashboard restore ` — Restore a dashboard revision → Full flags and examples: `references/dashboard.md` ### Replay Search and inspect Session Replays - `sentry replay list ` — List recent Session Replays - `sentry replay view ` — View a Session Replay → Full flags and examples: `references/replay.md` ### Release Work with Sentry releases - `sentry release list ` — List releases with adoption and health metrics - `sentry release view ` — View release details with health metrics - `sentry release create ` — Create a release - `sentry release finalize ` — Finalize a release - `sentry release delete ` — Delete a release - `sentry release deploy ` — Create a deploy for a release - `sentry release deploys ` — List deploys for a release - `sentry release set-commits ` — 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 ` — List repositories → Full flags and examples: `references/repo.md` ### Team Work with Sentry teams - `sentry team list ` — List teams → Full flags and examples: `references/team.md` ### Explore Query aggregate event data (Explore) - `sentry explore ` — Query aggregate event data (Explore) → Full flags and examples: `references/explore.md` ### Log View Sentry logs - `sentry log list ` — List logs from a project - `sentry log view ` — View details of one or more log entries → Full flags and examples: `references/log.md` ### Sourcemap Manage sourcemaps - `sentry sourcemap inject ` — Inject debug IDs into JavaScript files and sourcemaps - `sentry sourcemap upload ` — Upload sourcemaps to Sentry → Full flags and examples: `references/sourcemap.md` ### Span List and view spans in projects or traces - `sentry span list ` — List spans in a project or trace - `sentry span view ` — View details of specific spans → Full flags and examples: `references/span.md` ### Trace View distributed traces - `sentry trace list ` — List recent traces in a project - `sentry trace view ` — View details of a specific trace - `sentry trace logs ` — View logs associated with a trace → Full flags and examples: `references/trace.md` ### Trial Manage product trials - `sentry trial list ` — List product trials - `sentry trial start ` — Start a product trial → Full flags and examples: `references/trial.md` ### Init Initialize Sentry in your project (experimental) - `sentry init ` — Initialize Sentry in your project (experimental) → Full flags and examples: `references/init.md` ### Schema Browse the Sentry API schema - `sentry schema ` — 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 ` - 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: ```bash sentry org list --json | jq '.[] | .slug' ``` ### Opening in Browser View commands support `-w` or `--web` flag to open the resource in your browser: ```bash sentry issue view PROJ-123 -w ``` ````