--- title: "Agent Guidance" description: "Operational guidance for AI coding agents using the Sentry CLI" url: "https://cli.sentry.dev/agent-guidance/" --- # 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](https://cli.sentry.dev/exit-codes.md) 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" ``` ### Capture Events Locally (Spotlight) ```bash # 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 ```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 ``` ## Navigation - [Docs home](https://cli.sentry.dev/index.md) - [Previous: Contributing](https://cli.sentry.dev/contributing.md) - [Next: Commands](https://cli.sentry.dev/commands.md)