docs: align install, auth, config, and dev docs with current CLI behavior

[cursor]

Summary

Updates the Sentry CLI documentation to match the current CLI implementation: installer usage, self-hosted login, cli defaults, agent skill installation, bare org/project targets, and the development setup in the pnpm workspace.

What changed

Installation and distribution

• Installer examples now put SENTRY_VERSION / SENTRY_INSTALL_DIR on the bash side of the pipe (curl … | SENTRY_VERSION=0.42.2 bash). A prefix on curl never reaches the installer. Fixed in getting-started and the installer's --help text.
• Getting-started documents SENTRY_INIT=1, the -v short form of --version, and the SENTRY_CLI_NO_TELEMETRY=1 opt-out for installer error reporting.
• The README notes that npm/pnpm/yarn/bun installs need sentry cli setup for completions and agent skills.
• The cli page adds yarn to install method detection.

Authentication and self-hosted usage

• Self-hosted "After Login", the auth page, and getting-started now say that only sentry auth login --url saves the instance as the default URL. A login done through SENTRY_HOST/SENTRY_URL needs the variable kept set, or sentry cli defaults url.
• Getting-started recommends --url for self-hosted and mentions SENTRY_CLIENT_ID.
• Fixed the duplicated step number in the self-hosted OAuth app setup.

Configuration

• Persistent Defaults lists every sentry cli defaults key (headers, ca-cert, agent-skills, graphics, plus the existing ones), and the cli page has examples for the new keys.
• sentry upgrade corrected to sentry cli upgrade.

Commands and usage examples

• The commands overview has a new target syntax section. A bare name matches a project first and falls back to an org only for commands that accept one; <org>/ targets the org explicitly (matches fix(resolve): use an org slug only when no project matches #1622).
• alert metrics create example uses my-org/.
• sentry init target table describes the full bare-slug behavior (existing project, then org, then new project).

Agent skills and plugins

• Agentic usage and plugins README now say skills install only into existing ~/.claude / ~/.agents directories, that package manager installs need cli setup, and that --no-agent-skills is remembered. Re-enable with sentry cli defaults agent-skills on.
• Antigravity added to the detected-agent list.
• Agent safety guidance lists all delete commands, plus issue merge and trial start.
• Plugins README layout updated for packages/cli, references/, and the .well-known/skills publishing path.
• Regenerated SKILL.md and the alert/cli skill references.

Development documentation

• DEVELOPMENT.md, README, and contributing add the pnpm run generate:schema + generate:docs bootstrap. A fresh checkout can't run cli, typecheck, or tests without the generated API schema.
• pnpm run cli -- --help changed to pnpm run cli --help: pnpm forwards the literal --, so the old form fails with "Command not found: --help".
• DEVELOPMENT.md: SENTRY_CLIENT_ID is optional for local runs (falls back to the public sentry.io client ID) and required for build/bundle. .env.local lives in packages/cli and is loaded automatically.
• Contributing: .env.local copy path fixed. Test commands replaced with ones that actually isolate a file or watch (pnpm --filter sentry exec vitest …).
• packages/cli/AGENTS.md: fixed stale docs/src/... paths and broken relative links, and described the full generate:docs sequence.
• Root README lists apps/local.
• Root AGENTS.md restored to a pointer to packages/cli/AGENTS.md plus the lore section. fix(span): Handle invalid trace ID in tryAutoSplitSpanArg #1443 had replaced it with instructions for an unrelated agent (in its own commit, so it's easy to drop if unwanted).

Implementation updates

• packages/cli/install: only the --help usage examples changed (env var placement). Install logic is unchanged.
• cli setup --method brief now lists brew, which the parser already accepts and the Homebrew formula passes.
• cli uninstall --keep-config brief now names the XDG config dir instead of ~/.sentry.
• script/generate-docs-sections.ts: the generated project tree is rooted at packages/cli/ and no longer lists a docs/ directory.

Validation

• pnpm run generate:schema and pnpm run generate:docs: pass; regenerated output is committed.
• check:fragments, check:docs-sections, check:env-coverage, check:stale-refs: pass.
• pnpm run lint: pass.
• pnpm exec tsc --noEmit, run after generation: pass.
• TZ=UTC pnpm run test:unit: 464 files, 9,982 passed, 16 skipped.
• pnpm --filter sentry-cli-docs run build: pass, 50 pages.
• Extracted every sentry … example from the hand-written docs and skill files and checked each command path, flag, and positional count against the live route tree. No mismatches.

  

[vercel]

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

Project	Deployment	Actions	Updated
cli	Ready	Preview	Sep 28, 2026 12:30pm UTC
sentry-local	Ready	Preview	Sep 28, 2026 12:30pm UTC