[cursor]

Documentation Audit Report

This PR fixes the most impactful documentation issues found during a comprehensive audit of the Sentry CLI codebase. Below are the changes made, followed by a full gap report for items that remain open.

---

Changes in this PR

1. AGENTS.md: Fix toolchain drift (bun → pnpm, bun:test → vitest)

AGENTS.md referenced bun as the package manager and bun:test as the test runner throughout, but the project actually uses pnpm@10.11.0 and vitest@4.1.9. This causes AI agents to run incorrect commands (e.g. bun install instead of pnpm install) and import from a non-existent bun:test module.

Fixed:

• Quick Reference commands: bun install → pnpm install, bun run → pnpm run, etc.
• Testing section header: bun:test + fast-check → vitest + fast-check
• All code examples: import from 'bun:test' → import from 'vitest'
• mock.module() → vi.mock() (vitest API)
• bun add -d → pnpm add -D
• BUN_TEST_WORKER_ID → VITEST_POOL_ID
• CI check commands: bun run check:* → pnpm run check:*

2. .craft.yml: Fix Homebrew formula license

The brew formula template used FSL-1.1-MIT but the actual license (LICENSE.md, package.json, README.md) is FSL-1.1-Apache-2.0.

3. Proguard fragment: Add missing upload examples

The proguard command fragment only had bash examples for proguard uuid but none for proguard upload, leaving a gap in the generated command docs.

4. README.md: Clarify credential storage

README only said credentials were "stored in ~/.sentry/" — clarified that it uses a SQLite database (cli.db) and mentioned the SENTRY_CONFIG_DIR override, matching the docs site.

5. agentic-usage.md: Mention OpenCode

OpenCode is referenced in agent-skills.ts code comments and detected via detect-agent.ts, but was missing from the agentic usage documentation.

---

Full Gap Report

A. Undocumented or Missing Commands/Subcommands

All visible commands in src/commands/ have corresponding fragments in docs/src/fragments/commands/. The generated docs system ensures 1:1 coverage. No gaps found. Hidden commands (bash-hook, send-event, send-envelope) are intentionally undocumented.

B. Undocumented Flags

All non-hidden flags in command definitions are auto-generated into the command docs. Global hidden flags (--verbose, --log-level, --org, --project) are documented in the global options section. No significant gaps found — the auto-generation system keeps flags in sync.

C. Missing Usage Examples

Command	Status	Source file	Notes
sentry proguard upload	Fixed in this PR	docs/src/fragments/commands/proguard.md	Had uuid examples but no upload examples

All other ~119 subcommands have bash examples in their fragments.

D. Stale Descriptions

Command brief strings are auto-generated from code into docs. The generator uses live CLI introspection, so descriptions cannot drift. No gaps found.

E. Missing Route Mappings in Skill Generator

The ROUTE_TO_REFERENCE map was removed in a previous refactor. The skill generator now uses automatic 1:1 route-to-file mapping via groupRoutesByReference(), so no manual maintenance is needed. No gaps found.

F. Installation / Distribution Gaps

Finding	Severity	Files
Homebrew formula license mismatch	High	.craft.yml uses FSL-1.1-MIT, should be FSL-1.1-Apache-2.0 — Fixed in this PR
index.mdx InstallSelector omits yarn	Low	docs/src/content/docs/index.mdx — README and getting-started include yarn global add but the landing page install selector doesn't
Two install URLs coexist	Info	install script uses cli.sentry.dev/install; upgrade error hint mentions sentry.io/get-cli/ — both work but inconsistency
Example pinned version 0.19.0 in getting-started	Low	docs/src/content/docs/getting-started.mdx — version will keep drifting; consider using a placeholder

G. Undocumented Environment Variables

The following SENTRY_* env vars are used in src/ but absent from env-registry.ts (and thus from the generated configuration.md):

