Skip to content

Commit e926ac8

Browse files
cursoragentbetegon
cursoragent
and
betegon
committed
docs: fix documentation gaps found in audit
- Add missing commands to README table (release, repo, team, trial) - Add yarn to README package manager examples - Add Node.js >=22 note for npm users - Fix OAuth scope lists: add missing team:write in DEVELOPMENT.md and self-hosted.md - Add undocumented env vars to configuration.md (SENTRY_FORCE_ENV_TOKEN, SENTRY_OUTPUT_FORMAT, SENTRY_MAX_PAGINATION_PAGES, SENTRY_INIT) - Update contributing.md project structure to reflect all 15+ command directories - Add Cursor support to agentic-usage.md alongside Claude Code - Document installer flags and SENTRY_INIT in getting-started.mdx - Add DOCUMENTATION_AUDIT.md with full gap report Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
1 parent 29b8eba commit e926ac8

8 files changed

Lines changed: 346 additions & 16 deletions

File tree

‎DEVELOPMENT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ When creating your Sentry OAuth application:
6363
- `org:read`
6464
- `event:read`, `event:write`
6565
- `member:read`
66-
- `team:read`
66+
- `team:read`, `team:write`
6767

6868
## Environment Variables
6969

‎DOCUMENTATION_AUDIT.md‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# Sentry CLI Documentation Audit Report
2+
3+
**Date:** 2026-04-13
4+
**Scope:** Cross-reference of code implementation against all documentation surfaces
5+
6+
---
7+
8+
## A. Undocumented or Missing Commands/Subcommands
9+
10+
Command doc pages under `docs/src/content/docs/commands/` are **auto-generated** by `bun run generate:docs` and are **gitignored**, so they are not present in the repo at rest. The hand-written fragments in `docs/src/fragments/commands/` cover all top-level route groups. However, several commands are absent or under-represented in the **root README.md** commands table:
11+
12+
| Command | In code (`src/commands/`) | In README table | In fragments |
13+
|---------|--------------------------|-----------------|-------------|
14+
| `sentry release` (list, view, create, finalize, delete, deploy, deploys, set-commits, propose-version) | Yes | **Missing** | Yes (`release.md`) |
15+
| `sentry repo list` | Yes | **Missing** | Yes (`repo.md`) |
16+
| `sentry team list` | Yes | **Missing** | Yes (`team.md`) |
17+
| `sentry trial` (list, start) | Yes | **Missing from table** | Yes (`trial.md`) |
18+
| `sentry whoami` (top-level alias) | Yes | **Missing** | Covered in `auth.md` |
19+
| `sentry issue events` / `sentry event list` | Yes | **Missing** (only `event view` noted) | Partially in `issue.md` |
20+
| `sentry release deploys` | Yes | **Missing** | Not in `release.md` fragment |
21+
| `sentry dashboard widget` (add, edit, delete) | Yes | Mentioned as "create dashboards with widgets" | Yes (`dashboard.md`) |
22+
23+
**Source files:** `src/app.ts` (route map), `README.md` (lines 69–87)
24+
25+
### Recommendation
26+
Add `sentry release`, `sentry repo`, `sentry team`, and `sentry trial` to the README commands table. Add `sentry whoami` as a note. Mention `issue events` / `event list` in the event command description.
27+
28+
---
29+
30+
## B. Undocumented Flags
31+
32+
The following **non-hidden** flags are defined in code but not mentioned in the corresponding hand-written fragment files. (Auto-generated doc pages would include them, but they are not checked into the repo.)
33+
34+
| Command | Flag | Fragment coverage |
35+
|---------|------|-------------------|
36+
| `sentry auth login` | `--timeout` (default 900) | Not mentioned in `auth.md` |
37+
| `sentry auth login` | `--force` | Not mentioned in `auth.md` |
38+
| `sentry auth status` | `--fresh` | Not mentioned in `auth.md` |
39+
| `sentry auth whoami` | `--fresh` | Not mentioned in `auth.md` |
40+
| `sentry issue view` | `--spans` (span tree depth) | Not mentioned in `issue.md` |
41+
| `sentry issue view` | `--fresh` | Not mentioned in `issue.md` |
42+
| `sentry issue explain` | `--fresh` | Not mentioned in `issue.md` |
43+
| `sentry issue plan` | `--fresh` | Not mentioned in `issue.md` |
44+
| `sentry event view` | `--spans` | Not mentioned in `event.md` |
45+
| `sentry event view` | `--fresh` | Not mentioned in `event.md` |
46+
| `sentry trace view` | `--spans` | Not mentioned in `trace.md` |
47+
| `sentry trace view` | `--fresh` | Not mentioned in `trace.md` |
48+
| `sentry trace logs` | `--fresh` | Not mentioned in `trace.md` |
49+
| `sentry log view` | `--fresh` | Not mentioned in `log.md` |
50+
| `sentry span view` | `--spans`, `--fresh` | Not mentioned in `span.md` |
51+
| `sentry dashboard view` | `--fresh`, `--period` | Not mentioned in `dashboard.md` |
52+
| `sentry release list` | `--environment`, `--period`, `--status` | Not mentioned in `release.md` |
53+
| `sentry release create` | `--ref`, `--url` | Not mentioned in `release.md` |
54+
| `sentry release finalize` | `--released`, `--url` | Not mentioned in `release.md` |
55+
| `sentry release deploy` | `--url`, `--started`, `--finished`, `--time` | Not mentioned in `release.md` |
56+
| `sentry release set-commits` | `--clear`, `--commit`, `--initial-depth` | Not mentioned in `release.md` |
57+
| All list commands | `--fresh` (cache bypass) | Rarely mentioned in fragments |
58+
| All list commands | `--cursor` / `-c` | Mentioned in some fragments (repo, team, span, trace) but not all |
59+
| `sentry sourcemap upload` | `--url-prefix` default is `~/` | Default not documented |
60+
61+
**Source files:** `src/commands/*/` (flag definitions), `docs/src/fragments/commands/` (fragments)
62+
63+
### Recommendation
64+
The auto-generated docs cover these, but fragments should mention important flags like `--spans`, `--fresh`, `--timeout`, and release subcommand flags for discoverability. At minimum, add `--fresh` to the global options section in `docs/src/fragments/commands/index.md`.
65+
66+
---
67+
68+
## C. Missing Usage Examples
69+
70+
All 19 fragment files contain bash examples. This section is **clear** — no command fragment lacks examples entirely. However:
71+
72+
- `sentry release deploys` (list deploys) has no example in `release.md`
73+
- `sentry issue events` / `sentry event list` has no standalone example
74+
- `sentry auth refresh` has only a brief mention, no full example showing the output
75+
76+
---
77+
78+
## D. Stale Descriptions
79+
80+
| Location | Doc description | Code `brief` | Drift? |
81+
|----------|----------------|--------------|--------|
82+
| README: `sentry cli` | "Upgrade, setup, fix, and send feedback" | Routes: upgrade, feedback, fix, setup | Minor: matches |
83+
| README: `sentry event` | "View event details" | Route has `view` + `list` | **Yes**: `event list` exists but README only says "view" |
84+
| README: `sentry project` | "List, view, create, and delete projects" | Matches | OK |
85+
| README: `sentry log` | "List and view logs (with streaming)" | Matches | OK |
86+
87+
**Other observations:**
88+
- `DEVELOPMENT.md` lists OAuth scopes as: `project:read`, `project:write`, `project:admin`, `org:read`, `event:read`, `event:write`, `member:read`, `team:read` — **missing `team:write`** which is in the actual code (`src/lib/oauth.ts`).
89+
- `docs/src/content/docs/self-hosted.md` lists token scopes without `team:write`.
90+
91+
**Source files:** `src/lib/oauth.ts` (line 52–63), `DEVELOPMENT.md` (line 61–67), `self-hosted.md` (line 47)
92+
93+
---
94+
95+
## E. Missing Route Mappings in Skill Generator
96+
97+
The current `script/generate-skill.ts` uses **automatic 1:1 mapping** — every visible route gets its own reference file. There is no manual `ROUTE_TO_REFERENCE` map to go stale. This section is **clear**.
98+
99+
---
100+
101+
## F. Installation / Distribution Gaps
102+
103+
### README.md gaps
104+
105+
| Feature | In code | In README | Gap |
106+
|---------|---------|-----------|-----|
107+
| `yarn` as install method | Yes (getting-started.mdx, upgrade.ts) | **Missing** from package manager examples | Yes |
108+
| `npx` / `pnpm dlx` / `bunx` / `yarn dlx` | Yes (getting-started.mdx) | Only `npx` shown | Minor |
109+
| Nightly builds | Yes (install script `--version nightly`) | **Not mentioned** | Yes |
110+
| `SENTRY_VERSION` env var for install | Yes (install script) | **Not mentioned** | Yes |
111+
| `SENTRY_INIT=1` env var | Yes (install script) | **Not mentioned** anywhere in docs | Yes |
112+
| `SENTRY_INSTALL_DIR` | Yes (binary.ts, install script) | **Not mentioned** in README | Documented in configuration.md |
113+
| `--no-modify-path` / `--no-completions` installer flags | Yes (install script) | **Not mentioned** | Yes |
114+
| Node.js >=22 requirement | Yes (`package.json` engines) | **Not mentioned** in README install section | Only in library-usage.md |
115+
| Supported platforms (darwin/linux/windows, arm64/x64) | Yes (install script) | **Not mentioned** | Yes |
116+
117+
### getting-started.mdx gaps
118+
119+
| Feature | In code | In getting-started.mdx | Gap |
120+
|---------|---------|----------------------|-----|
121+
| `SENTRY_INIT=1` env var | Yes (install script) | **Missing** | Yes |
122+
| `--no-modify-path` / `--no-completions` installer flags | Yes (install script) | **Missing** | Yes |
123+
| Supported platforms/architectures | Yes | **Missing** | Yes |
124+
| Windows support notes (x64 only) | Yes (install script) | **Missing** | Yes |
125+
126+
**Source files:** `install` (bash script), `README.md`, `docs/src/content/docs/getting-started.mdx`
127+
128+
---
129+
130+
## G. Undocumented Environment Variables
131+
132+
The following `SENTRY_*` variables are used in `src/` but **absent** from `docs/src/content/docs/configuration.md`:
133+
134+
| Variable | Usage in code | Documented? |
135+
|----------|---------------|-------------|
136+
| `SENTRY_FORCE_ENV_TOKEN` | Forces env token over stored OAuth | **No** |
137+
| `SENTRY_OUTPUT_FORMAT` | Library mode: `"json"` forces JSON output | **No** |
138+
| `SENTRY_MAX_PAGINATION_PAGES` | Caps pagination loops (default 50) | **No** |
139+
| `SENTRY_CLI_NO_AUTO_REPAIR` | Disables DB auto-repair | **No** |
140+
| `SENTRY_INIT` | Install script: runs `sentry init` after install | **No** (not in configuration.md or getting-started.mdx) |
141+
142+
All other `SENTRY_*` variables (`SENTRY_AUTH_TOKEN`, `SENTRY_TOKEN`, `SENTRY_HOST`, `SENTRY_URL`, `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_DSN`, `SENTRY_CLIENT_ID`, `SENTRY_CONFIG_DIR`, `SENTRY_VERSION`, `SENTRY_PLAIN_OUTPUT`, `SENTRY_CLI_NO_TELEMETRY`, `SENTRY_LOG_LEVEL`, `SENTRY_CLI_NO_UPDATE_CHECK`, `SENTRY_INSTALL_DIR`, `SENTRY_NO_CACHE`, `NO_COLOR`) are documented.
143+
144+
**Source files:** `src/lib/db/auth.ts`, `src/lib/command.ts`, `src/lib/db/pagination.ts`, `src/lib/db/schema.ts`, `install`
145+
146+
---
147+
148+
## H. Auth / Self-Hosted Gaps
149+
150+
### OAuth scopes mismatch
151+
152+
| Source | Scopes listed |
153+
|--------|---------------|
154+
| Code (`src/lib/oauth.ts`) | `project:read`, `project:write`, `project:admin`, `org:read`, `event:read`, `event:write`, `member:read`, `team:read`, **`team:write`** |
155+
| `DEVELOPMENT.md` | Missing `team:write` |
156+
| `self-hosted.md` | Missing `team:write` |
157+
158+
### Token storage description
159+
160+
- `getting-started.mdx` correctly says "SQLite database at `~/.sentry/`"
161+
- `configuration.md` correctly describes `cli.db` with WAL side-files and mode 600
162+
- **Gap:** Neither doc mentions the `.sentryclirc` **legacy file** fallback for token (`[auth] token`), though `configuration.md` documents the `[defaults]` section. The `[auth]` section is documented but the **precedence** between SQLite-stored OAuth token and `.sentryclirc` token is not explicitly spelled out.
163+
164+
### Self-hosted gaps
165+
166+
- `self-hosted.md` says "Sentry 26.1.0+" for OAuth but the version requirement is not independently verified in the install/upgrade code — it's a documentation-only claim, which is fine.
167+
- The page correctly documents `SENTRY_HOST` + `SENTRY_CLIENT_ID`.
168+
- **Gap:** No mention of the `SENTRY_FORCE_ENV_TOKEN` variable which is relevant for self-hosted users who want env tokens to take priority over stored OAuth.
169+
170+
**Source files:** `src/lib/oauth.ts`, `src/lib/db/auth.ts`, `DEVELOPMENT.md`, `self-hosted.md`
171+
172+
---
173+
174+
## I. Plugin/Skills Gaps
175+
176+
### Supported IDEs
177+
178+
| IDE/Agent | In code/plugins | In `agentic-usage.md` | In `plugins/README.md` |
179+
|-----------|----------------|----------------------|----------------------|
180+
| Claude Code | Yes (skill install targets `~/.claude/`) | Mentioned as example | Yes (full install instructions) |
181+
| Cursor | Yes (`.cursor/skills/` symlink in repo) | **Not mentioned** | Yes ("automatically available") |
182+
| Other agents | Yes (generic copy instructions) | **Not mentioned** | Yes (generic instructions) |
183+
184+
### Agentic usage page gaps
185+
186+
- `agentic-usage.md` only mentions "Claude Code" and a generic "AI coding agents" — **Cursor is not mentioned** despite having first-class support via `.cursor/skills/`.
187+
- The skill installation command shown (`npx skills add https://cli.sentry.dev`) may not match the current plugin installation method (`claude plugin install sentry/cli` in `plugins/README.md`). These appear to be two different systems.
188+
- **Gap:** No mention of `sentry cli setup --no-agent-skills` flag to control skill installation.
189+
- **Gap:** No mention that skills are **embedded at build time** (not fetched from network), which is a meaningful detail for offline/air-gapped environments.
190+
191+
### plugins/README.md accuracy
192+
193+
- Generally accurate and well-structured.
194+
- **Gap:** Does not mention that `sentry cli setup` automatically installs skills (only discusses manual plugin installation).
195+
196+
**Source files:** `src/lib/agent-skills.ts`, `src/commands/cli/setup.ts`, `plugins/README.md`, `docs/src/content/docs/agentic-usage.md`
197+
198+
---
199+
200+
## J. README / DEVELOPMENT.md Drift
201+
202+
### DEVELOPMENT.md
203+
204+
| Claim | Code reality | Drift? |
205+
|-------|-------------|--------|
206+
| OAuth scopes missing `team:write` | Code has `team:write` | **Yes** |
207+
| Environment variables table lists only `SENTRY_CLIENT_ID`, `SENTRY_HOST`, `SENTRY_URL` | Many more variables exist | **Yes** — incomplete but not wrong |
208+
| "No client secret is needed" for device flow | Correct | OK |
209+
| "Install dependencies: `bun install`" | Correct | OK |
210+
211+
### README.md
212+
213+
| Claim | Code reality | Drift? |
214+
|-------|-------------|--------|
215+
| "Bun v1.0+" in prerequisites | `packageManager: bun@1.3.11` in package.json | **Minor** — works with v1.0 but repo pins 1.3.11 |
216+
| Commands table missing `release`, `repo`, `team`, `trial`, `whoami` | All exist in code | **Yes** |
217+
| `sentry event` described as only "View event details" | Also has `event list` | **Yes** |
218+
| No mention of Node.js >=22 for npm users | `engines.node: ">=22"` | **Yes** |
219+
| Library usage shows `signal` as `AbortSignal` to cancel streaming | Correct per `sdk-types.ts` | OK |
220+
| No `yarn` in package manager examples | Supported in getting-started.mdx and code | **Minor** |
221+
222+
### contributing.md
223+
224+
| Claim | Code reality | Drift? |
225+
|-------|-------------|--------|
226+
| Project structure lists only `auth/`, `org/`, `project/`, `issue/`, `event/` under commands | Many more directories exist (trace, span, log, dashboard, cli, release, sourcemap, schema, trial, repo, team, init, api, help) | **Yes** — significantly outdated |
227+
| No mention of `bun run typecheck` | Exists in package.json | **Minor** (it's in the Code Style section) |
228+
229+
**Source files:** `README.md`, `DEVELOPMENT.md`, `docs/src/content/docs/contributing.md`, `package.json`
230+
231+
---
232+
233+
## Top 5 Most Impactful Fixes (Prioritized)
234+
235+
### 1. Add missing commands to README.md commands table
236+
**Impact: High** — The README is the first thing users see. Missing `release`, `repo`, `team`, `trial`, and `whoami` makes the CLI appear less capable than it is. Also update `event` description to include `list`.
237+
238+
### 2. Fix OAuth scope lists (`team:write` missing)
239+
**Impact: High** — `DEVELOPMENT.md` and `self-hosted.md` list OAuth scopes that self-hosted admins copy when creating OAuth apps. Missing `team:write` causes permission errors for team management features.
240+
241+
### 3. Document missing environment variables in configuration.md
242+
**Impact: Medium-High** — `SENTRY_FORCE_ENV_TOKEN`, `SENTRY_OUTPUT_FORMAT`, `SENTRY_MAX_PAGINATION_PAGES`, `SENTRY_CLI_NO_AUTO_REPAIR`, and `SENTRY_INIT` are used in code but absent from the configuration reference. `SENTRY_INIT` is especially useful for CI/CD pipelines.
243+
244+
### 4. Update contributing.md project structure
245+
**Impact: Medium** — The project structure in `contributing.md` lists only 5 command directories when 15+ exist. This misleads new contributors about the codebase scope.
246+
247+
### 5. Add Cursor to agentic-usage.md and document installer flags
248+
**Impact: Medium** — Cursor has first-class skill support but isn't mentioned in the agentic usage docs. The install script accepts `--no-modify-path`, `--no-completions`, and `SENTRY_INIT=1` that are useful for CI but undocumented in getting-started.mdx.

‎README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,12 @@ brew install getsentry/tools/sentry
3333
```bash
3434
npm install -g sentry
3535
pnpm add -g sentry
36+
yarn global add sentry
3637
bun add -g sentry
3738
```
3839

40+
> **Note:** The npm package requires Node.js ≥22.
41+
3942
### Run Without Installing
4043

4144
```bash
@@ -74,12 +77,16 @@ sentry issue plan PROJ-ABC
7477
| `sentry org` | List and view organizations |
7578
| `sentry project` | List, view, create, and delete projects |
7679
| `sentry issue` | List, view, explain, and plan issues |
77-
| `sentry event` | View event details |
80+
| `sentry event` | List and view event details |
7881
| `sentry trace` | List and view distributed traces |
7982
| `sentry span` | List and view spans |
8083
| `sentry log` | List and view logs (with streaming) |
84+
| `sentry release` | Create, finalize, deploy, and manage releases |
8185
| `sentry dashboard` | List, view, and create dashboards with widgets |
8286
| `sentry sourcemap` | Inject debug IDs and upload sourcemaps |
87+
| `sentry team` | List teams in an organization |
88+
| `sentry repo` | List repositories in an organization |
89+
| `sentry trial` | List and start product trials |
8390
| `sentry init` | Initialize Sentry in your project |
8491
| `sentry schema` | Browse the Sentry API schema |
8592
| `sentry api` | Make direct API requests |

‎docs/src/content/docs/agentic-usage.md‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,30 @@ title: Agentic Usage
33
description: Enable AI coding agents to use the Sentry CLI
44
---
55

6-
AI coding agents like Claude Code can use the Sentry CLI through the skill system. This allows agents to interact with Sentry directly from your development environment.
6+
AI coding agents like Claude Code and Cursor can use the Sentry CLI through the skill system. This allows agents to interact with Sentry directly from your development environment.
77

88
## Adding the Skill
99

10-
Add the Sentry CLI skill to your agent:
10+
### Claude Code
11+
12+
Install the Sentry CLI plugin:
1113

1214
```bash
13-
npx skills add https://cli.sentry.dev
15+
claude plugin marketplace add getsentry/cli
16+
claude plugin install sentry/cli
1417
```
1518

16-
This registers the Sentry CLI as a skill that your agent can invoke when needed.
19+
### Cursor
20+
21+
Skills are automatically available for Cursor users. The CLI ships with a `.cursor/skills/` directory that Cursor picks up when the repo is opened. Running `sentry cli setup` also installs skills to the local config.
22+
23+
### Other Agents
24+
25+
Copy the `plugins/sentry-cli/skills/` directory to your agent's skills location, or reference the SKILL.md files directly according to your agent's documentation.
26+
27+
### Automatic Installation
28+
29+
Running `sentry cli setup` installs agent skills automatically. Use `--no-agent-skills` to skip this step.
1730

1831
## Capabilities
1932

@@ -43,4 +56,4 @@ The skill uses your existing CLI authentication, so you'll need to run `sentry a
4356
## Requirements
4457

4558
- An authenticated Sentry CLI installation (`sentry auth login`)
46-
- An AI coding agent that supports the skills system (e.g., Claude Code)
59+
- An AI coding agent that supports skills (e.g., Claude Code, Cursor)

‎docs/src/content/docs/configuration.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,38 @@ Disable API response caching. When set, the CLI will not cache API responses and
213213
export SENTRY_NO_CACHE=1
214214
```
215215

216+
### `SENTRY_FORCE_ENV_TOKEN`
217+
218+
When set, environment variable tokens (`SENTRY_AUTH_TOKEN` / `SENTRY_TOKEN`) take precedence over the stored OAuth token from `sentry auth login`. Useful for self-hosted setups or CI environments where you want to ensure the env token is always used.
219+
220+
```bash
221+
export SENTRY_FORCE_ENV_TOKEN=1
222+
```
223+
224+
### `SENTRY_OUTPUT_FORMAT`
225+
226+
Force the output format for all commands. Currently only `json` is supported. This is primarily used by the library API (`createSentrySDK()`) to get JSON output without passing `--json` flags.
227+
228+
```bash
229+
export SENTRY_OUTPUT_FORMAT=json
230+
```
231+
232+
### `SENTRY_MAX_PAGINATION_PAGES`
233+
234+
Cap the maximum number of pages fetched during auto-pagination. Defaults to 50. Useful for limiting API calls when using large `--limit` values.
235+
236+
```bash
237+
export SENTRY_MAX_PAGINATION_PAGES=10
238+
```
239+
240+
### `SENTRY_INIT`
241+
242+
Used with the install script. When set to `1`, the installer runs `sentry init` after installing the binary to guide you through project setup.
243+
244+
```bash
245+
SENTRY_INIT=1 curl https://cli.sentry.dev/install -fsS | bash
246+
```
247+
216248
## Global Options
217249

218250
These flags are accepted by every command. They are not shown in individual command `--help` output, but are always available.

0 commit comments

Comments
 (0)