docs(cli): Correct self-hosted login, upgrade, and dev setup docs

apps/cli-docs/src/content/docs/agentic-usage.md

@@ -11,7 +11,7 @@ The curl installer and Homebrew run `sentry cli setup`, which installs agent ski
 
 This uses the same `~/.agents` convention as [dotagents](https://github.com/getsentry/dotagents), Sentry's first-party tool for installing agent skills. See [Manual Installation](#manual-installation) to add the skill with dotagents yourself.
 
-To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli setup`.
+To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli setup` (or to the install script or `sentry cli upgrade`). The CLI remembers this choice, so later upgrades also skip skills. Run `sentry cli defaults agent-skills on` to turn installation back on.
 
 ## Manual Installation
 

apps/cli-docs/src/content/docs/contributing.md

@@ -124,17 +124,17 @@ pnpm run bundle
 ## Testing
 
 ```bash
-# Run all tests
+# Run unit tests with coverage (regenerates docs and the SDK first)
 pnpm run test
 
-# Run specific test file
-pnpm run test -- test/path/to/test.ts
+# Run a specific test file (skips the generate steps)
+pnpm exec vitest run test/path/to/test.ts
 
-# Run with watch mode
-pnpm run test -- --watch
+# Run in watch mode
+pnpm exec vitest
 
-# Run with coverage
-pnpm run test -- --coverage
+# Run end-to-end tests
+pnpm run test:e2e
 ```
 
 ## Code Style

apps/cli-docs/src/content/docs/getting-started.mdx

@@ -55,6 +55,12 @@ You can also set `SENTRY_INSTALL_DIR` to override the binary installation direct
 curl https://cli.sentry.dev/install -fsS | SENTRY_INSTALL_DIR="$HOME/.local/bin" bash
 ```
 
+Set `SENTRY_INIT=1` to run [`sentry init`](../commands/init/) right after installing. This requires an interactive terminal:
+
+```bash
+curl https://cli.sentry.dev/install -fsS | SENTRY_INIT=1 bash
+```
+
 ### Windows (PowerShell)
 
 On Windows, install the latest stable release from PowerShell:

apps/cli-docs/src/content/docs/self-hosted.md

@@ -22,21 +22,17 @@ The OAuth device flow requires **Sentry 26.1.0 or later** and a public OAuth app
 1. In your Sentry instance, go to **Settings → Developer Settings → Applications → Create New Application** (or visit `https://sentry.example.com/settings/account/api/applications/`)
 2. Select **Public** as the application type
 3. Fill in the required fields (name, redirect URL — can be any placeholder URL)
-3. Save the application and copy the **Client ID**
+4. Save the application and copy the **Client ID**
 
 #### 2. Log In
 
-Use the `--url` flag to authenticate against your instance (recommended — this registers the host as trusted):
+Pass your instance URL with the `--url` flag. It registers the host as trusted:
 
 ```bash
 SENTRY_CLIENT_ID=your-client-id sentry auth login --url https://sentry.example.com
 ```
 
-Or pass the instance URL via environment variable:
-
-```bash
-SENTRY_HOST=https://sentry.example.com SENTRY_CLIENT_ID=your-client-id sentry auth login --url https://sentry.example.com
-```
+`--url` is required even when `SENTRY_HOST` or `SENTRY_URL` is already set. Without it, `sentry auth login` refuses to log in to a self-hosted host.
 
 :::tip
 You can export both variables in your shell profile so every CLI invocation picks them up:
@@ -48,7 +44,7 @@ export SENTRY_CLIENT_ID=your-client-id
 :::
 
 :::note
-The `--url` flag is the most secure way to authenticate with a new host — it is the only way to register a trust anchor for that host. Without it, the CLI refuses to log in to an instance URL that was picked up from an untrusted channel (e.g. a `.sentryclirc` file), protecting you from credential leaks and OAuth phishing.
+The `--url` flag is the only way to register a trust anchor for a new host. Without it, the CLI refuses to log in to any self-hosted instance URL, including one picked up from an environment variable or a `.sentryclirc` file. This protects you from credential leaks and OAuth phishing.
 :::
 
 ### With an API Token

apps/cli-docs/src/fragments/commands/auth.md

@@ -44,11 +44,12 @@ sentry auth --scope project:read,event:read
 
 ### Self-hosted Sentry
 
-Use `--url` (recommended) or the `SENTRY_URL` environment variable:
+Pass `--url` to log in to a self-hosted instance. Setting `SENTRY_HOST` or
+`SENTRY_URL` alone is not enough: the CLI refuses to log in to a self-hosted
+host unless `--url` confirms it.
 
 ```bash
 sentry auth --url https://sentry.example.com
-SENTRY_URL=https://sentry.example.com sentry auth
 ```
 
 For token-based auth with self-hosted:

apps/cli-docs/src/fragments/commands/cli.md

@@ -57,9 +57,10 @@ The CLI detects how it was installed and uses the appropriate upgrade method:
 | brew | Binary in a Homebrew Cellar (`brew install getsentry/tools/sentry`) |
 | npm | Globally installed via `npm install -g sentry` |
 | pnpm | Globally installed via `pnpm add -g sentry` |
-| bun | Globally installed via `bun install -g sentry` |
+| bun | Globally installed via `bun add -g sentry` |
+| yarn | Globally installed via `yarn global add sentry` |
 
-Nightly builds are only available as standalone binaries (via the curl install method). Switching to nightly from a package manager install will automatically migrate to a standalone binary.
+Nightly builds are only available as standalone binaries (via the curl install method). Switching to nightly from a Homebrew or package manager install will automatically migrate to a standalone binary.
 
 ### View and manage defaults
 

apps/cli-docs/src/fragments/configuration.md

@@ -66,7 +66,7 @@ If you previously used the legacy `sentry-cli` and have a `~/.sentryclirc` file,
 
 ## Persistent Defaults
 
-Use `sentry cli defaults` to set persistent defaults for organization, project, URL, telemetry, and tips. These are stored in the CLI's local database and apply to all commands.
+Use `sentry cli defaults` to set persistent defaults for organization, project, URL, custom headers, CA certificate, telemetry, agent skills, inline graphics, and tips. These are stored in the CLI's local database and apply to all commands.
 
 ```bash
 sentry cli defaults org my-org           # Set default organization
@@ -140,4 +140,4 @@ When installed via the install script, the CLI binary is placed in an XDG-aligne
 
 Older installs placed the binary in `~/.sentry/bin`. Running `sentry cli setup` moves an existing `~/.sentry/bin` binary into the resolved install directory (updating your `PATH` and recorded install metadata to match) and migrates any legacy `~/.sentry` config data (`cli.db`, `config.json`) into the XDG config directory. Both migrations are skipped when a binary or config already exists at the target.
 
-`sentry upgrade` runs `setup` on the new binary, so it migrates too — but conservatively, because upgrade never edits your `PATH`. A legacy `~/.sentry/bin` binary is relocated to the XDG install directory **only when that directory is already on your `PATH`**, so the moved binary stays discoverable. If the XDG directory isn't on `PATH`, upgrade leaves the binary in place (a mislocated binary that vanished from `PATH` would break the command); run `sentry cli setup` explicitly to relocate it and update `PATH`. Legacy config data is migrated on upgrade regardless.
+`sentry cli upgrade` runs `setup` on the new binary, so it migrates too — but conservatively, because upgrade never edits your `PATH`. A legacy `~/.sentry/bin` binary is relocated to the XDG install directory **only when that directory is already on your `PATH`**, so the moved binary stays discoverable. If the XDG directory isn't on `PATH`, upgrade leaves the binary in place (a mislocated binary that vanished from `PATH` would break the command); run `sentry cli setup` explicitly to relocate it and update `PATH`. Legacy config data is migrated on upgrade regardless.

packages/cli/AGENTS.md

@@ -104,7 +104,7 @@ const result = execFileSync("id", ["-u", "username"], { encoding: "utf-8", stdio
 
 The full project-structure tree — including the live command/subcommand list and the
 domain API modules — is generated from the route tree and lives in
-[`apps/cli-docs/src/content/docs/contributing.md`](apps/cli-docs/src/content/docs/contributing.md)
+[`apps/cli-docs/src/content/docs/contributing.md`](../../apps/cli-docs/src/content/docs/contributing.md)
 (the `project-structure` block produced by `script/generate-docs-sections.ts`). It is
 kept in sync automatically, so it is **not** duplicated here to avoid drift. For the
 current command list run `ls src/commands/` or `sentry --help`.
@@ -115,12 +115,13 @@ Top-level layout:
   **`src/context.ts`** — dependency-injection context.
 - **`src/commands/`** — one directory per command group (`agent-conversation`,
   `alert`, `auth`, `build`, `cli`, `code-mappings`, `dart-symbol-map`,
-  `dashboard`, `debug-files`, `docs`, `event`, `feedback`, `issue`, `local`,
+  `dashboard`, `debug-files`, `docs`, `dsn`, `event`, `feedback`, `integration`, `issue`, `local`,
   `log`, `monitor`, `org`, `platform`, `proguard`, `project`, `react-native`,
   `release`, `replay`, `repo`, `snapshots`, `sourcemap`, `span`, `status`,
   `team`, `trace`, `trial`) plus standalone command files (`api.ts`,
-  `explore.ts`, `help.ts`, `info.ts`, `init.ts`, `schema.ts`,
-  `wasm-split.ts`).
+  `explore.ts`, `help.ts`, `info.ts`, `init.ts`, `mcp.ts`, `schema.ts`,
+  `wasm-split.ts`, plus the hidden `bash-hook.ts`, `send-event.ts`, and
+  `send-envelope.ts`).
 - **`src/lib/`** — shared utilities. Key subtrees: `api/` (domain API modules),
   `db/` (SQLite layer), `dsn/` (DSN detection, with per-language extractors under
   `dsn/languages/`), and `formatters/` (output formatting). See the file-locations
@@ -434,9 +435,9 @@ Use `"date"` for timestamp-based sort (not `"time"`). Export sort types from the
 
 ### Generated Docs & Skills
 
-All command docs and skill files are generated via `pnpm run generate:docs` (which runs `generate:command-docs` then `generate:skill`). This runs automatically as part of `dev`, `build`, `typecheck`, and `test` scripts.
+All command docs and skill files are generated via `pnpm run generate:docs` (which runs `generate:banner`, `generate:command-docs`, `generate:skill`, then `generate:docs-sections`). This runs automatically as part of `dev`, `build`, `typecheck`, and `test` scripts.
 
-- **Command docs** (`apps/cli-docs/src/content/docs/commands/*.md`) are **gitignored** and generated from CLI metadata + hand-written fragments in `apps/cli-docs/src/fragments/commands/`.
+- **Command docs** (`apps/cli-docs/src/content/docs/commands/*.md`) and the configuration page (`apps/cli-docs/src/content/docs/configuration.md`) are **gitignored** and generated from CLI metadata + hand-written fragments in `apps/cli-docs/src/fragments/` (paths live in `script/paths.ts`).
 - **Skill files** (`plugins/sentry-cli/skills/sentry-cli/`) are **committed** (consumed by external plugin systems) and auto-committed by CI when stale.
 - **Examples belong to the command**: add them to `docs.examples` (`{ description, command }[]`, see `src/commands/agent-conversation/list.ts`). They render in `--help`, the generated docs, and the skill references. Don't hand-write an `Examples:` block in `fullDescription` or a `## Examples` section in a fragment for new commands.
 - Use fragments in `apps/cli-docs/src/fragments/commands/` only for prose the command metadata can't carry: guides, permissions, caveats.

packages/cli/DEVELOPMENT.md

@@ -6,7 +6,7 @@
 - [Node.js](https://nodejs.org/) v22.15+ installed
 - [pnpm](https://pnpm.io/) v11.8+ installed
 <!-- GENERATED:END dev-prereq -->
-- A Sentry OAuth application (create one at https://sentry.io/settings/account/api/applications/)
+- A Sentry OAuth application client ID for builds, self-hosted Sentry, or a custom OAuth app (create one at https://sentry.io/settings/account/api/applications/)
 
 ## Setup
 
@@ -16,19 +16,19 @@
 pnpm install
 ```
 
-2. Create a `.env.local` file in the project root:
+2. Optionally, create `packages/cli/.env.local` (see `.env.example`):
 
 ```
 SENTRY_CLIENT_ID=your-sentry-oauth-client-id
 ```
 
-Get the client ID from your Sentry OAuth application settings.
+Dev mode (`pnpm run cli`) falls back to the CLI's public sentry.io client ID when `SENTRY_CLIENT_ID` is unset. Set it to use self-hosted Sentry or your own OAuth app. `pnpm run build` and `pnpm run bundle` require it. Get the client ID from your Sentry OAuth application settings.
 
 **Note:** No client secret is needed - the CLI uses OAuth 2.0 Device Authorization Grant (RFC 8628) which is designed for public clients.
 
 ## Running Locally
 
-Load environment variables from `.env.local` (e.g. via `dotenv` or `export $(cat .env.local | xargs)`), then:
+`pnpm run cli` loads `.env.local` automatically when it exists:
 
 ```bash
 pnpm run cli -- auth login

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/auth.md

@@ -40,7 +40,6 @@ sentry auth --scope project:read --scope org:read
 sentry auth --scope project:read,event:read
 
 sentry auth --url https://sentry.example.com
-SENTRY_URL=https://sentry.example.com sentry auth
 
 sentry auth --token YOUR_TOKEN --url https://sentry.example.com
 ```

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/cli.md

@@ -132,7 +132,7 @@ Configure shell integration
 
 **Flags:**
 - `--install - Install the binary from a temp location to the system path`
-- `--method <value> - Installation method (curl, npm, pnpm, bun, yarn)`
+- `--method <value> - Installation method (curl, brew, npm, pnpm, bun, yarn)`
 - `--channel <value> - Release channel to persist (stable or nightly)`
 - `--no-modify-path - Skip PATH modification`
 - `--no-completions - Skip shell completion installation`

packages/cli/src/commands/cli/setup.ts

@@ -647,7 +647,7 @@ export const setupCommand = buildCommand({
       method: {
         kind: "parsed",
         parse: parseInstallationMethod,
-        brief: "Installation method (curl, npm, pnpm, bun, yarn)",
+        brief: "Installation method (curl, brew, npm, pnpm, bun, yarn)",
         placeholder: "method",
         optional: true,
       },