From fd4e20e737e6166123bd853deaf55a0d6b375e1d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 29 Jun 2026 12:10:25 +0000 Subject: [PATCH 1/3] docs: fix agentic-usage npm install claim, add proguard upload examples, fix library auth priority MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - agentic-usage.md: clarify that npm/pnpm/bun installs require manual 'sentry cli setup' for agent skills (no postinstall hook exists) - proguard.md: add missing upload subcommand examples and notes - library-usage.md: fix auth token priority to match actual implementation (stored OAuth > env token by default, not the reverse) Co-authored-by: Miguel Betegón --- docs/src/content/docs/agentic-usage.md | 4 +++- docs/src/content/docs/library-usage.md | 10 ++++++---- docs/src/fragments/commands/proguard.md | 24 ++++++++++++++++++++++++ 3 files changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/src/content/docs/agentic-usage.md b/docs/src/content/docs/agentic-usage.md index f18193b1a..1482a3644 100644 --- a/docs/src/content/docs/agentic-usage.md +++ b/docs/src/content/docs/agentic-usage.md @@ -7,7 +7,9 @@ AI coding agents like Claude Code — and any agent that reads skills from `~/.a ## Automatic Installation -When you install the CLI (via `curl`, Homebrew, or a package manager), `sentry cli setup` automatically installs agent skills into any detected agent root directories (`~/.claude`, `~/.agents`). Skills are also refreshed on `sentry cli upgrade`. No network fetch is needed — skill files are embedded in the binary. +When you install the CLI via `curl` or Homebrew, `sentry cli setup` automatically installs agent skills into any detected agent root directories (`~/.claude`, `~/.agents`). Skills are also refreshed on `sentry cli upgrade`. No network fetch is needed — skill files are embedded in the binary. + +If you installed via a package manager (`npm`, `pnpm`, `bun`), run `sentry cli setup` manually after installation to install agent skills. To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli setup`. diff --git a/docs/src/content/docs/library-usage.md b/docs/src/content/docs/library-usage.md index bee5978d7..7597a4f56 100644 --- a/docs/src/content/docs/library-usage.md +++ b/docs/src/content/docs/library-usage.md @@ -119,12 +119,14 @@ const help = await sdk.run("help", "issue"); ## Authentication The `token` option provides an auth token for the current invocation. When -omitted, it falls back to environment variables and stored credentials: +omitted, it falls back to stored credentials and environment variables: 1. `token` option (highest priority) -2. `SENTRY_AUTH_TOKEN` environment variable -3. `SENTRY_TOKEN` environment variable -4. Stored OAuth token from `sentry auth login` +2. Stored OAuth token from `sentry auth login` (if not expired) +3. `SENTRY_AUTH_TOKEN` environment variable +4. `SENTRY_TOKEN` environment variable + +Set `SENTRY_FORCE_ENV_TOKEN=1` to make environment variable tokens take priority over stored OAuth. ```typescript // Explicit token diff --git a/docs/src/fragments/commands/proguard.md b/docs/src/fragments/commands/proguard.md index 263a410aa..7f81b63f7 100644 --- a/docs/src/fragments/commands/proguard.md +++ b/docs/src/fragments/commands/proguard.md @@ -2,6 +2,27 @@ ## Examples +### Upload mapping files + +```bash +# Upload a ProGuard/R8 mapping file +sentry proguard upload ./app/build/outputs/mapping/release/mapping.txt + +# Upload multiple mapping files at once +sentry proguard upload mapping1.txt mapping2.txt + +# Preview without uploading (dry run) +sentry proguard upload mapping.txt --no-upload + +# Force a specific UUID instead of computing from content +sentry proguard upload mapping.txt --uuid 12345678-1234-1234-1234-123456789abc + +# Require at least one mapping file (exit non-zero if none found) +sentry proguard upload ./mappings/ --require-one +``` + +### Compute UUID + ```bash # Compute the UUID for a ProGuard/R8 mapping file sentry proguard uuid ./app/build/outputs/mapping/release/mapping.txt @@ -17,3 +38,6 @@ sentry proguard uuid mapping.txt --json Sentry uses to associate a mapping with obfuscated Android stack traces. - This matches the UUID computed by the legacy `sentry-cli proguard uuid` command byte-for-byte. +- `sentry proguard upload` uses the DIF chunk-upload protocol. Each mapping + file is bundled as `proguard/.txt`. Org/project are resolved via + standard auto-detection (DSN, env vars, config defaults). From fd7ddd27f86ecd9a3704f919659c20b2477c7abd Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 29 Jun 2026 12:11:05 +0000 Subject: [PATCH 2/3] docs: document --read-only, --scope, --url flags for auth login MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - auth.md fragment: add examples for --read-only and --scope flags - auth.md fragment: update self-hosted example to use --url (recommended) - getting-started.mdx: add --url flag example for self-hosted login, mention SENTRY_HOST alongside SENTRY_URL Co-authored-by: Miguel Betegón --- docs/src/content/docs/getting-started.mdx | 11 +++++++-- docs/src/fragments/commands/auth.md | 27 +++++++++++++++++++++-- 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx index ab018ccf8..ee2198d9c 100644 --- a/docs/src/content/docs/getting-started.mdx +++ b/docs/src/content/docs/getting-started.mdx @@ -112,10 +112,17 @@ sentry auth logout ## Self-Hosted Sentry -Using a self-hosted Sentry instance? Set `SENTRY_URL` to point at it: +Using a self-hosted Sentry instance? Use the `--url` flag on login to register your instance: ```bash -SENTRY_URL=https://sentry.example.com sentry auth login +sentry auth login --url https://sentry.example.com +``` + +You can also set `SENTRY_HOST` (or `SENTRY_URL`) as an environment variable: + +```bash +export SENTRY_HOST=https://sentry.example.com +sentry auth login ``` See the [Self-Hosted](../self-hosted/) guide for full setup details. diff --git a/docs/src/fragments/commands/auth.md b/docs/src/fragments/commands/auth.md index 9d5afa16b..2f4578a50 100644 --- a/docs/src/fragments/commands/auth.md +++ b/docs/src/fragments/commands/auth.md @@ -20,16 +20,39 @@ sentry auth login sentry auth login --token YOUR_SENTRY_API_TOKEN ``` +### Read-only login + +```bash +# Request only read scopes (project:read, org:read, event:read, etc.) +sentry auth login --read-only +``` + +### Custom scopes + +```bash +# Request specific OAuth scopes (comma-separated or repeated) +sentry auth login --scope project:read --scope org:read +sentry auth login --scope project:read,org:read,event:read +``` + ### Self-hosted Sentry +Use `--url` to register your instance as a trusted host (recommended): + +```bash +sentry auth login --url https://sentry.example.com +``` + +Or set the host via environment variable: + ```bash -SENTRY_URL=https://sentry.example.com sentry auth login +SENTRY_HOST=https://sentry.example.com sentry auth login ``` For token-based auth with self-hosted: ```bash -SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN +sentry auth login --url https://sentry.example.com --token YOUR_TOKEN ``` See [Self-Hosted Sentry](../self-hosted/) for details. From 07010b66a16d3e24bea8032dfa8c19a916034eff Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 29 Jun 2026 12:14:19 +0000 Subject: [PATCH 3/3] chore: regenerate docs --- .../skills/sentry-cli/references/auth.md | 13 +++++++++++-- .../skills/sentry-cli/references/proguard.md | 19 +++++++++++++++++++ 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/plugins/sentry-cli/skills/sentry-cli/references/auth.md b/plugins/sentry-cli/skills/sentry-cli/references/auth.md index 8d070f627..f83256f85 100644 --- a/plugins/sentry-cli/skills/sentry-cli/references/auth.md +++ b/plugins/sentry-cli/skills/sentry-cli/references/auth.md @@ -30,9 +30,18 @@ sentry auth login sentry auth login --token YOUR_SENTRY_API_TOKEN -SENTRY_URL=https://sentry.example.com sentry auth login +# Request only read scopes (project:read, org:read, event:read, etc.) +sentry auth login --read-only -SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN +# Request specific OAuth scopes (comma-separated or repeated) +sentry auth login --scope project:read --scope org:read +sentry auth login --scope project:read,org:read,event:read + +sentry auth login --url https://sentry.example.com + +SENTRY_HOST=https://sentry.example.com sentry auth login + +sentry auth login --url https://sentry.example.com --token YOUR_TOKEN ``` ### `sentry auth logout` diff --git a/plugins/sentry-cli/skills/sentry-cli/references/proguard.md b/plugins/sentry-cli/skills/sentry-cli/references/proguard.md index c5049a020..be5e7f409 100644 --- a/plugins/sentry-cli/skills/sentry-cli/references/proguard.md +++ b/plugins/sentry-cli/skills/sentry-cli/references/proguard.md @@ -20,6 +20,25 @@ Upload ProGuard/R8 mapping files to Sentry - `--no-upload - Compute and print UUIDs without uploading (dry-run)` - `--require-one - Require at least one mapping file (error if none provided)` +**Examples:** + +```bash +# Upload a ProGuard/R8 mapping file +sentry proguard upload ./app/build/outputs/mapping/release/mapping.txt + +# Upload multiple mapping files at once +sentry proguard upload mapping1.txt mapping2.txt + +# Preview without uploading (dry run) +sentry proguard upload mapping.txt --no-upload + +# Force a specific UUID instead of computing from content +sentry proguard upload mapping.txt --uuid 12345678-1234-1234-1234-123456789abc + +# Require at least one mapping file (exit non-zero if none found) +sentry proguard upload ./mappings/ --require-one +``` + ### `sentry proguard uuid ` Compute the UUID for a ProGuard mapping file