getsentry · cursor · May 11, 2026 · May 11, 2026 · May 11, 2026 · May 11, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -114,20 +114,22 @@ cli/
 │   ├── commands/           # CLI commands
 │   │   ├── auth/           # login, logout, refresh, status, token, whoami
 │   │   ├── cli/            # defaults, feedback, fix, setup, upgrade
-│   │   ├── dashboard/      # list, view, create, widget (add, edit, delete)
+│   │   ├── dashboard/      # list, view, create, revisions, restore, widget (add, edit, delete)
 │   │   ├── event/          # list, view
-│   │   ├── issue/          # list, view, events, explain, plan, resolve, unresolve, merge
+│   │   ├── issue/          # list, view, events, explain, plan, resolve, unresolve, archive, merge
 │   │   ├── log/            # list, view
 │   │   ├── org/            # list, view
 │   │   ├── project/        # list, view, create, delete
 │   │   ├── release/        # list, view, create, finalize, delete, deploy, deploys, set-commits, propose-version
+│   │   ├── replay/         # list, view
 │   │   ├── repo/           # list
 │   │   ├── sourcemap/      # inject, upload
 │   │   ├── span/           # list, view
 │   │   ├── team/           # list
 │   │   ├── trace/          # list, view, logs
 │   │   ├── trial/          # list, start
 │   │   ├── api.ts          # Direct API access command
+│   │   ├── explore.ts      # Query aggregate event data (Explore)
 │   │   ├── help.ts         # Help command
 │   │   ├── init.ts         # Initialize Sentry in your project (experimental)
 │   │   └── schema.ts       # Browse the Sentry API schema
@@ -136,14 +138,22 @@ cli/
 │   │   ├── api-client.ts   # Barrel re-export for API modules
 │   │   ├── api/            # Domain API modules
 │   │   │   ├── infrastructure.ts # Shared helpers, types, raw requests
-│   │   │   ├── organizations.ts
-│   │   │   ├── projects.ts
-│   │   │   ├── issues.ts
+│   │   │   ├── dashboards.ts
+│   │   │   ├── discover.ts
 │   │   │   ├── events.ts
-│   │   │   ├── traces.ts      # Trace + span listing
+│   │   │   ├── issues.ts
 │   │   │   ├── logs.ts
+│   │   │   ├── organizations.ts
+│   │   │   ├── projects.ts
+│   │   │   ├── releases.ts
+│   │   │   ├── replays.ts
+│   │   │   ├── repositories.ts
 │   │   │   ├── seer.ts
-│   │   │   └── trials.ts
+│   │   │   ├── sourcemaps.ts
+│   │   │   ├── teams.ts
+│   │   │   ├── traces.ts      # Trace + span listing
+│   │   │   ├── trials.ts
+│   │   │   └── users.ts
 │   │   ├── region.ts       # Multi-region resolution
 │   │   ├── telemetry.ts    # Sentry SDK instrumentation
 │   │   ├── sentry-urls.ts  # URL builders for Sentry

diff --git a/README.md b/README.md
@@ -33,13 +33,17 @@ brew install getsentry/tools/sentry
 ```bash
 npm install -g sentry
 pnpm add -g sentry
+yarn global add sentry
 bun add -g sentry
 ```
 
 ### Run Without Installing
 
 ```bash
 npx sentry@latest
+pnpm dlx sentry --help
+yarn dlx sentry --help
+bunx sentry --help
 ```
 
 ## Quick Start

