Repository navigation
docs(cli): Correct self-hosted login, upgrade, and dev setup docs - #1541
Merged
Merged
Conversation
Co-Authored-By: Miguel Betegon <miguel.betegon@sentry.io>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
BYK
approved these changes
Oct 19, 2026
This was referenced Oct 22, 2026
BYK
added a commit
that referenced
this pull request
Oct 23, 2026
#1541 fixed most of the CLI docs drift found in getsentry/cli#1644, but the remaining gaps were all the same kind of problem: hand-written docs that copy facts out of the code. Fixing each one by hand would just bring the drift back later, so this PR makes the docs come from the code, and adds CI checks for what can't be generated. **Generated from code** (via `generate-docs-sections.ts` markers, checked by `check:docs-sections`): - **Destructive commands in the agent Safety Rules.** A new `destructive` flag on `buildCommand` drives this list, and `buildDeleteCommand` sets it automatically. `issue merge` and `trial start` set it explicitly. The list grows from 2 commands to 10, and the generated skill picks it up. It now also covers `cli uninstall`, `integration delete` and `issue unlink`, which #1644's hand-made list missed. - **Detected agents in agentic-usage.** These come from a new `AGENT_DISPLAY_NAMES` map. A unit test fails if `detectAgent()` can return an agent with no display name. This adds Antigravity, which the docs were missing. - **Target syntax table** in the commands overview and `CONTRIBUTING.md`. It comes from `TARGET_FORMS`, and a test runs every documented example through `parseOrgProjectArg()`. The test also fails if a parse type has no documented form. - **Skill file layout in `plugins/README.md`.** Generation fails if a listed path no longer exists. **New checks** (added to `ci:policy`): - **`check:doc-examples`** checks about 1,400 `sentry …` invocations against the live route tree. It covers fenced shell blocks and inline code in hand-written docs, plus command `--help` examples. An example fails if the command doesn't exist (aliases count), if it uses a flag the command doesn't define, or if it passes a bare `my-org` where the CLI looks up projects first. The last rule found ambiguous examples in the dashboard help, `alert metrics create`, `project list` and `agent-conversation list`, which now use `my-org/`. - **`check:installer-docs`** checks the install scripts: - Every `SENTRY_*` variable or flag an install script reads must appear in its own help text. - Everything in either installer's help must appear in the installation guide. - It caught `SENTRY_CLI_NO_TELEMETRY`, which the bash installer and the guide didn't mention. - **`check:stale-refs`** now flags `pnpm run cli -- <args>`. pnpm passes the literal `--` through, so `pnpm run cli -- --help` fails with "Command not found: --help". **Dev setup:** `pnpm run cli` and `generate:docs` now create missing `src/generated/` files on a fresh checkout through `script/ensure-generated.mjs`. That removes the `generate:schema` bootstrap step instead of documenting it. Before this, `pnpm run cli` and `pnpm run test:unit` failed on a fresh clone. **Docs-only fixes:** - The bare-name row in the `sentry init` target table now matches `resolveTarget`: existing project, then org, then a new project. - The `--keep-config` help text now uses the XDG config dir constant instead of `~/.sentry`. - The package README tells Homebrew and package-manager users to run `sentry cli setup` for agent skills; package managers also skip completions. Not ported from #1644: its claim that Homebrew runs `cli setup` automatically. The formula in `.craft.yml` doesn't run it, and its caveats tell users to run it themselves. <!-- junior-request-attribution:start --> via **BYK**. <!-- junior-request-attribution:end --> <!-- junior-session-footer:start --> <!-- junior-conversation-id:local%3Aweb%3A7fce60d3964134b1dfb66d55 --> -- [View Junior Session in Sentry](https://sentry.sentry.io/explore/conversations/local%3Aweb%3A7fce60d3964134b1dfb66d55/?project=4510944073809921) <!-- junior-session-footer:end --> --------- Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: Claude Opus <noreply@anthropic.com> Co-authored-by: BYK <burak.kaya@sentry.io>
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This fixes CLI docs that no longer match how the CLI behaves. Every change was checked against the implementation in
packages/cli.What changed
SENTRY_HOSTorSENTRY_URLwas enough forsentry auth login. In fact the CLI only trusts a self-hosted host when--urlis passed, because that's the only thing that registers a login trust anchor. Without it, login is refused. Theself-hostedpage, theauthfragment and the generated skill reference now say this, and the env-only example is removed. Also fixed the numbering of the OAuth app setup steps.yarnto the install-method table and corrected thebuncommand tobun add -g. Also noted that switching to nightly from a Homebrew install also moves you to a standalone binary. The--methodhelp forsentry cli setupnow listsbrew, which it already accepted.SENTRY_INIT=1, which runssentry initright after installing.--no-agent-skillschoice is saved and applies to later upgrades.sentry cli defaults agent-skills onturns installation back on.sentry upgradeis nowsentry cli upgrade, and the persistent-defaults intro lists every keysentry cli defaultsaccepts.contributing.mdnow match the package scripts.DEVELOPMENT.mdnow describesSENTRY_CLIENT_IDand thepackages/cli/.env.localsetup correctly.packages/cli/AGENTS.mdnow has the right relative link, the fullgenerate:docssteps and an up-to-date command directory list.Validation
generate:schema,generate:docsand thesentry-cli-docsbuild.ci:policy, lint, typecheck and the repo-widedocs:checkpassed.test/commands/cliandtest/scripttests passed.via bete.
--
View Junior Session [Sentry]