Skip to content

Commit a6131d2

Browse files
betegonclaudeBYK
authored
docs(issue): add command reference for explain and plan (#137)
## Summary Adds detailed command reference documentation for `sentry issue explain` and `sentry issue plan` to the issue commands page. These commands were documented in features.md at a high level but lacked the detailed syntax, options, and examples that `list` and `view` have. ## Changes Added documentation for both commands following the existing format: - Arguments and options tables - Multiple usage examples (numeric ID, short ID, short suffix) - Requirements section noting Seer/GitHub prerequisites ## Test plan - Preview the docs locally to verify markdown renders correctly - Check that the format matches existing `list` and `view` sections --- Closes #136 --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Burak Yigit Kaya <byk@sentry.io>
1 parent b052bbc commit a6131d2

4 files changed

Lines changed: 348 additions & 0 deletions

File tree

‎.github/assets/banner.png‎

642 KB
Loading

‎docs/src/content/docs/commands/issue.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,99 @@ Latest event:
9595
```bash
9696
sentry issue view FRONT-ABC -w
9797
```
98+
99+
### `sentry issue explain`
100+
101+
Analyze an issue's root cause using Seer AI.
102+
103+
```bash
104+
sentry issue explain <issue-id>
105+
```
106+
107+
This command analyzes the issue and provides:
108+
- Identified root causes
109+
- Reproduction steps
110+
- Relevant code locations
111+
112+
The analysis may take a few minutes for new issues.
113+
114+
**Arguments:**
115+
116+
| Argument | Description |
117+
|----------|-------------|
118+
| `<issue-id>` | The issue ID (numeric), short ID (e.g., PROJ-ABC), or short suffix |
119+
120+
**Options:**
121+
122+
| Option | Description |
123+
|--------|-------------|
124+
| `--org <org-slug>` | Organization slug (required for short IDs if not auto-detected) |
125+
| `--project <project-slug>` | Project slug (required for short suffixes if not auto-detected) |
126+
| `--force` | Force new analysis even if one already exists |
127+
| `--json` | Output as JSON |
128+
129+
**Examples:**
130+
131+
```bash
132+
# By numeric issue ID
133+
sentry issue explain 123456789
134+
135+
# By short ID
136+
sentry issue explain MYPROJECT-ABC --org my-org
137+
138+
# By short suffix (requires project context)
139+
sentry issue explain G --org my-org --project my-project
140+
141+
# Force a fresh analysis
142+
sentry issue explain 123456789 --force
143+
```
144+
145+
**Requirements:**
146+
147+
- Seer AI enabled for your organization
148+
- GitHub integration configured with repository access
149+
- Code mappings set up to link stack frames to source files
150+
151+
### `sentry issue plan`
152+
153+
Generate a solution plan for a Sentry issue using Seer AI.
154+
155+
```bash
156+
sentry issue plan <issue-id>
157+
```
158+
159+
This command requires that `sentry issue explain` has been run first to identify the root cause. It generates a solution plan with specific implementation steps to fix the issue.
160+
161+
**Arguments:**
162+
163+
| Argument | Description |
164+
|----------|-------------|
165+
| `<issue-id>` | The issue ID (numeric), short ID (e.g., PROJ-ABC), or short suffix |
166+
167+
**Options:**
168+
169+
| Option | Description |
170+
|--------|-------------|
171+
| `--org <org-slug>` | Organization slug (required for short IDs if not auto-detected) |
172+
| `--project <project-slug>` | Project slug (required for short suffixes if not auto-detected) |
173+
| `--cause <n>` | Root cause ID to plan (required if multiple causes were identified) |
174+
| `--json` | Output as JSON |
175+
176+
**Examples:**
177+
178+
```bash
179+
# After running explain, create a plan
180+
sentry issue plan 123456789
181+
182+
# Specify which root cause to plan for (if multiple were found)
183+
sentry issue plan 123456789 --cause 0
184+
185+
# By short ID
186+
sentry issue plan MYPROJECT-ABC --org my-org --cause 1
187+
```
188+
189+
**Requirements:**
190+
191+
- Root cause analysis must be completed first (`sentry issue explain`)
192+
- GitHub integration configured for your organization
193+
- Code mappings set up for your project

‎docs/src/content/docs/features.md‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
---
2+
title: Features
3+
description: Advanced features of the Sentry CLI
4+
---
5+
6+
The Sentry CLI includes several features designed to streamline your workflow, especially in complex project setups.
7+
8+
## DSN Auto-Detection
9+
10+
The CLI automatically detects your Sentry project from your codebase, eliminating the need to specify `--org` and `--project` flags for every command.
11+
12+
### How It Works
13+
14+
DSN detection follows this priority order (highest first):
15+
16+
1. **Source code** - Explicit DSN in `Sentry.init()` calls
17+
2. **Environment files** - `.env.local`, `.env`, etc.
18+
3. **Environment variable** - `SENTRY_DSN`
19+
20+
When a DSN is found, the CLI resolves it to your organization and project, then caches the result for fast subsequent lookups.
21+
22+
### Supported Languages
23+
24+
The CLI can detect DSNs from source code in these languages:
25+
26+
| Language | File Extensions | Detection Pattern |
27+
|----------|-----------------|-------------------|
28+
| JavaScript/TypeScript | `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs` | `Sentry.init({ dsn: "..." })` |
29+
| Python | `.py` | `sentry_sdk.init(dsn="...")` |
30+
| Go | `.go` | `sentry.Init(sentry.ClientOptions{Dsn: "..."})` |
31+
| Java | `.java` | `Sentry.init(options -> options.setDsn("..."))` |
32+
| Ruby | `.rb` | `Sentry.init { |config| config.dsn = "..." }` |
33+
| PHP | `.php` | `\Sentry\init(['dsn' => '...'])` |
34+
35+
### Caching
36+
37+
To avoid scanning your codebase on every command, the CLI caches:
38+
39+
- **DSN location** - Which file contains the DSN
40+
- **Resolved project** - The org/project slugs from the API
41+
42+
The cache is validated on each run by checking if the source file still contains the same DSN. If the DSN changes or the file is deleted, a full scan is triggered.
43+
44+
### Usage
45+
46+
Once your project has a DSN configured, commands automatically use it:
47+
48+
```bash
49+
# Instead of:
50+
sentry issue list --org my-org --project my-project
51+
52+
# Just run:
53+
sentry issue list
54+
```
55+
56+
The CLI will show which project was detected:
57+
58+
```
59+
Detected project: my-app (from .env)
60+
61+
ID SHORT ID TITLE COUNT
62+
123456789 MYAPP-ABC TypeError: Cannot read prop... 142
63+
```
64+
65+
## Monorepo Support & Alias System
66+
67+
In monorepos with multiple Sentry projects, the CLI generates short aliases for each project, making it easy to work with issues across projects.
68+
69+
### How Aliases Work
70+
71+
When you run `sentry issue list`, the CLI:
72+
73+
1. Scans for DSNs in monorepo directories (`packages/`, `apps/`, etc.)
74+
2. Generates unique short aliases for each project
75+
3. Caches the aliases for use with other commands
76+
77+
Aliases are the shortest unique prefix of each project slug. For example:
78+
79+
| Project Slug | Alias |
80+
|--------------|-------|
81+
| `frontend` | `f` |
82+
| `functions` | `fu` |
83+
| `backend` | `b` |
84+
85+
For projects with a common prefix (like `spotlight-electron`, `spotlight-website`), the prefix is stripped first:
86+
87+
| Project Slug | Alias |
88+
|--------------|-------|
89+
| `spotlight-electron` | `e` |
90+
| `spotlight-website` | `w` |
91+
| `spotlight-backend` | `b` |
92+
93+
### Using Alias-Suffix Format
94+
95+
After running `issue list`, you can reference issues using the `alias-suffix` format:
96+
97+
```bash
98+
# List issues - note the ALIAS column
99+
sentry issue list
100+
```
101+
102+
```
103+
ALIAS SHORT ID TITLE COUNT
104+
e SPOTLIGHT-ELEC-4Y TypeError: Cannot read prop... 142
105+
w SPOTLIGHT-WEB-ABC Failed to fetch user data 89
106+
b SPOTLIGHT-BACK-XYZ Connection timeout 34
107+
```
108+
109+
```bash
110+
# View issue using alias-suffix
111+
sentry issue view e-4Y
112+
113+
# Explain using alias-suffix
114+
sentry issue explain w-ABC
115+
116+
# Works with any issue command
117+
sentry issue plan b-XYZ
118+
```
119+
120+
### Cross-Organization Support
121+
122+
If you work with multiple organizations that have projects with the same slug, the CLI uses org-prefixed aliases:
123+
124+
```
125+
ALIAS SHORT ID TITLE
126+
o1:api ORG1-API-123 Error in API handler
127+
o2:api ORG2-API-456 Database connection failed
128+
```
129+
130+
## Issue ID Formats
131+
132+
The CLI accepts several formats for identifying issues:
133+
134+
### Numeric ID
135+
136+
The internal Sentry issue ID:
137+
138+
```bash
139+
sentry issue view 123456789
140+
sentry issue explain 987654321
141+
```
142+
143+
### Full Short ID
144+
145+
The project-prefixed short ID shown in Sentry UI:
146+
147+
```bash
148+
sentry issue view MYPROJECT-ABC
149+
sentry issue explain FRONTEND-XYZ
150+
```
151+
152+
### Short Suffix
153+
154+
Just the suffix portion when `--project` context is provided:
155+
156+
```bash
157+
sentry issue view ABC --org my-org --project myproject
158+
```
159+
160+
### Alias-Suffix
161+
162+
The short alias plus suffix, available after running `issue list`:
163+
164+
```bash
165+
# First, list issues to populate the alias cache
166+
sentry issue list
167+
168+
# Then use alias-suffix format
169+
sentry issue view e-4Y
170+
sentry issue explain w-ABC
171+
sentry issue plan b-XYZ
172+
```
173+
174+
This format is especially useful in monorepos where you're working across multiple projects.
175+
176+
## AI-Powered Analysis with Seer
177+
178+
The CLI integrates with Sentry's Seer AI to provide root cause analysis and fix plans directly in your terminal.
179+
180+
### Root Cause Analysis
181+
182+
Use `sentry issue explain` to understand why an issue is happening:
183+
184+
```bash
185+
sentry issue explain MYPROJECT-ABC
186+
```
187+
188+
Seer analyzes:
189+
- Stack traces and error messages
190+
- Related events and patterns
191+
- Your codebase (via GitHub integration)
192+
193+
And provides:
194+
- Detailed root cause explanation
195+
- Reproduction steps
196+
- Relevant code locations
197+
198+
### Fix Plans
199+
200+
After understanding the root cause, use `sentry issue plan` to get actionable fix steps:
201+
202+
```bash
203+
sentry issue plan MYPROJECT-ABC
204+
```
205+
206+
The plan includes:
207+
- Specific files to modify
208+
- Code changes to make
209+
- Implementation guidance
210+
211+
### Requirements
212+
213+
For Seer integration to work, you need:
214+
215+
1. **Seer enabled** for your organization
216+
2. **GitHub integration** configured with repository access
217+
3. **Code mappings** set up to link stack frames to source files
218+
219+
See [Sentry's Seer documentation](https://docs.sentry.io/product/issues/issue-details/ai-suggested-solution/) for setup instructions.

‎plugins/sentry-cli/skills/sentry-cli/SKILL.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -210,6 +210,24 @@ Analyze an issue's root cause using Seer AI
210210
- `--json - Output as JSON`
211211
- `--force - Force new analysis even if one exists`
212212

213+
**Examples:**
214+
215+
```bash
216+
sentry issue explain <issue-id>
217+
218+
# By numeric issue ID
219+
sentry issue explain 123456789
220+
221+
# By short ID
222+
sentry issue explain MYPROJECT-ABC --org my-org
223+
224+
# By short suffix (requires project context)
225+
sentry issue explain G --org my-org --project my-project
226+
227+
# Force a fresh analysis
228+
sentry issue explain 123456789 --force
229+
```
230+
213231
#### `sentry issue plan <arg0>`
214232

215233
Generate a solution plan using Seer AI
@@ -220,6 +238,21 @@ Generate a solution plan using Seer AI
220238
- `--cause <value> - Root cause ID to plan (required if multiple causes exist)`
221239
- `--json - Output as JSON`
222240

241+
**Examples:**
242+
243+
```bash
244+
sentry issue plan <issue-id>
245+
246+
# After running explain, create a plan
247+
sentry issue plan 123456789
248+
249+
# Specify which root cause to plan for (if multiple were found)
250+
sentry issue plan 123456789 --cause 0
251+
252+
# By short ID
253+
sentry issue plan MYPROJECT-ABC --org my-org --cause 1
254+
```
255+
223256
#### `sentry issue view <arg0>`
224257

225258
View details of a specific issue

0 commit comments

Comments
 (0)