diff --git a/docs/DOCUMENTATION_GAPS.md b/docs/DOCUMENTATION_GAPS.md
@@ -0,0 +1,206 @@
+# Documentation Gap Report
+
+Audit date: 2026-05-11
+Auditor: Automated analysis of code vs documentation
+
+This report identifies gaps between the Sentry CLI implementation and its documentation across all surfaces: the doc site (`docs/src/content/docs/`), `README.md`, `DEVELOPMENT.md`, `AGENTS.md`, and generated command/configuration pages.
+
+---
+
+## A. Undocumented or Missing Commands/Subcommands
+
+Command docs are auto-generated from code via `generate-command-docs.ts`, so all commands that exist in `src/commands/` get a generated page under `docs/src/content/docs/commands/`. However, **AGENTS.md** has a manually maintained architecture tree that is stale:
+
+| Missing from AGENTS.md | Source |
+|-------------------------|--------|
+| `replay/` (list, view) | `src/commands/replay/` |
+| `explore.ts` | `src/commands/explore.ts` |
+| `dashboard/revisions.ts` | `src/commands/dashboard/revisions.ts` |
+| `dashboard/restore.ts` | `src/commands/dashboard/restore.ts` |
+| `issue/archive.ts` | `src/commands/issue/archive.ts` |
+
+**AGENTS.md lists `issue/` subcommands as:** `list, view, events, explain, plan, resolve, unresolve, merge`
+**Actual subcommands:** also includes `archive` (with alias `ignore`).
+
+**AGENTS.md lists `dashboard/` subcommands as:** `list, view, create, widget (add, edit, delete)`
+**Actual subcommands:** also includes `revisions` and `restore`.
+
+The generated `contributing.md` tree is correct (it uses `generate-docs-sections.ts`), proving AGENTS.md's tree drifted manually.
+
+---
+
+## B. Undocumented Flags
+
+Since command docs are auto-generated from the Stricli route tree, all non-hidden flags are automatically documented in the generated pages. The system works correctly here. No flags are missing from the generated docs.
+
+However, some **fragment files** (hand-written examples) don't mention newer flags:
+
+| Command | Flag | Fragment Status |
+|---------|------|-----------------|
+| `sentry dashboard view` | `--refresh <interval>` | Not shown in `dashboard.md` fragment examples |
+| `sentry dashboard revisions` | (all flags) | No examples in fragment (revisions/restore are new) |
+| `sentry dashboard restore` | `--revision` | No examples in fragment |
+| `sentry issue archive` | `--until <spec>` | Extensively documented in `issue.md` fragment — good |
+| `sentry log list` | `--follow` with poll interval | Covered in `log.md` fragment — good |
+| `sentry cli defaults` | `headers`, `ca-cert` sub-keys | Not documented in `cli.md` fragment |
+
+---
+
+## C. Missing Usage Examples
+
+All 21 command fragment files contain bash examples. No fragment is empty. Coverage is good.
+
+---
+
+## D. Stale Descriptions
+
+Command brief strings and descriptions are auto-generated from code, so no drift exists on the generated pages. The fragment content (hand-written) is additive and doesn't duplicate briefs.
+
+---
+
+## E. Missing Route Mappings in Skill Generator
+
+The old `ROUTE_TO_REFERENCE` constant has been removed. The skill generator now automatically creates one reference file per visible top-level route (excluding `help`). There are no missing mappings — this is fully automated.
+
+---
+
+## F. Installation / Distribution Gaps
+
+### README.md gaps
+
+| Gap | Details |
+|-----|---------|
+| **Missing `yarn` install method** | `getting-started.mdx` lists `yarn global add sentry` and `yarn dlx sentry --help`, but `README.md` only shows npm, pnpm, bun. |
+| **Missing `pnpm dlx` / `bunx` run-without-installing** | `getting-started.mdx` documents `pnpm dlx sentry`, `yarn dlx sentry`, and `bunx sentry`. README only shows `npx sentry@latest`. |
+| **Missing nightly channel** | `getting-started.mdx` documents `--version nightly` and `SENTRY_VERSION=nightly`. README doesn't mention nightly at all. |
+| **Missing `SENTRY_VERSION` env var for CI pinning** | `getting-started.mdx` shows `SENTRY_VERSION=0.19.0 curl ...`. README doesn't mention this. |
+| **Missing `SENTRY_INIT` env var** | The install script accepts `SENTRY_INIT=1` to run the init wizard post-install. Not documented in README or getting-started. |
+
+### getting-started.mdx gaps
+
+| Gap | Details |
+|-----|---------|
+| **No mention of `SENTRY_INSTALL_DIR`** | The install script reads `SENTRY_INSTALL_DIR` to override the binary location. Not documented in getting-started. Only in the env-registry (which feeds configuration.md). |
+| **Installer flags incomplete** | The install script accepts `--no-modify-path`, `--no-completions`, `--no-agent-skills` — none of these are documented in getting-started. They're useful for CI/Docker. |
+
+---
+
+## G. Undocumented Environment Variables
+
+The `ENV_VAR_REGISTRY` in `src/lib/env-registry.ts` is the source of truth for the generated `configuration.md` page. Comparing against all `SENTRY_*` env vars used in code:
+
+| Variable | Used in Code | In ENV_VAR_REGISTRY |
+|----------|-------------|---------------------|
+| `SENTRY_AUTH_TOKEN` | Yes | Yes |
+| `SENTRY_TOKEN` | Yes | Yes |
+| `SENTRY_FORCE_ENV_TOKEN` | Yes | Yes |
+| `SENTRY_ORG` | Yes | Yes |
+| `SENTRY_PROJECT` | Yes | Yes |
+| `SENTRY_DSN` | Yes | Yes |
+| `SENTRY_RELEASE` | Yes | Yes |
+| `SENTRY_HOST` | Yes | Yes |
+| `SENTRY_URL` | Yes | Yes |
+| `SENTRY_CLIENT_ID` | Yes | Yes |
+| `SENTRY_CUSTOM_HEADERS` | Yes | Yes |
+| `SENTRY_CONFIG_DIR` | Yes | Yes |
+| `SENTRY_INSTALL_DIR` | Yes | Yes (installOnly) |
+| `SENTRY_VERSION` | Yes (install script) | Yes (installOnly) |
+| `SENTRY_INIT` | Yes (install script) | Yes (installOnly) |
+| `SENTRY_PLAIN_OUTPUT` | Yes | Yes |
+| `SENTRY_OUTPUT_FORMAT` | Yes | Yes |
+| `SENTRY_LOG_LEVEL` | Yes | Yes |
+| `SENTRY_CLI_NO_TELEMETRY` | Yes | Yes |
+| `SENTRY_CLI_NO_UPDATE_CHECK` | Yes | Yes |
+| `SENTRY_NO_CACHE` | Yes | Yes |
+| `SENTRY_MAX_PAGINATION_PAGES` | Yes | Yes |
+| `SENTRY_CLI_NO_AUTO_REPAIR` | Yes | Yes |
+| `NO_COLOR` | Yes | Yes |
+| `FORCE_COLOR` | Yes | Yes |
+| `NODE_EXTRA_CA_CERTS` | Yes | Yes |
+| **`SENTRY_INIT_TUI`** | Yes (`init/ui/factory.ts`) | **No** |
+| **`SENTRY_SCAN_DISABLE_WORKERS`** | Yes (`scan/grep.ts`) | **No** |
+| `NEXT_PUBLIC_SENTRY_DSN` | Yes (DSN detection) | No (internal) |
+| `REACT_APP_SENTRY_DSN` | Yes (DSN detection) | No (internal) |
+| `VITE_SENTRY_DSN` | Yes (DSN detection) | No (internal) |
+| `EXPO_PUBLIC_SENTRY_DSN` | Yes (DSN detection) | No (internal) |
+| `NUXT_PUBLIC_SENTRY_DSN` | Yes (DSN detection) | No (internal) |
+
+**Missing from registry (user-facing):**
+- `SENTRY_INIT_TUI` — disables the TUI for the init wizard (`=0`). Useful for CI/scripting.
+- `SENTRY_SCAN_DISABLE_WORKERS` — disables worker pool in DSN scanning (`=1`). Debugging tool.
+
+The framework-prefixed DSN variables (`NEXT_PUBLIC_SENTRY_DSN`, etc.) are internal detection helpers, not user-configurable, so omitting them is appropriate.
+
+---
+
+## H. Auth / Self-Hosted Gaps
+
+The auth and self-hosted docs are well-maintained:
+
+| Area | Status |
+|------|--------|
+| OAuth device flow | Documented in getting-started.mdx, self-hosted.md, auth.md fragment |
+| Token login | Documented |
+| OAuth scopes | Auto-generated in DEVELOPMENT.md and self-hosted.md |
+| Token precedence | Documented in auth.md fragment |
+| Self-hosted requirements | Documented (SENTRY_HOST, SENTRY_CLIENT_ID, version 26.1.0+) |
+| Token storage (SQLite) | Documented in auth.md fragment and configuration.md fragment |
+| `SENTRY_CUSTOM_HEADERS` | Documented in self-hosted.md env var table |
+| `NODE_EXTRA_CA_CERTS` | Documented in self-hosted.md env var table |
+| `.sentryclirc` support | Documented in configuration.md fragment |
+
+**Minor gaps:**
+- `auth login --url` flag for trusting self-hosted URLs is not explicitly documented. The self-hosted guide uses `SENTRY_HOST` env var instead, which works but `--url` is more explicit.
+- The `auth login --timeout` flag (OAuth device flow timeout, default 900s) is auto-documented in the generated page but not mentioned in any fragment example.
+
+---
+
+## I. Plugin/Skills Gaps
+
+| Area | Documentation | Status |
+|------|--------------|--------|
+| Automatic installation | `agentic-usage.md` | Correct: mentions setup, upgrade, `--no-agent-skills` |
+| Manual installation | `agentic-usage.md` | Correct: `npx skills add https://cli.sentry.dev` |
+| Claude Code support | `agentic-usage.md`, `plugins/README.md` | Correct |
+| Cursor support | `agentic-usage.md` | Mentioned as example of `~/.agents` consumer |
+| `~/.agents` directory | `agentic-usage.md` | Correct |
+| Plugin manifest | `plugins/README.md` | Correct |
+| Version in plugin.json | `plugins/sentry-cli/.claude-plugin/plugin.json` | Shows `0.34.0` — should match package.json's version |
+
+**Minor gaps:**
+- `agentic-usage.md` doesn't mention that skill installation requires the agent root directories (`~/.agents` or `~/.claude`) to already exist — the installer does NOT create them.
+- `plugins/README.md` mentions `.cursor/skills/` as a path, but the workspace `.cursor/` directory doesn't have a `skills/` subtree. This may confuse contributors.
+
+---
+
+## J. README / DEVELOPMENT.md Drift
+
+| Claim | File | Actual Code | Status |
+|-------|------|-------------|--------|
+| Bun v1.3+ prerequisite | README.md | `packageManager: "bun@1.3.13"` | **Correct** (auto-generated) |
+| Node.js ≥22.12 | README.md | `engines.node: ">=22.12"` | **Correct** (auto-generated) |
+| `bun run cli` dev command | AGENTS.md | `"cli": "bun run src/bin.ts"` in package.json | **Mismatch** — AGENTS.md shows `bun run dev` while README shows `bun run cli`. Both exist but serve different purposes (`dev` runs generate first). |
+| Architecture tree | AGENTS.md | Code has `replay/`, `explore.ts`, `dashboard/revisions`, `dashboard/restore`, `issue/archive` | **Stale** — AGENTS.md tree missing these entries |
+| `bun run build:all` | AGENTS.md | Exists in package.json | Correct |
+| `bun test --filter` | AGENTS.md | Bun supports this | Correct |
+| Build scripts in README | README.md | Auto-generated from curated list | Correct |
+| License FSL-1.1-Apache-2.0 | README.md | Matches package.json | Correct |
+
+---
+
+## Top 5 Most Impactful Fixes (Prioritized)
+
+### 1. Update AGENTS.md Architecture Tree
+**Impact: High** — AI agents and contributors use AGENTS.md as the primary codebase map. The stale tree causes agents to miss `replay/`, `explore.ts`, `dashboard/revisions`, `dashboard/restore`, and `issue/archive` commands.
+
+### 2. Add Missing Environment Variables to Registry
+**Impact: Medium** — `SENTRY_INIT_TUI` is useful for CI/Docker users running `sentry init` non-interactively. Adding it to `env-registry.ts` ensures it appears in the generated `configuration.md`.
+
+### 3. Add `yarn` and Missing Run-Without-Installing Methods to README.md
+**Impact: Medium** — The README is the most-viewed surface. Missing `yarn` as an install method and missing `pnpm dlx`/`bunx`/`yarn dlx` as run-without-installing options creates a gap for users of those package managers.
+
+### 4. Document Installer Flags in getting-started.mdx
+**Impact: Medium** — `--no-modify-path`, `--no-completions`, `--no-agent-skills` are important for CI/Docker setups. Documenting them in the getting-started page helps DevOps users.
+
+### 5. Add `dashboard revisions`/`restore` and `--refresh` Examples to Fragments
+**Impact: Low-Medium** — These are newer features without example coverage in the hand-written fragments. Users discovering them rely on `--help` only.
diff --git a/docs/src/content/docs/agentic-usage.md b/docs/src/content/docs/agentic-usage.md
@@ -9,6 +9,10 @@ AI coding agents like Claude Code — and any agent that reads skills from `~/.a
 
 When you install the CLI (via `curl`, Homebrew, or a package manager), `sentry cli setup` automatically installs agent skills into any detected agent root directories (`~/.claude`, `~/.agents`). Skills are also refreshed on `sentry cli upgrade`. No network fetch is needed — skill files are embedded in the binary.
 
+:::note
+Automatic installation only runs if `~/.claude` or `~/.agents` already exists on your system. The installer does not create these directories — they are created by the respective AI agent tools (Claude Code, etc.) when you first set them up.
+:::
+
 To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli setup`.
 
 ## Manual Installation

diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx
@@ -36,6 +36,39 @@ The `--version` flag takes precedence over `SENTRY_VERSION` if both are set.
 The chosen channel is persisted so that `sentry cli upgrade` automatically
 tracks the same channel on future updates.
 
+#### Installer Options
+
+The install script accepts these flags (pass them after `--` in the `bash -s` invocation):
+
+```bash
+# Skip modifying shell profile (PATH)
+curl https://cli.sentry.dev/install -fsS | bash -s -- --no-modify-path
+
+# Skip shell completion installation
+curl https://cli.sentry.dev/install -fsS | bash -s -- --no-completions
+
+# Skip agent skill installation (Claude Code, Cursor, etc.)
+curl https://cli.sentry.dev/install -fsS | bash -s -- --no-agent-skills
+
+# Combine multiple flags
+curl https://cli.sentry.dev/install -fsS | bash -s -- --no-modify-path --no-completions
+```
+
+| Flag | Description |
+|------|-------------|
+| `--version <version>` | Install a specific version or `nightly` |
+| `--no-modify-path` | Don't add the install directory to your shell's PATH |
+| `--no-completions` | Don't install shell completions |
+| `--no-agent-skills` | Don't install AI agent skills |
+
+These environment variables are also supported:
+
+| Variable | Description |
+|----------|-------------|
+| `SENTRY_VERSION` | Pin a version (same as `--version`) |
+| `SENTRY_INSTALL_DIR` | Override the binary install directory |
+| `SENTRY_INIT` | Set to `1` to run `sentry init` after installation |
+
 #### Supported Platforms
 
 {/* GENERATED:START platform-support */}

diff --git a/docs/src/fragments/commands/dashboard.md b/docs/src/fragments/commands/dashboard.md
@@ -108,6 +108,26 @@ sentry dashboard widget delete 'My Dashboard' --title 'Error Count'
 sentry dashboard widget delete 12345 --index 2
 ```
 
+### View revision history
+
+```bash
+# List revisions for a dashboard
+sentry dashboard revisions 'Frontend Performance'
+
+# With explicit org
+sentry dashboard revisions my-org/ 12345
+```
+
+### Restore a previous revision
+
+```bash
+# Restore a specific revision
+sentry dashboard restore 'Frontend Performance' --revision 3
+
+# With explicit org/dashboard ID
+sentry dashboard restore my-org/ 12345 --revision 1
+```
+
 ## Query Shorthand
 
 The `--query` flag supports shorthand for aggregate functions:

diff --git a/docs/src/fragments/configuration.md b/docs/src/fragments/configuration.md
@@ -68,6 +68,8 @@ sentry cli defaults org my-org           # Set default organization
 sentry cli defaults project my-project   # Set default project
 sentry cli defaults url https://...      # Set Sentry URL (self-hosted)
 sentry cli defaults telemetry off        # Disable telemetry
+sentry cli defaults headers "X-IAP: token"  # Set custom HTTP headers (self-hosted)
+sentry cli defaults ca-cert /path/to.pem # Set custom CA certificate (self-hosted)
 sentry cli defaults                      # Show all current defaults
 sentry cli defaults org --clear          # Clear a specific default
 ```

diff --git a/plugins/sentry-cli/skills/sentry-cli/references/dashboard.md b/plugins/sentry-cli/skills/sentry-cli/references/dashboard.md
@@ -175,11 +175,31 @@ List dashboard revisions
 - `-n, --limit <value> - Maximum number of revisions to list - (default: "25")`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
+**Examples:**
+
+```bash
+# List revisions for a dashboard
+sentry dashboard revisions 'Frontend Performance'
+
+# 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:**
+
+```bash
+# Restore a specific revision
+sentry dashboard restore 'Frontend Performance' --revision 3
+
+# With explicit org/dashboard ID
+sentry dashboard restore my-org/ 12345 --revision 1
+```
+
 All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.