diff --git a/.github/assets/banner.png b/.github/assets/banner.png new file mode 100644 index 00000000..939cbd9f Binary files /dev/null and b/.github/assets/banner.png differ diff --git a/docs/src/content/docs/commands/issue.md b/docs/src/content/docs/commands/issue.md index 8e7ecd25..e4ceb4a7 100644 --- a/docs/src/content/docs/commands/issue.md +++ b/docs/src/content/docs/commands/issue.md @@ -95,3 +95,99 @@ Latest event: ```bash sentry issue view FRONT-ABC -w ``` + +### `sentry issue explain` + +Analyze an issue's root cause using Seer AI. + +```bash +sentry issue explain +``` + +This command analyzes the issue and provides: +- Identified root causes +- Reproduction steps +- Relevant code locations + +The analysis may take a few minutes for new issues. + +**Arguments:** + +| Argument | Description | +|----------|-------------| +| `` | The issue ID (numeric), short ID (e.g., PROJ-ABC), or short suffix | + +**Options:** + +| Option | Description | +|--------|-------------| +| `--org ` | Organization slug (required for short IDs if not auto-detected) | +| `--project ` | Project slug (required for short suffixes if not auto-detected) | +| `--force` | Force new analysis even if one already exists | +| `--json` | Output as JSON | + +**Examples:** + +```bash +# By numeric issue ID +sentry issue explain 123456789 + +# By short ID +sentry issue explain MYPROJECT-ABC --org my-org + +# By short suffix (requires project context) +sentry issue explain G --org my-org --project my-project + +# Force a fresh analysis +sentry issue explain 123456789 --force +``` + +**Requirements:** + +- Seer AI enabled for your organization +- GitHub integration configured with repository access +- Code mappings set up to link stack frames to source files + +### `sentry issue plan` + +Generate a solution plan for a Sentry issue using Seer AI. + +```bash +sentry issue plan +``` + +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. + +**Arguments:** + +| Argument | Description | +|----------|-------------| +| `` | The issue ID (numeric), short ID (e.g., PROJ-ABC), or short suffix | + +**Options:** + +| Option | Description | +|--------|-------------| +| `--org ` | Organization slug (required for short IDs if not auto-detected) | +| `--project ` | Project slug (required for short suffixes if not auto-detected) | +| `--cause ` | Root cause ID to plan (required if multiple causes were identified) | +| `--json` | Output as JSON | + +**Examples:** + +```bash +# After running explain, create a plan +sentry issue plan 123456789 + +# Specify which root cause to plan for (if multiple were found) +sentry issue plan 123456789 --cause 0 + +# By short ID +sentry issue plan MYPROJECT-ABC --org my-org --cause 1 +``` + +**Requirements:** + +- Root cause analysis must be completed first (`sentry issue explain`) +- GitHub integration configured for your organization +- Code mappings set up for your project \ No newline at end of file diff --git a/docs/src/content/docs/features.md b/docs/src/content/docs/features.md new file mode 100644 index 00000000..0e12be8d --- /dev/null +++ b/docs/src/content/docs/features.md @@ -0,0 +1,219 @@ +--- +title: Features +description: Advanced features of the Sentry CLI +--- + +The Sentry CLI includes several features designed to streamline your workflow, especially in complex project setups. + +## DSN Auto-Detection + +The CLI automatically detects your Sentry project from your codebase, eliminating the need to specify `--org` and `--project` flags for every command. + +### How It Works + +DSN detection follows this priority order (highest first): + +1. **Source code** - Explicit DSN in `Sentry.init()` calls +2. **Environment files** - `.env.local`, `.env`, etc. +3. **Environment variable** - `SENTRY_DSN` + +When a DSN is found, the CLI resolves it to your organization and project, then caches the result for fast subsequent lookups. + +### Supported Languages + +The CLI can detect DSNs from source code in these languages: + +| Language | File Extensions | Detection Pattern | +|----------|-----------------|-------------------| +| JavaScript/TypeScript | `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs` | `Sentry.init({ dsn: "..." })` | +| Python | `.py` | `sentry_sdk.init(dsn="...")` | +| Go | `.go` | `sentry.Init(sentry.ClientOptions{Dsn: "..."})` | +| Java | `.java` | `Sentry.init(options -> options.setDsn("..."))` | +| Ruby | `.rb` | `Sentry.init { |config| config.dsn = "..." }` | +| PHP | `.php` | `\Sentry\init(['dsn' => '...'])` | + +### Caching + +To avoid scanning your codebase on every command, the CLI caches: + +- **DSN location** - Which file contains the DSN +- **Resolved project** - The org/project slugs from the API + +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. + +### Usage + +Once your project has a DSN configured, commands automatically use it: + +```bash +# Instead of: +sentry issue list --org my-org --project my-project + +# Just run: +sentry issue list +``` + +The CLI will show which project was detected: + +``` +Detected project: my-app (from .env) + +ID SHORT ID TITLE COUNT +123456789 MYAPP-ABC TypeError: Cannot read prop... 142 +``` + +## Monorepo Support & Alias System + +In monorepos with multiple Sentry projects, the CLI generates short aliases for each project, making it easy to work with issues across projects. + +### How Aliases Work + +When you run `sentry issue list`, the CLI: + +1. Scans for DSNs in monorepo directories (`packages/`, `apps/`, etc.) +2. Generates unique short aliases for each project +3. Caches the aliases for use with other commands + +Aliases are the shortest unique prefix of each project slug. For example: + +| Project Slug | Alias | +|--------------|-------| +| `frontend` | `f` | +| `functions` | `fu` | +| `backend` | `b` | + +For projects with a common prefix (like `spotlight-electron`, `spotlight-website`), the prefix is stripped first: + +| Project Slug | Alias | +|--------------|-------| +| `spotlight-electron` | `e` | +| `spotlight-website` | `w` | +| `spotlight-backend` | `b` | + +### Using Alias-Suffix Format + +After running `issue list`, you can reference issues using the `alias-suffix` format: + +```bash +# List issues - note the ALIAS column +sentry issue list +``` + +``` +ALIAS SHORT ID TITLE COUNT +e SPOTLIGHT-ELEC-4Y TypeError: Cannot read prop... 142 +w SPOTLIGHT-WEB-ABC Failed to fetch user data 89 +b SPOTLIGHT-BACK-XYZ Connection timeout 34 +``` + +```bash +# View issue using alias-suffix +sentry issue view e-4Y + +# Explain using alias-suffix +sentry issue explain w-ABC + +# Works with any issue command +sentry issue plan b-XYZ +``` + +### Cross-Organization Support + +If you work with multiple organizations that have projects with the same slug, the CLI uses org-prefixed aliases: + +``` +ALIAS SHORT ID TITLE +o1:api ORG1-API-123 Error in API handler +o2:api ORG2-API-456 Database connection failed +``` + +## Issue ID Formats + +The CLI accepts several formats for identifying issues: + +### Numeric ID + +The internal Sentry issue ID: + +```bash +sentry issue view 123456789 +sentry issue explain 987654321 +``` + +### Full Short ID + +The project-prefixed short ID shown in Sentry UI: + +```bash +sentry issue view MYPROJECT-ABC +sentry issue explain FRONTEND-XYZ +``` + +### Short Suffix + +Just the suffix portion when `--project` context is provided: + +```bash +sentry issue view ABC --org my-org --project myproject +``` + +### Alias-Suffix + +The short alias plus suffix, available after running `issue list`: + +```bash +# First, list issues to populate the alias cache +sentry issue list + +# Then use alias-suffix format +sentry issue view e-4Y +sentry issue explain w-ABC +sentry issue plan b-XYZ +``` + +This format is especially useful in monorepos where you're working across multiple projects. + +## AI-Powered Analysis with Seer + +The CLI integrates with Sentry's Seer AI to provide root cause analysis and fix plans directly in your terminal. + +### Root Cause Analysis + +Use `sentry issue explain` to understand why an issue is happening: + +```bash +sentry issue explain MYPROJECT-ABC +``` + +Seer analyzes: +- Stack traces and error messages +- Related events and patterns +- Your codebase (via GitHub integration) + +And provides: +- Detailed root cause explanation +- Reproduction steps +- Relevant code locations + +### Fix Plans + +After understanding the root cause, use `sentry issue plan` to get actionable fix steps: + +```bash +sentry issue plan MYPROJECT-ABC +``` + +The plan includes: +- Specific files to modify +- Code changes to make +- Implementation guidance + +### Requirements + +For Seer integration to work, you need: + +1. **Seer enabled** for your organization +2. **GitHub integration** configured with repository access +3. **Code mappings** set up to link stack frames to source files + +See [Sentry's Seer documentation](https://docs.sentry.io/product/issues/issue-details/ai-suggested-solution/) for setup instructions. diff --git a/plugins/sentry-cli/skills/sentry-cli/SKILL.md b/plugins/sentry-cli/skills/sentry-cli/SKILL.md index bf793713..f886df11 100644 --- a/plugins/sentry-cli/skills/sentry-cli/SKILL.md +++ b/plugins/sentry-cli/skills/sentry-cli/SKILL.md @@ -210,6 +210,24 @@ Analyze an issue's root cause using Seer AI - `--json - Output as JSON` - `--force - Force new analysis even if one exists` +**Examples:** + +```bash +sentry issue explain + +# By numeric issue ID +sentry issue explain 123456789 + +# By short ID +sentry issue explain MYPROJECT-ABC --org my-org + +# By short suffix (requires project context) +sentry issue explain G --org my-org --project my-project + +# Force a fresh analysis +sentry issue explain 123456789 --force +``` + #### `sentry issue plan ` Generate a solution plan using Seer AI @@ -220,6 +238,21 @@ Generate a solution plan using Seer AI - `--cause - Root cause ID to plan (required if multiple causes exist)` - `--json - Output as JSON` +**Examples:** + +```bash +sentry issue plan + +# After running explain, create a plan +sentry issue plan 123456789 + +# Specify which root cause to plan for (if multiple were found) +sentry issue plan 123456789 --cause 0 + +# By short ID +sentry issue plan MYPROJECT-ABC --org my-org --cause 1 +``` + #### `sentry issue view ` View details of a specific issue