docs(cli): Correct CLI docs drift and guard against it by sentry-junior[bot] · Pull Request #1667 · getsentry/toolkit

sentry-junior · 2026-10-26T13:19:00Z

Summary

Fixes several places where the CLI docs no longer matched CLI behavior, and adds checks so the same kinds of drift fail CI instead of shipping.

What changed

Features page
- The alias examples now match buildOrgAwareAliases: frontend becomes fr, not f, and cross-org aliases look like a/a / g/a, not o1:api.
- issue list has no ALIAS column and prints no Detected project: line, so the sample tables are gone. The page now says the alias-suffix (e-4y) appears under the short ID in multi-project lists, and the list title names the resolved project.
- The DSN pattern now matches any host, so self-hosted DSNs are included. The scanned-extension table adds .lua and .config.
Agent guidance (and the generated skill): the "Wrong issue ID format" item no longer calls numeric issue IDs wrong, because issue view accepts them.
local fragment: documents --max-envelopes (1–50,000, default 500), session view, session retention, envelope view, daemon start and daemon restart.
Flag briefs: briefs that restated their declared default no longer show it twice in --help, the command pages and the skill references. This covers local serve/local run --port/--host, alert issues create --frequency, auth login/auth default --timeout, dashboard view --renderer and sourcemap upload --url-prefix.
SDK examples (library usage, CLI README, createSentrySDK JSDoc): sdk.run("issue", "list", "-l", "5") becomes -n. -l isn't a registered alias.
packages/cli/AGENTS.md: removed the deleted src/lib/dsn/languages/ references and documented the new guards.

Implementation updates

Drift guards, so these mistakes fail CI:

Generated tables: generate-docs-sections.ts now generates the features page's DSN extension table and alias tables.
- The extension table is built from a family map, and generation fails unless that map exactly matches TEXT_EXTENSIONS.
- The alias tables are computed by calling buildOrgAwareAliases. check:docs-sections flags them as stale if the alias code changes.
SDK examples: check-doc-examples.ts now checks string-literal sdk.run(…) calls in the docs, README.md and src/index.ts against the route tree, the same way it checks sentry … examples.
Fragment coverage: check:fragments now runs with --strict, so a fragment that misses a subcommand fails instead of warning.
Flag briefs: the new test/lib/flag-briefs.test.ts fails when a value flag's brief restates its declared default.

Validation

pnpm --filter sentry run generate:schema and pnpm --filter sentry run generate:docs: pass.
pnpm --filter sentry run ci:policy: passes, with strict fragment coverage.
pnpm --filter sentry-cli-docs run build: passes.
packages/cli pnpm run lint and pnpm run typecheck: pass.
Each new guard fails when the drift is reintroduced:
- restoring -l fails check:doc-examples
- adding .zig to TEXT_EXTENSIONS fails check:docs-sections
- restoring (default 8969) fails the brief test
vitest run on test/lib, test/script and the alert, auth, dashboard, sourcemap and local command tests: 9059 passed, 6 failed. The 6 failures are permission tests (EACCES/EPERM/readonly) that also fail on the base commit in this sandbox, so this change didn't cause them.

via Junior system actor event.

--

View Junior Session [Sentry]

Show issue aliases the way issue list prints them, list every scanned extension, document configurable Local session retention, drop the duplicated defaults from Local port and host briefs, and replace the unsupported -l limit alias in SDK examples with -n.

vercel · 2026-10-26T13:19:06Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-local	Skipped		Oct 26, 2026 8:55pm UTC

BYK

This is pretty good but we need systemic changes to prevent these kinds of drifts. Can you figure out a way to prevent these drifts?

Generate the DSN extension and alias tables on the features page from the scanner and alias code, check sdk.run() examples like CLI examples, fail fragment subcommand coverage instead of warning, and test that value flag briefs don't restate their declared defaults.

sentry-junior · 2026-10-26T19:50:51Z

Thanks @BYK. Pushed 5c76a8e, which adds guards so these kinds of drift fail CI:

Code-backed tables: the features page's DSN extension and alias tables are now generated sections. The extension map must exactly match TEXT_EXTENSIONS, and the alias tables are computed by buildOrgAwareAliases.
SDK examples: check:doc-examples now checks string-literal sdk.run(…) examples against the route tree. This catches mistakes like the -l example.
Fragment coverage: check:fragments runs with --strict, so missing subcommand coverage is an error instead of a warning.
Flag briefs: the new test/lib/flag-briefs.test.ts fails when a value flag's brief restates its declared default. It caught five more briefs, which I fixed.

I checked that each guard fails when its drift is reintroduced.

Some hand-written samples, like the old Detected project: output, can't be checked mechanically. If you want, a follow-up could add more generated sections for lists like that.

BYK

Love the updates and the direction but I'm pretty sure you can do more/better :)

@example

Address review feedback on drift prevention: - Find sdk.run() calls with the TypeScript compiler instead of regexes. TypeScript fences in docs and @example JSDoc in src/index.ts are parsed, so multi-line calls, comments, and parentheses in arguments are handled. - Generate the library-usage.md sdk.run() sample from `issue list` docs.examples, so it can't drift from a checked CLI example. - Let docs.examples take an array of steps for multi-step workflows. Every step is checked by check:doc-examples and shown in --help, the generated pages, and the skill. Move the release CI workflow and the Local session lifecycle out of allow-commands fragment blocks into examples, and count workflow steps toward fragment subcommand coverage.

BYK

Beautiful. See my comment about bash tokenization. It's not a hard-blocker but if there's already a battle-tested and small library we should probably prefer that.

Alternatively you can also write this in peggyjs if you can find a good and simple enough grammar definition.

Replace the hand-written shell tokenizer and the operator-splitting regex with shell-quote (zero dependencies, already in the lockfile), added as a dev dependency for the doc scripts. Quoting, escapes, control operators, comments, and redirections now follow shell rules, so a `|` or `&&` inside a quoted argument no longer splits a command. `<placeholder>` words are protected before parsing so they aren't read as redirections.

sentry-junior Bot added the CLI Sentry CLI and CLI documentation label Oct 26, 2026

sentry-junior Bot assigned betegon Oct 26, 2026

BYK requested changes Oct 26, 2026

View reviewed changes

vercel Bot temporarily deployed to Preview October 26, 2026 19:49 Inactive

sentry-junior Bot changed the title ~~docs(cli): Correct alias, DSN scan, and Local session docs~~ docs(cli): Correct CLI docs drift and guard against it Oct 26, 2026

BYK requested changes Oct 26, 2026

View reviewed changes

Comment thread apps/cli-docs/src/content/docs/library-usage.md

Comment thread apps/cli-docs/src/fragments/commands/local.md Outdated

Comment thread packages/cli/script/check-doc-examples.ts Outdated

vercel Bot temporarily deployed to Preview October 26, 2026 20:38 Inactive

BYK approved these changes Oct 26, 2026

View reviewed changes

Comment thread packages/cli/script/shell-words.ts Outdated

BYK marked this pull request as ready for review October 26, 2026 20:50

github-actions Bot added the risk: low PR risk score: low label Oct 26, 2026

vercel Bot temporarily deployed to Preview October 26, 2026 20:55 Inactive

BYK approved these changes Oct 26, 2026

View reviewed changes

BYK merged commit f53d68d into main Oct 26, 2026
44 of 45 checks passed

BYK deleted the docs/cli-docs-accuracy-2026-10-26 branch October 26, 2026 21:41

Navigation Menu

Repository navigation

docs(cli): Correct CLI docs drift and guard against it - #1667

docs(cli): Correct CLI docs drift and guard against it#1667
BYK merged 4 commits into
mainfrom
docs/cli-docs-accuracy-2026-10-26

sentry-junior Bot commented Oct 26, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 26, 2026 •

edited

Loading

Uh oh!

BYK left a comment

Uh oh!

sentry-junior Bot commented Oct 26, 2026

Uh oh!

BYK left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BYK left a comment

Uh oh!

Uh oh!

Uh oh!

This branch was previously deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

sentry-junior Bot commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Implementation updates

Validation

Uh oh!

vercel Bot commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BYK left a comment

Choose a reason for hiding this comment

Uh oh!

sentry-junior Bot commented Oct 26, 2026

Uh oh!

BYK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BYK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This branch was previously deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sentry-junior Bot commented Oct 26, 2026 •

edited

Loading

vercel Bot commented Oct 26, 2026 •

edited

Loading