docs: documentation audit — fix gaps between implementation and docs

[cursor]

Documentation Audit Report

This PR fixes the most impactful gaps found during a comprehensive audit of the Sentry CLI codebase vs. its documentation. The full gap report follows.

Changes Made

• agentic-usage.md: Fixed incorrect claim that npm/pnpm/bun installs automatically run sentry cli setup for agent skills. npm has no postinstall hook — users must run sentry cli setup manually.
• proguard.md fragment: Added missing sentry proguard upload subcommand examples and notes (only uuid was documented).
• library-usage.md: Fixed auth token priority to match actual implementation. Was listed as env token > stored OAuth; actual default is stored OAuth > env token.
• auth.md fragment: Added undocumented --read-only and --scope flags for sentry auth login. Updated self-hosted example to use --url flag (recommended over bare env var).
• getting-started.mdx: Added --url flag for self-hosted login, mentioned SENTRY_HOST alongside SENTRY_URL.

---

Full Gap Report

A. Undocumented or Missing Commands/Subcommands

Command	Source	Missing From
sentry proguard upload	src/commands/proguard/upload.ts	docs/src/fragments/commands/proguard.md — fixed in this PR

All other visible commands have corresponding fragment files. Hidden backward-compat aliases (sentry issues, sentry orgs, sentry sourcemaps, sentry whoami, sentry send-event, sentry send-envelope, sentry bash-hook) are intentionally excluded from docs.

B. Undocumented Flags

Command	Flag	Source	Doc File
sentry auth login	--read-only	src/commands/auth/login.ts	auth.md fragment — fixed in this PR
sentry auth login	--scope	src/commands/auth/login.ts	auth.md fragment — fixed in this PR
sentry auth login	--url	src/commands/auth/login.ts	auth.md fragment — fixed in this PR
sentry auth login	--timeout, --force	src/commands/auth/login.ts	auth.md fragment
sentry auth refresh	--read-only, --scope, --force	src/commands/auth/refresh.ts	auth.md fragment
sentry init	--app, --tui	src/commands/init.ts	init.md fragment
sentry local serve	--host, --attributes	src/commands/local/server.ts	local.md fragment
sentry local run	--host, --verify, --timeout	src/commands/local/run.ts	local.md fragment
sentry monitor run	--check-in-margin, --failure-issue-threshold, --recovery-threshold	src/commands/monitor/run.ts	monitor.md fragment
sentry sourcemap inject	--ignore, --ignore-file	src/commands/sourcemap/inject.ts	sourcemap.md fragment
sentry sourcemap upload	--dist, --ignore, --ignore-file, --strip-prefix, --strip-common-prefix, --no-rewrite	src/commands/sourcemap/upload.ts	sourcemap.md fragment
sentry explore	--environment	src/commands/explore.ts	explore.md fragment
sentry issue list	--period, --compact	src/commands/issue/list.ts	issue.md fragment
sentry release list	--environment, --period, --status	src/commands/release/list.ts	release.md fragment
sentry release create	--ref, --url	src/commands/release/create.ts	release.md fragment
sentry release deploy	--url, --started, --finished, --time	src/commands/release/deploy.ts	release.md fragment
sentry release finalize	--released, --url	src/commands/release/finalize.ts	release.md fragment
sentry release set-commits	--clear, --commit, --initial-depth	src/commands/release/set-commits.ts	release.md fragment
sentry replay list	--environment	src/commands/replay/list.ts	replay.md fragment
sentry dashboard view	--period	src/commands/dashboard/view.ts	dashboard.md fragment
sentry dashboard widget add	--col, --row, --width, --height, --layout	src/commands/dashboard/widget/add.ts	dashboard.md fragment

Note: Globally auto-injected flags (--json, --fields, --fresh, --cursor, --verbose, --log-level, --org, --project) are handled by wrappers and documented in the global options section.

C. Missing Usage Examples

All fragment files have bash examples. Only gap was sentry proguard upload — fixed in this PR.

D. Stale Descriptions

No meaningful drift. Brief strings are auto-generated into docs.

E. Missing Route Mappings in Skill Generator

No gaps. ROUTE_TO_REFERENCE was replaced by automatic 1:1 mapping. All 27 visible routes have reference files.

