From 562d643e072d0dec2788006818210ee569d53e88 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 20 Apr 2026 12:10:39 +0000 Subject: [PATCH] fix: correct auth token precedence docs and update stale architecture tree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix SENTRY_AUTH_TOKEN description in env-registry.ts: stored OAuth token takes priority by default, not the env var (unless SENTRY_FORCE_ENV_TOKEN is set) - Fix auth fragment docs: token precedence order was inverted - Update AGENTS.md architecture tree: add missing command directories (dashboard, release, sourcemap, repo, init, schema) and update subcommand lists for auth, cli, event, issue, project - Update DEVELOPMENT.md env var table: add SENTRY_AUTH_TOKEN, SENTRY_FORCE_ENV_TOKEN, SENTRY_CLI_NO_TELEMETRY, SENTRY_LOG_LEVEL - Update agentic-usage.md: document automatic skill installation, expand supported agent list beyond Claude Code Co-authored-by: Miguel Betegón --- AGENTS.md | 21 ++++++++++++++------- DEVELOPMENT.md | 14 +++++++++----- docs/src/content/docs/agentic-usage.md | 14 ++++++++++---- docs/src/fragments/commands/auth.md | 12 +++++++----- 4 files changed, 40 insertions(+), 21 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a1724a17d..dbad5306f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -112,18 +112,25 @@ cli/ │ ├── app.ts # Stricli application setup │ ├── context.ts # Dependency injection context │ ├── commands/ # CLI commands -│ │ ├── auth/ # login, logout, status, refresh -│ │ ├── event/ # view -│ │ ├── issue/ # list, view, explain, plan +│ │ ├── auth/ # login, logout, refresh, status, token, whoami +│ │ ├── cli/ # defaults, feedback, fix, setup, upgrade +│ │ ├── dashboard/ # list, view, create, widget (add, edit, delete) +│ │ ├── event/ # list, view +│ │ ├── issue/ # list, view, events, explain, plan, resolve, unresolve, merge +│ │ ├── log/ # list, view │ │ ├── org/ # list, view -│ │ ├── project/ # list, view +│ │ ├── project/ # list, view, create, delete +│ │ ├── release/ # list, view, create, finalize, delete, deploy, deploys, set-commits, propose-version +│ │ ├── repo/ # list +│ │ ├── sourcemap/ # inject, upload │ │ ├── span/ # list, view +│ │ ├── team/ # list │ │ ├── trace/ # list, view, logs -│ │ ├── log/ # list, view │ │ ├── trial/ # list, start -│ │ ├── cli/ # fix, upgrade, feedback, setup │ │ ├── api.ts # Direct API access command -│ │ └── help.ts # Help command +│ │ ├── help.ts # Help command +│ │ ├── init.ts # Initialize Sentry in your project (experimental) +│ │ └── schema.ts # Browse the Sentry API schema │ ├── lib/ # Shared utilities │ │ ├── command.ts # buildCommand wrapper (telemetry + output) │ │ ├── api-client.ts # Barrel re-export for API modules diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 5a088f91c..854ab19d8 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -69,11 +69,15 @@ When creating your Sentry OAuth application: ## Environment Variables -| Variable | Description | Default | -| ------------------ | ----------------------------------------------------- | -------------------- | -| `SENTRY_CLIENT_ID` | Sentry OAuth app client ID | (required) | -| `SENTRY_HOST` | Sentry instance URL (for self-hosted, takes precedence) | `https://sentry.io` | -| `SENTRY_URL` | Alias for `SENTRY_HOST` | `https://sentry.io` | +| Variable | Description | Default | +| ----------------------- | ---------------------------------------------------------------- | -------------------- | +| `SENTRY_CLIENT_ID` | Sentry OAuth app client ID | (required for build) | +| `SENTRY_HOST` | Sentry instance URL (for self-hosted, takes precedence) | `https://sentry.io` | +| `SENTRY_URL` | Alias for `SENTRY_HOST` | `https://sentry.io` | +| `SENTRY_AUTH_TOKEN` | API token for non-interactive use (lower priority than stored OAuth by default) | — | +| `SENTRY_FORCE_ENV_TOKEN`| Force env token to take priority over stored OAuth token | — | +| `SENTRY_CLI_NO_TELEMETRY`| Disable CLI telemetry (error tracking) | — | +| `SENTRY_LOG_LEVEL` | Diagnostic log level (`error`, `warn`, `log`, `info`, `debug`, `trace`) | `info` | ## Building diff --git a/docs/src/content/docs/agentic-usage.md b/docs/src/content/docs/agentic-usage.md index add0f74d2..f18193b1a 100644 --- a/docs/src/content/docs/agentic-usage.md +++ b/docs/src/content/docs/agentic-usage.md @@ -3,11 +3,17 @@ title: Agentic Usage description: Enable AI coding agents to use the Sentry CLI --- -AI coding agents like Claude Code can use the Sentry CLI through the skill system. This allows agents to interact with Sentry directly from your development environment. +AI coding agents like Claude Code — and any agent that reads skills from `~/.agents` (such as Cursor) — can use the Sentry CLI through the skill system. This allows agents to interact with Sentry directly from your development environment. -## Adding the Skill +## Automatic Installation -Add the Sentry CLI skill to your agent: +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. + +To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli setup`. + +## Manual Installation + +Add the Sentry CLI skill to your agent manually: ```bash npx skills add https://cli.sentry.dev @@ -43,4 +49,4 @@ The skill uses your existing CLI authentication, so you'll need to run `sentry a ## Requirements - An authenticated Sentry CLI installation (`sentry auth login`) -- An AI coding agent that supports the skills system (e.g., Claude Code) +- An AI coding agent that supports the skills system (e.g., Claude Code, or any agent that reads from `~/.agents` such as Cursor) diff --git a/docs/src/fragments/commands/auth.md b/docs/src/fragments/commands/auth.md index 0a0884d76..9d5afa16b 100644 --- a/docs/src/fragments/commands/auth.md +++ b/docs/src/fragments/commands/auth.md @@ -76,12 +76,14 @@ sentry auth whoami Auth tokens are stored in a SQLite database at `~/.sentry/cli.db` with restricted file permissions. -## Environment Variable Precedence +## Token Precedence -The CLI checks for auth tokens in the following order, using the first one found: +By default, the CLI checks for auth tokens in the following order: -1. `SENTRY_AUTH_TOKEN` environment variable -2. `SENTRY_TOKEN` environment variable (legacy alias) -3. The stored OAuth token in the SQLite database +1. The stored OAuth token in the SQLite database (from `sentry auth login`) +2. `SENTRY_AUTH_TOKEN` environment variable +3. `SENTRY_TOKEN` environment variable (legacy alias) + +The stored OAuth token takes priority because it supports automatic refresh. To override this and force environment tokens to win, set `SENTRY_FORCE_ENV_TOKEN=1`. When a token comes from an environment variable, the CLI skips expiry checks and automatic refresh.