Variable	Where used	Notes
SENTRY_TRACES_SAMPLE_RATE	local/run.ts, init/verify-setup.ts	Passed to child processes
SENTRY_ENVIRONMENT	bash-hook/traceback.ts	Event metadata
SENTRY_DIST	React Native xcode	Release resolution
SENTRY_PIPELINE	build/upload.ts	Build plugin detection
SENTRY_SPOTLIGHT	local/run.ts, init/verify-setup.ts	Set/injected for Spotlight
SENTRY_MONITOR_SLUG	monitor/run.ts	Set for wrapped command
SENTRY_SCAN_DISABLE_WORKERS	scan/grep.ts	Disables worker threads
SENTRY_CLI_NO_EXIT_TRAP	bash-hook template	Controls trap behavior
SENTRY_RN_* (5 vars)	React Native wrap-call/xcode	Internal RN build vars
Framework-prefixed DSN vars	dsn/env.ts	NEXT_PUBLIC_SENTRY_DSN, etc.
Framework-prefixed Spotlight vars	local/run.ts	NEXT_PUBLIC_SENTRY_SPOTLIGHT, etc.

Most of these are internal/pass-through vars, not user-facing config. The React Native SENTRY_RN_* vars and SENTRY_PIPELINE are the most notable omissions for users integrating with build systems.

H. Auth / Self-Hosted Gaps

Finding	Severity	Files
OAuth scope --scope validation against SENTRY_SCOPES (broader than default OAUTH_SCOPES) not documented	Low	src/lib/oauth.ts vs docs/src/content/docs/self-hosted.md
Token refresh threshold (10% lifetime remaining) not documented	Info	src/lib/db/auth.ts
Host-scoped tokens (schema v16) behavior not documented in user docs	Low	src/lib/db/auth.ts
.sentryclirc URL poison prevention (--url trust anchor) documented in self-hosted.md ✓	—	No gap

The auth system is well-documented for common flows. The gaps are in advanced/edge-case behaviors.

I. Plugin/Skills Gaps

Finding	Severity	Files
OpenCode not mentioned in agentic-usage.md	Medium	Fixed in this PR
OpenCode not mentioned in plugins/README.md	Low	plugins/README.md
~/.agents is described as a Cursor path in agentic-usage.md, but it's the shared Agent Skills root (not Cursor-specific)	Low	docs/src/content/docs/agentic-usage.md
Skills are described as embedded in binary (correct) but install mechanism details (atomic writes, writable check) not documented	Info	Implementation detail, not user-facing

J. README / DEVELOPMENT.md Drift

Finding	Severity	Files
AGENTS.md uses bun everywhere; project uses pnpm	Critical	Fixed in this PR
AGENTS.md references bun:test; project uses vitest	Critical	Fixed in this PR
README credential storage vague	Medium	Fixed in this PR
DEVELOPMENT.md env vars table is auto-generated from env-registry.ts — stays in sync ✓	—	No gap
README dev prerequisites block is auto-generated — stays in sync ✓	—	No gap
plugins/README.md uses pnpm run generate:docs (correct)	—	No gap

---

Top 5 Most Impactful Fixes (Prioritized)

1. AGENTS.md toolchain drift (fixed) — Every AI agent working on this codebase was getting incorrect commands. This affected bun install, bun test, bun:test imports, and bun add -d across the entire file.

2. Homebrew formula license mismatch (fixed) — The brew formula shipped FSL-1.1-MIT to every Homebrew user, but the actual license is FSL-1.1-Apache-2.0. This is a legal/compliance issue.

3. Undocumented SENTRY_ env vars* (reported, not fixed) — ~15 env vars used in source are absent from the env registry. Most impactful are SENTRY_PIPELINE, SENTRY_DIST, and SENTRY_ENVIRONMENT which CI/build users may need.

4. Proguard upload examples (fixed) — The only command with zero bash examples for its primary subcommand (upload).

5. README credential storage (fixed) — Users looking at the README had no idea credentials used SQLite or that SENTRY_CONFIG_DIR could override the path.

  

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-1199/
Built to branch gh-pages at 2026-07-06 12:18 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[sentry-junior]

Closing as part of archiving getsentry/cli; the CLI now lives in getsentry/toolkit. Stale docs audit from July. Later audits (#1540, #1602, getsentry/toolkit#1541, #1542) cover this ground, and toolkit's scheduled docs audit keeps running.