F. Installation / Distribution Gaps

Gap	Source	Doc
SENTRY_INSTALL_DIR env var not in getting-started	install script, setup.ts	getting-started.mdx
Install script flags (--no-modify-path, --no-completions, --no-agent-skills) not in getting-started	install lines 64-72	getting-started.mdx
npm/pnpm/bun installs don't auto-run setup but docs claimed they did	package.json (no postinstall)	agentic-usage.md — fixed
Nightly channel switching from npm triggers standalone migration, undocumented	upgrade.ts	Not in any doc

G. Undocumented Environment Variables

configuration.md is generated from env-registry.ts. These vars exist in code but are absent from the registry:

Variable	Used In	Purpose
SENTRY_TRACES_SAMPLE_RATE	local/run.ts	Injected into wrapped commands
SENTRY_SCAN_DISABLE_WORKERS	scan/grep.ts	Disable worker threads
SENTRY_MONITOR_SLUG	monitor/run.ts	Injected into wrapped command
SENTRY_LAST_EVENT	bash-hook.ts	Bash hook template
SENTRY_ENVIRONMENT	bash-hook.ts	Bash hook traceback
SENTRY_CLI_NO_EXIT_TRAP	bash-hook.ts	Skip exit trap

Note: Most are auto-injected rather than user-configured, so omission may be intentional.

H. Auth / Self-Hosted Gaps

Gap	Source	Doc
--url flag for login not documented	login.ts	fixed in this PR
--read-only and --scope for login	login.ts	fixed in this PR
Auth token priority inverted in library-usage	db/auth.ts	fixed in this PR
auth refresh flags (--read-only, --scope, --force)	refresh.ts	auth.md fragment
Trust anchor model not cross-referenced from auth docs	login-host-guard.ts	auth.md

I. Plugin/Skills Gaps

Gap	Source	Doc
npm install claimed to auto-install skills	package.json	fixed in this PR
plugins/README.md doesn't document ~/.claude/~/.agents auto-install	agent-skills.ts	plugins/README.md
plugins/README.md doesn't mention npx skills add	agentic-usage.md	plugins/README.md

J. README / DEVELOPMENT.md Drift

Claim	File	Actual
Uses bun install, bun run, bun test commands	AGENTS.md lines 40-61	package.json uses pnpm@10.11.0. Scripts use pnpm run.
References bun:test testing framework	AGENTS.md testing section	Tests use vitest, not bun:test.
Title says "Built with Bun"	AGENTS.md line 3	Dev uses pnpm + tsx, build uses esbuild + fossilize.
bun add -d for deps	AGENTS.md Rules section	Should be pnpm add -D
README.md and DEVELOPMENT.md use pnpm	Both files	Matches package.json — OK

---

Top 5 Most Impactful Fixes (Prioritized)

1. AGENTS.md bun → pnpm/vitest drift (HIGH) — AGENTS.md is consumed by every AI agent working on this repo. It references bun install, bun test, bun:test, and bun add -d throughout, but the repo uses pnpm as package manager and vitest as test runner. Every agent following these instructions will run wrong commands. Not fixed here — needs broader discussion as it's the primary agent guidance file.

2. Auth token priority in library-usage.md (HIGH) — Was inverted (said env token > stored OAuth). Fixed in this PR.

3. Missing --url flag for self-hosted login (HIGH) — The recommended auth method for self-hosted was undocumented. Fixed in this PR.

4. Agentic-usage.md npm install claim (MEDIUM) — Users on npm/pnpm/bun wouldn't get auto-installed skills. Fixed in this PR.

5. Missing proguard upload documentation (MEDIUM) — Full command with zero docs. Fixed in this PR.

  

[github-actions]

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

[github-actions]

Codecov Results 📊

✅ Patch coverage is 100.00%. Project has 5134 uncovered lines.
❌ Project coverage is 81.47%. Comparing base (base) to head (head).

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
- Coverage    81.48%    81.47%    -0.01%
==========================================
  Files          397       397         —
  Lines        27702     27702         —
  Branches     17991     17991         —
==========================================
+ Hits         22570     22568        -2
- Misses        5132      5134        +2
- Partials      1862      1862         —

---

Generated by Codecov Action