Skip to content

Share Sentry API URLs and bearer headers - #1442

Merged
BYK merged 3 commits into
mainfrom
feat/toolkit-core-auth-api
Oct 7, 2026
Merged

BYK merged 3 commits into
mainfrom
feat/toolkit-core-auth-api

Conversation

@BYK

@BYK BYK commented Oct 7, 2026

Copy link
Copy Markdown
Member

Summary

  • Add pure shared API URL assembly and bearer-header formatting in toolkit-core.
  • Use the shared functions in CLI raw/region API requests and the MCP API client while retaining product-specific host scope, OAuth refresh, HTTP transport, retries, and error types.
  • Cover self-hosted path prefixes, encoded cursors, and malformed token rejection.

Validation

  • pnpm run tsc
  • pnpm run lint
  • pnpm run test (CLI 10,533; MCP core 1,755; toolkit core 36; MCP server 84; test client 80; Cloudflare 433)
  • pnpm run pre-commit:generated, pnpm run docs:check, CLI check:deps, Oxfmt

Co-Authored-By: GPT-6 Sol <agent@openai.com>
@github-actions github-actions Bot added the risk: medium PR risk score: medium label Oct 7, 2026
BYK and others added 2 commits October 7, 2026 20:37
Co-Authored-By: GPT-6 Sol <agent@openai.com>
Co-Authored-By: GPT-6 Sol <agent@openai.com>
@BYK
BYK merged commit 7ee08df into main Oct 7, 2026
34 checks passed
@BYK
BYK deleted the feat/toolkit-core-auth-api branch October 7, 2026 21:39
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…missing env vars, new commands (getsentry#1461)

## Documentation Audit Report (2026-08-24)

Weekly automated audit comparing the CLI implementation against its
documentation. Changes since the last merged audit (PR getsentry#1400,
2026-08-11) include: the `sentry cli completion` command (getsentry#1427), sixel
dashboard rendering (getsentry#1410), the `--environment` explore fix (getsentry#1442),
and the 0.43.0 release.

---

## Findings & Fixes

### A. Undocumented or missing commands/subcommands

| Command | Source | Expected doc location | Status |
|---------|--------|----------------------|--------|
| `sentry cli completion` | `src/commands/cli/completion.ts` (added in
getsentry#1427) | `apps/cli-docs/src/fragments/commands/cli.md` | **Fixed** —
added examples for bash, zsh, fish |

All other commands in `src/commands/` have corresponding fragment files.
Hidden backward-compat aliases (`send-event`, `send-envelope`,
`bash-hook`, `whoami`, plural aliases) are correctly excluded from docs.

### B. Undocumented flags

| Flag | Command | Source | Doc file | Status |
|------|---------|--------|----------|--------|
| `--sixel` / `-s` | `sentry dashboard view` |
`src/commands/dashboard/view.ts` | `fragments/commands/dashboard.md` |
**Fixed** — added example |

All other non-hidden flags are auto-generated into the command docs via
`generate-command-docs.ts`.

### C. Missing usage examples

No new gaps. The `sentry cli completion` command was the only command
without examples, now fixed.

### D. Stale descriptions

| Command/Flag | Code brief | Doc description | Status |
|-------------|-----------|-----------------|--------|
| `sentry explore --environment` | Was: "Replay environment filter for
--dataset replays" | Now works for all datasets (fixed in getsentry#1442) |
**Fixed** — updated brief to "Environment filter" |

### E. Missing route mappings in skill generator

**N/A** — `ROUTE_TO_REFERENCE` was removed and replaced with automatic
1:1 route-to-reference mapping via `groupRoutesByReference()` in
`script/generate-skill.ts`. No manual mapping to go stale.

### F. Installation / distribution gaps

No new gaps. Install script flags (`--no-modify-path`,
`--no-completions`, `--no-agent-skills`) and env vars
(`SENTRY_INSTALL_DIR`, `SENTRY_VERSION`, `SENTRY_INIT`) are documented
in `getting-started.mdx`. Platform support table matches `.craft.yml`
targets (macOS x64/arm64, Linux x64/arm64, Windows x64).

### G. Undocumented environment variables

| Variable | Referenced in | Expected doc | Status |
|----------|-------------|-------------|--------|
| `DO_NOT_TRACK` | `src/lib/telemetry.ts` | `configuration.md`
(generated from env-registry) | **Fixed** — added to env-registry.ts |
| `SENTRY_PIPELINE` | `src/commands/build/upload.ts`,
`src/lib/build/index.ts` | `configuration.md` | **Fixed** — added to
env-registry.ts |

Remaining niche/internal vars NOT added (intentionally excluded from
user-facing docs):
- `SENTRY_ENVIRONMENT` — bash-hook template only
- `SENTRY_CLI_NO_EXIT_TRAP` — bash-hook template internal
- `SENTRY_SCAN_DISABLE_WORKERS` — internal performance tuning
- `SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE` — test-only
- `SENTRY_RN_*` — internal react-native wrapper vars
- `SENTRY_TRACES_SAMPLE_RATE` — inherited from SDK, not a CLI config

### H. Auth / self-hosted gaps

No new gaps. OAuth scopes in `self-hosted.md` and `DEVELOPMENT.md` are
auto-generated (`GENERATED:START oauth-scopes`). The `--url` flag for
`auth login` and `SENTRY_HOST`/`SENTRY_URL` behavior are documented.
Token priority (OAuth > env token unless `SENTRY_FORCE_ENV_TOKEN`) is
correct.

### I. Plugin/skills gaps

No new gaps since the last audit. Skills install to `~/.claude` and
`~/.agents` only. The `agentic-usage.md` correctly states this.
Detection of other agents (Cursor, Windsurf, Copilot, etc.) is for
telemetry and the docs correctly list them as "supported" agents (they
can use the CLI, just not via auto-installed skills).

### J. README / DEVELOPMENT.md / contributing.md drift

| File | Claim | Reality | Status |
|------|-------|---------|--------|
| `script/generate-docs-sections.ts` line 210 | "TypeScript types and
Zod schemas" | Migrated to Valibot in getsentry#1389 (merged Aug 7) | **Fixed** |
| `apps/cli-docs/src/content/docs/features.md` | DSN detection table
lists 6 languages with specific `Sentry.init()` patterns | Scanner uses
a universal DSN URL regex across 30+ file extensions | **Fixed** —
updated table to match actual TEXT_EXTENSIONS set |

Node.js version claims (v22.15+ for dev, >=20 for runtime) are correct.
Build commands, test commands, and license (`FSL-1.1-Apache-2.0`) are
all accurate.

---

## Top 5 Most Impactful Fixes (prioritized)

1. **DSN detection language table overhaul** (`features.md`) — The
previous table implied language-specific `Sentry.init()` pattern
matching, which is misleading. The universal regex approach supports 30+
file extensions. Users of Kotlin, Rust, Swift, Dart, C#, etc. would not
have known their DSNs are detected.

2. **Missing `sentry cli completion` docs** (`cli.md` fragment) — New
command from getsentry#1427 with no usage examples. Users discovering shell
completions would miss this standalone alternative to `sentry cli
setup`.

3. **Stale `--environment` flag brief** (`explore.ts`) — After getsentry#1442
fixed `--environment` to work for all datasets, the flag's `brief`
string still said "Replay environment filter". Users would think it only
applies to replays.

4. **Missing env vars in registry** (`env-registry.ts`) — `DO_NOT_TRACK`
(industry-standard telemetry opt-out) and `SENTRY_PIPELINE` (build
plugin identification) were referenced in code but absent from the
generated configuration page.

5. **Zod→Valibot drift in project structure**
(`generate-docs-sections.ts`) — The auto-generated project structure
tree in `contributing.md` still said "Zod schemas" despite the migration
to Valibot in getsentry#1389. Contributors would be confused about which
validation library to use.

<div><a
href="https://cursor.com/agents/bc-2961de96-bee8-48d4-becb-d403a42a7cb6?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/automations/8b0c0f35-da5e-409d-984c-5e39518ffb8a"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/view-automation-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/view-automation-light.png"><img
alt="View Automation" width="141" height="28"
src="https://cursor.com/assets/images/view-automation-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: jared-outpost[bot] <jared-outpost[bot]@users.noreply.github.com>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…missing env vars, new commands (getsentry#1461)

## Documentation Audit Report (2026-08-24)

Weekly automated audit comparing the CLI implementation against its
documentation. Changes since the last merged audit (PR getsentry#1400,
2026-08-11) include: the `sentry cli completion` command (getsentry#1427), sixel
dashboard rendering (getsentry#1410), the `--environment` explore fix (getsentry#1442),
and the 0.43.0 release.

---

## Findings & Fixes

### A. Undocumented or missing commands/subcommands

| Command | Source | Expected doc location | Status |
|---------|--------|----------------------|--------|
| `sentry cli completion` | `src/commands/cli/completion.ts` (added in
getsentry#1427) | `apps/cli-docs/src/fragments/commands/cli.md` | **Fixed** —
added examples for bash, zsh, fish |

All other commands in `src/commands/` have corresponding fragment files.
Hidden backward-compat aliases (`send-event`, `send-envelope`,
`bash-hook`, `whoami`, plural aliases) are correctly excluded from docs.

### B. Undocumented flags

| Flag | Command | Source | Doc file | Status |
|------|---------|--------|----------|--------|
| `--sixel` / `-s` | `sentry dashboard view` |
`src/commands/dashboard/view.ts` | `fragments/commands/dashboard.md` |
**Fixed** — added example |

All other non-hidden flags are auto-generated into the command docs via
`generate-command-docs.ts`.

### C. Missing usage examples

No new gaps. The `sentry cli completion` command was the only command
without examples, now fixed.

### D. Stale descriptions

| Command/Flag | Code brief | Doc description | Status |
|-------------|-----------|-----------------|--------|
| `sentry explore --environment` | Was: "Replay environment filter for
--dataset replays" | Now works for all datasets (fixed in getsentry#1442) |
**Fixed** — updated brief to "Environment filter" |

### E. Missing route mappings in skill generator

**N/A** — `ROUTE_TO_REFERENCE` was removed and replaced with automatic
1:1 route-to-reference mapping via `groupRoutesByReference()` in
`script/generate-skill.ts`. No manual mapping to go stale.

### F. Installation / distribution gaps

No new gaps. Install script flags (`--no-modify-path`,
`--no-completions`, `--no-agent-skills`) and env vars
(`SENTRY_INSTALL_DIR`, `SENTRY_VERSION`, `SENTRY_INIT`) are documented
in `getting-started.mdx`. Platform support table matches `.craft.yml`
targets (macOS x64/arm64, Linux x64/arm64, Windows x64).

### G. Undocumented environment variables

| Variable | Referenced in | Expected doc | Status |
|----------|-------------|-------------|--------|
| `DO_NOT_TRACK` | `src/lib/telemetry.ts` | `configuration.md`
(generated from env-registry) | **Fixed** — added to env-registry.ts |
| `SENTRY_PIPELINE` | `src/commands/build/upload.ts`,
`src/lib/build/index.ts` | `configuration.md` | **Fixed** — added to
env-registry.ts |

Remaining niche/internal vars NOT added (intentionally excluded from
user-facing docs):
- `SENTRY_ENVIRONMENT` — bash-hook template only
- `SENTRY_CLI_NO_EXIT_TRAP` — bash-hook template internal
- `SENTRY_SCAN_DISABLE_WORKERS` — internal performance tuning
- `SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE` — test-only
- `SENTRY_RN_*` — internal react-native wrapper vars
- `SENTRY_TRACES_SAMPLE_RATE` — inherited from SDK, not a CLI config

### H. Auth / self-hosted gaps

No new gaps. OAuth scopes in `self-hosted.md` and `DEVELOPMENT.md` are
auto-generated (`GENERATED:START oauth-scopes`). The `--url` flag for
`auth login` and `SENTRY_HOST`/`SENTRY_URL` behavior are documented.
Token priority (OAuth > env token unless `SENTRY_FORCE_ENV_TOKEN`) is
correct.

### I. Plugin/skills gaps

No new gaps since the last audit. Skills install to `~/.claude` and
`~/.agents` only. The `agentic-usage.md` correctly states this.
Detection of other agents (Cursor, Windsurf, Copilot, etc.) is for
telemetry and the docs correctly list them as "supported" agents (they
can use the CLI, just not via auto-installed skills).

### J. README / DEVELOPMENT.md / contributing.md drift

| File | Claim | Reality | Status |
|------|-------|---------|--------|
| `script/generate-docs-sections.ts` line 210 | "TypeScript types and
Zod schemas" | Migrated to Valibot in getsentry#1389 (merged Aug 7) | **Fixed** |
| `apps/cli-docs/src/content/docs/features.md` | DSN detection table
lists 6 languages with specific `Sentry.init()` patterns | Scanner uses
a universal DSN URL regex across 30+ file extensions | **Fixed** —
updated table to match actual TEXT_EXTENSIONS set |

Node.js version claims (v22.15+ for dev, >=20 for runtime) are correct.
Build commands, test commands, and license (`FSL-1.1-Apache-2.0`) are
all accurate.

---

## Top 5 Most Impactful Fixes (prioritized)

1. **DSN detection language table overhaul** (`features.md`) — The
previous table implied language-specific `Sentry.init()` pattern
matching, which is misleading. The universal regex approach supports 30+
file extensions. Users of Kotlin, Rust, Swift, Dart, C#, etc. would not
have known their DSNs are detected.

2. **Missing `sentry cli completion` docs** (`cli.md` fragment) — New
command from getsentry#1427 with no usage examples. Users discovering shell
completions would miss this standalone alternative to `sentry cli
setup`.

3. **Stale `--environment` flag brief** (`explore.ts`) — After getsentry#1442
fixed `--environment` to work for all datasets, the flag's `brief`
string still said "Replay environment filter". Users would think it only
applies to replays.

4. **Missing env vars in registry** (`env-registry.ts`) — `DO_NOT_TRACK`
(industry-standard telemetry opt-out) and `SENTRY_PIPELINE` (build
plugin identification) were referenced in code but absent from the
generated configuration page.

5. **Zod→Valibot drift in project structure**
(`generate-docs-sections.ts`) — The auto-generated project structure
tree in `contributing.md` still said "Zod schemas" despite the migration
to Valibot in getsentry#1389. Contributors would be confused about which
validation library to use.

<div><a
href="https://cursor.com/agents/bc-2961de96-bee8-48d4-becb-d403a42a7cb6?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/automations/8b0c0f35-da5e-409d-984c-5e39518ffb8a"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/view-automation-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/view-automation-light.png"><img
alt="View Automation" width="141" height="28"
src="https://cursor.com/assets/images/view-automation-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: jared-outpost[bot] <jared-outpost[bot]@users.noreply.github.com>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…missing env vars, new commands (getsentry#1461)

## Documentation Audit Report (2026-08-24)

Weekly automated audit comparing the CLI implementation against its
documentation. Changes since the last merged audit (PR getsentry#1400,
2026-08-11) include: the `sentry cli completion` command (getsentry#1427), sixel
dashboard rendering (getsentry#1410), the `--environment` explore fix (getsentry#1442),
and the 0.43.0 release.

---

## Findings & Fixes

### A. Undocumented or missing commands/subcommands

| Command | Source | Expected doc location | Status |
|---------|--------|----------------------|--------|
| `sentry cli completion` | `src/commands/cli/completion.ts` (added in
getsentry#1427) | `apps/cli-docs/src/fragments/commands/cli.md` | **Fixed** —
added examples for bash, zsh, fish |

All other commands in `src/commands/` have corresponding fragment files.
Hidden backward-compat aliases (`send-event`, `send-envelope`,
`bash-hook`, `whoami`, plural aliases) are correctly excluded from docs.

### B. Undocumented flags

| Flag | Command | Source | Doc file | Status |
|------|---------|--------|----------|--------|
| `--sixel` / `-s` | `sentry dashboard view` |
`src/commands/dashboard/view.ts` | `fragments/commands/dashboard.md` |
**Fixed** — added example |

All other non-hidden flags are auto-generated into the command docs via
`generate-command-docs.ts`.

### C. Missing usage examples

No new gaps. The `sentry cli completion` command was the only command
without examples, now fixed.

### D. Stale descriptions

| Command/Flag | Code brief | Doc description | Status |
|-------------|-----------|-----------------|--------|
| `sentry explore --environment` | Was: "Replay environment filter for
--dataset replays" | Now works for all datasets (fixed in getsentry#1442) |
**Fixed** — updated brief to "Environment filter" |

### E. Missing route mappings in skill generator

**N/A** — `ROUTE_TO_REFERENCE` was removed and replaced with automatic
1:1 route-to-reference mapping via `groupRoutesByReference()` in
`script/generate-skill.ts`. No manual mapping to go stale.

### F. Installation / distribution gaps

No new gaps. Install script flags (`--no-modify-path`,
`--no-completions`, `--no-agent-skills`) and env vars
(`SENTRY_INSTALL_DIR`, `SENTRY_VERSION`, `SENTRY_INIT`) are documented
in `getting-started.mdx`. Platform support table matches `.craft.yml`
targets (macOS x64/arm64, Linux x64/arm64, Windows x64).

### G. Undocumented environment variables

| Variable | Referenced in | Expected doc | Status |
|----------|-------------|-------------|--------|
| `DO_NOT_TRACK` | `src/lib/telemetry.ts` | `configuration.md`
(generated from env-registry) | **Fixed** — added to env-registry.ts |
| `SENTRY_PIPELINE` | `src/commands/build/upload.ts`,
`src/lib/build/index.ts` | `configuration.md` | **Fixed** — added to
env-registry.ts |

Remaining niche/internal vars NOT added (intentionally excluded from
user-facing docs):
- `SENTRY_ENVIRONMENT` — bash-hook template only
- `SENTRY_CLI_NO_EXIT_TRAP` — bash-hook template internal
- `SENTRY_SCAN_DISABLE_WORKERS` — internal performance tuning
- `SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE` — test-only
- `SENTRY_RN_*` — internal react-native wrapper vars
- `SENTRY_TRACES_SAMPLE_RATE` — inherited from SDK, not a CLI config

### H. Auth / self-hosted gaps

No new gaps. OAuth scopes in `self-hosted.md` and `DEVELOPMENT.md` are
auto-generated (`GENERATED:START oauth-scopes`). The `--url` flag for
`auth login` and `SENTRY_HOST`/`SENTRY_URL` behavior are documented.
Token priority (OAuth > env token unless `SENTRY_FORCE_ENV_TOKEN`) is
correct.

### I. Plugin/skills gaps

No new gaps since the last audit. Skills install to `~/.claude` and
`~/.agents` only. The `agentic-usage.md` correctly states this.
Detection of other agents (Cursor, Windsurf, Copilot, etc.) is for
telemetry and the docs correctly list them as "supported" agents (they
can use the CLI, just not via auto-installed skills).

### J. README / DEVELOPMENT.md / contributing.md drift

| File | Claim | Reality | Status |
|------|-------|---------|--------|
| `script/generate-docs-sections.ts` line 210 | "TypeScript types and
Zod schemas" | Migrated to Valibot in getsentry#1389 (merged Aug 7) | **Fixed** |
| `apps/cli-docs/src/content/docs/features.md` | DSN detection table
lists 6 languages with specific `Sentry.init()` patterns | Scanner uses
a universal DSN URL regex across 30+ file extensions | **Fixed** —
updated table to match actual TEXT_EXTENSIONS set |

Node.js version claims (v22.15+ for dev, >=20 for runtime) are correct.
Build commands, test commands, and license (`FSL-1.1-Apache-2.0`) are
all accurate.

---

## Top 5 Most Impactful Fixes (prioritized)

1. **DSN detection language table overhaul** (`features.md`) — The
previous table implied language-specific `Sentry.init()` pattern
matching, which is misleading. The universal regex approach supports 30+
file extensions. Users of Kotlin, Rust, Swift, Dart, C#, etc. would not
have known their DSNs are detected.

2. **Missing `sentry cli completion` docs** (`cli.md` fragment) — New
command from getsentry#1427 with no usage examples. Users discovering shell
completions would miss this standalone alternative to `sentry cli
setup`.

3. **Stale `--environment` flag brief** (`explore.ts`) — After getsentry#1442
fixed `--environment` to work for all datasets, the flag's `brief`
string still said "Replay environment filter". Users would think it only
applies to replays.

4. **Missing env vars in registry** (`env-registry.ts`) — `DO_NOT_TRACK`
(industry-standard telemetry opt-out) and `SENTRY_PIPELINE` (build
plugin identification) were referenced in code but absent from the
generated configuration page.

5. **Zod→Valibot drift in project structure**
(`generate-docs-sections.ts`) — The auto-generated project structure
tree in `contributing.md` still said "Zod schemas" despite the migration
to Valibot in getsentry#1389. Contributors would be confused about which
validation library to use.

<div><a
href="https://cursor.com/agents/bc-2961de96-bee8-48d4-becb-d403a42a7cb6?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/automations/8b0c0f35-da5e-409d-984c-5e39518ffb8a"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/view-automation-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/view-automation-light.png"><img
alt="View Automation" width="141" height="28"
src="https://cursor.com/assets/images/view-automation-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: jared-outpost[bot] <jared-outpost[bot]@users.noreply.github.com>
joshuawayzwright pushed a commit to joshuawayzwright/sentry-mcp that referenced this pull request Nov 16, 2026
…missing env vars, new commands (getsentry#1461)

## Documentation Audit Report (2026-08-24)

Weekly automated audit comparing the CLI implementation against its
documentation. Changes since the last merged audit (PR getsentry#1400,
2026-08-11) include: the `sentry cli completion` command (getsentry#1427), sixel
dashboard rendering (getsentry#1410), the `--environment` explore fix (getsentry#1442),
and the 0.43.0 release.

---

## Findings & Fixes

### A. Undocumented or missing commands/subcommands

| Command | Source | Expected doc location | Status |
|---------|--------|----------------------|--------|
| `sentry cli completion` | `src/commands/cli/completion.ts` (added in
getsentry#1427) | `apps/cli-docs/src/fragments/commands/cli.md` | **Fixed** —
added examples for bash, zsh, fish |

All other commands in `src/commands/` have corresponding fragment files.
Hidden backward-compat aliases (`send-event`, `send-envelope`,
`bash-hook`, `whoami`, plural aliases) are correctly excluded from docs.

### B. Undocumented flags

| Flag | Command | Source | Doc file | Status |
|------|---------|--------|----------|--------|
| `--sixel` / `-s` | `sentry dashboard view` |
`src/commands/dashboard/view.ts` | `fragments/commands/dashboard.md` |
**Fixed** — added example |

All other non-hidden flags are auto-generated into the command docs via
`generate-command-docs.ts`.

### C. Missing usage examples

No new gaps. The `sentry cli completion` command was the only command
without examples, now fixed.

### D. Stale descriptions

| Command/Flag | Code brief | Doc description | Status |
|-------------|-----------|-----------------|--------|
| `sentry explore --environment` | Was: "Replay environment filter for
--dataset replays" | Now works for all datasets (fixed in getsentry#1442) |
**Fixed** — updated brief to "Environment filter" |

### E. Missing route mappings in skill generator

**N/A** — `ROUTE_TO_REFERENCE` was removed and replaced with automatic
1:1 route-to-reference mapping via `groupRoutesByReference()` in
`script/generate-skill.ts`. No manual mapping to go stale.

### F. Installation / distribution gaps

No new gaps. Install script flags (`--no-modify-path`,
`--no-completions`, `--no-agent-skills`) and env vars
(`SENTRY_INSTALL_DIR`, `SENTRY_VERSION`, `SENTRY_INIT`) are documented
in `getting-started.mdx`. Platform support table matches `.craft.yml`
targets (macOS x64/arm64, Linux x64/arm64, Windows x64).

### G. Undocumented environment variables

| Variable | Referenced in | Expected doc | Status |
|----------|-------------|-------------|--------|
| `DO_NOT_TRACK` | `src/lib/telemetry.ts` | `configuration.md`
(generated from env-registry) | **Fixed** — added to env-registry.ts |
| `SENTRY_PIPELINE` | `src/commands/build/upload.ts`,
`src/lib/build/index.ts` | `configuration.md` | **Fixed** — added to
env-registry.ts |

Remaining niche/internal vars NOT added (intentionally excluded from
user-facing docs):
- `SENTRY_ENVIRONMENT` — bash-hook template only
- `SENTRY_CLI_NO_EXIT_TRAP` — bash-hook template internal
- `SENTRY_SCAN_DISABLE_WORKERS` — internal performance tuning
- `SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE` — test-only
- `SENTRY_RN_*` — internal react-native wrapper vars
- `SENTRY_TRACES_SAMPLE_RATE` — inherited from SDK, not a CLI config

### H. Auth / self-hosted gaps

No new gaps. OAuth scopes in `self-hosted.md` and `DEVELOPMENT.md` are
auto-generated (`GENERATED:START oauth-scopes`). The `--url` flag for
`auth login` and `SENTRY_HOST`/`SENTRY_URL` behavior are documented.
Token priority (OAuth > env token unless `SENTRY_FORCE_ENV_TOKEN`) is
correct.

### I. Plugin/skills gaps

No new gaps since the last audit. Skills install to `~/.claude` and
`~/.agents` only. The `agentic-usage.md` correctly states this.
Detection of other agents (Cursor, Windsurf, Copilot, etc.) is for
telemetry and the docs correctly list them as "supported" agents (they
can use the CLI, just not via auto-installed skills).

### J. README / DEVELOPMENT.md / contributing.md drift

| File | Claim | Reality | Status |
|------|-------|---------|--------|
| `script/generate-docs-sections.ts` line 210 | "TypeScript types and
Zod schemas" | Migrated to Valibot in getsentry#1389 (merged Aug 7) | **Fixed** |
| `apps/cli-docs/src/content/docs/features.md` | DSN detection table
lists 6 languages with specific `Sentry.init()` patterns | Scanner uses
a universal DSN URL regex across 30+ file extensions | **Fixed** —
updated table to match actual TEXT_EXTENSIONS set |

Node.js version claims (v22.15+ for dev, >=20 for runtime) are correct.
Build commands, test commands, and license (`FSL-1.1-Apache-2.0`) are
all accurate.

---

## Top 5 Most Impactful Fixes (prioritized)

1. **DSN detection language table overhaul** (`features.md`) — The
previous table implied language-specific `Sentry.init()` pattern
matching, which is misleading. The universal regex approach supports 30+
file extensions. Users of Kotlin, Rust, Swift, Dart, C#, etc. would not
have known their DSNs are detected.

2. **Missing `sentry cli completion` docs** (`cli.md` fragment) — New
command from getsentry#1427 with no usage examples. Users discovering shell
completions would miss this standalone alternative to `sentry cli
setup`.

3. **Stale `--environment` flag brief** (`explore.ts`) — After getsentry#1442
fixed `--environment` to work for all datasets, the flag's `brief`
string still said "Replay environment filter". Users would think it only
applies to replays.

4. **Missing env vars in registry** (`env-registry.ts`) — `DO_NOT_TRACK`
(industry-standard telemetry opt-out) and `SENTRY_PIPELINE` (build
plugin identification) were referenced in code but absent from the
generated configuration page.

5. **Zod→Valibot drift in project structure**
(`generate-docs-sections.ts`) — The auto-generated project structure
tree in `contributing.md` still said "Zod schemas" despite the migration
to Valibot in getsentry#1389. Contributors would be confused about which
validation library to use.

<div><a
href="https://cursor.com/agents/bc-2961de96-bee8-48d4-becb-d403a42a7cb6?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/automations/8b0c0f35-da5e-409d-984c-5e39518ffb8a"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/view-automation-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/view-automation-light.png"><img
alt="View Automation" width="141" height="28"
src="https://cursor.com/assets/images/view-automation-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: jared-outpost[bot] <jared-outpost[bot]@users.noreply.github.com>

This branch was previously deployed

1 inactive deployment
Actions — 4daba833 Deployed Oct 7, 2026 by BYK via eval #1273
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: medium PR risk score: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants