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/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/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/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. 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). 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