From f4751eead8cbf91803512ccb35b2e2854345141a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 31 Aug 2026 12:21:06 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20weekly=20documentation=20audit=20?= =?UTF-8?q?=E2=80=94=20add=20sentry=20docs/status=20coverage,=20install=20?= =?UTF-8?q?flags,=20plugin=20syntax?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add sentry docs command to agentic-usage.md capabilities and examples - Add sentry docs and sentry status workflow patterns to agent-guidance.md - Add sentry docs to agent-guidance key principles and common mistakes - Document install script --no-modify-path, --no-completions, --no-agent-skills flags and SENTRY_INSTALL_DIR in getting-started.mdx - Update plugins/README.md to replace deprecated Claude Code marketplace syntax with dotagents and automatic installation instructions - Add auth refresh --read-only and --scope examples to auth.md fragment Co-authored-by: Miguel Betegón --- .../src/content/docs/agent-guidance.md | 22 ++++++++++++++++ .../src/content/docs/agentic-usage.md | 5 +++- .../src/content/docs/getting-started.mdx | 21 ++++++++++++++++ apps/cli-docs/src/fragments/commands/auth.md | 6 +++++ packages/cli/plugins/README.md | 25 +++++++------------ 5 files changed, 62 insertions(+), 17 deletions(-) diff --git a/apps/cli-docs/src/content/docs/agent-guidance.md b/apps/cli-docs/src/content/docs/agent-guidance.md index c42d460cc2..d21dfaacf3 100644 --- a/apps/cli-docs/src/content/docs/agent-guidance.md +++ b/apps/cli-docs/src/content/docs/agent-guidance.md @@ -9,6 +9,7 @@ Best practices and operational guidance for AI coding agents using the Sentry CL - **Just run the command** — the CLI handles authentication and org/project detection automatically. Don't pre-authenticate or look up org/project before running commands. The CLI prompts for login if needed. - **Prefer CLI commands over raw API calls** — the CLI has dedicated commands for most tasks. Reach for `sentry issue view`, `sentry issue list`, `sentry trace view`, etc. before constructing API calls manually or fetching external documentation. +- **Use `sentry docs` for setup questions** — if you need to know how to configure a Sentry SDK or feature, run `sentry docs "your question"` to query the documentation directly. This is faster and more accurate than fetching docs externally. - **Use `sentry schema` to explore the API** — if you need to discover API endpoints, run `sentry schema` to browse interactively or `sentry schema ` to search. This is faster than fetching OpenAPI specs externally. - **Use `sentry issue view ` to investigate issues** — when asked about a specific issue (e.g., `CLI-G5`, `PROJECT-123`), use `sentry issue view` directly. - **Use `--json` for machine-readable output** — pipe through `jq` for filtering. Human-readable output includes formatting that is hard to parse. @@ -135,6 +136,26 @@ sentry local -f ai # Sentry.init({ spotlight: process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT ?? false }) ``` +### Query Sentry Documentation + +```bash +# Ask a documentation question +sentry docs "How do I configure tracing in Next.js?" + +# Search the documentation index +sentry docs list "source maps" +``` + +### Check Sentry Service Status + +```bash +# Show current status of Sentry services +sentry status + +# Machine-readable status +sentry status --json +``` + ### Explore the API Schema ```bash @@ -273,6 +294,7 @@ When querying the Events API (directly or via `sentry api`), valid dataset value - **Confusing `--query` syntax**: The `--query` flag uses Sentry search syntax (e.g., `is:unresolved`, `assigned:me`), not free text search. - **Not using `--web`**: View commands support `-w`/`--web` to open the resource in the browser — useful for sharing links. - **Fetching API schemas instead of using the CLI**: Prefer `sentry schema` to browse the API and `sentry api` to make requests — the CLI handles authentication and endpoint resolution, so there's rarely a need to download OpenAPI specs separately. +- **Fetching Sentry docs externally**: Use `sentry docs "your question"` to query Sentry's documentation from the CLI — this returns concise answers with source links, without needing to fetch or parse documentation pages. - **Release version mismatch**: The `org/version` positional is `/`, where `org/` is the org, not part of the version. `sentry release create sentry/1.0.0` creates version `1.0.0` in org `sentry`. If your `Sentry.init()` uses `release: "1.0.0"`, this is correct. Don't double-prefix like `sentry/myapp/1.0.0`. - **Running `set-commits --auto` without a git checkout**: `--auto` needs a local git repo to discover the origin remote URL and HEAD commit. In CI, ensure `actions/checkout` with `fetch-depth: 0` runs before `set-commits --auto`. - **Using `sentry api` when CLI commands suffice**: `sentry issue list --json` and `sentry issue view --json` already include `shortId`, `title`, `count`, `userCount`, `priority`, `level`, `status`, `permalink`, and other fields at the top level. When using `--fields` to select specific fields like `count` or `userCount`, the CLI automatically ensures these fields are present in the API response. Use `--fields` to select specific fields and `--help` to see all available fields. Only fall back to `sentry api` for data the CLI doesn't expose. diff --git a/apps/cli-docs/src/content/docs/agentic-usage.md b/apps/cli-docs/src/content/docs/agentic-usage.md index ffe68dc146..56233087e2 100644 --- a/apps/cli-docs/src/content/docs/agentic-usage.md +++ b/apps/cli-docs/src/content/docs/agentic-usage.md @@ -53,6 +53,7 @@ With this skill, agents can: - **AI analysis** - Get root cause analysis and fix plans via Seer AI - **Browse projects** - List projects and organizations you have access to - **Explore the API** - Browse API endpoints with `sentry schema` and make arbitrary requests with `sentry api` +- **Query documentation** - Ask questions about Sentry setup and configuration with `sentry docs` - **Make API calls** - Execute arbitrary Sentry API requests - **Authenticate** - Help you set up CLI authentication @@ -64,8 +65,10 @@ When you ask your agent about Sentry errors or want to investigate an issue, the - "What's the stack trace for ISSUE-123?" → `sentry issue view ISSUE-123` - "List all projects in my organization" → `sentry project list my-org` - "What API endpoints exist for releases?" → `sentry schema releases` +- "How do I set up source maps for Next.js?" → `sentry docs "source maps Next.js"` +- "What is Sentry's status right now?" → `sentry status` -The CLI has dedicated commands for most Sentry tasks, so agents should prefer `sentry` commands over constructing raw API calls. The `sentry schema` command provides built-in API exploration, and `sentry api` handles authenticated requests for anything not covered by a dedicated command. +The CLI has dedicated commands for most Sentry tasks, so agents should prefer `sentry` commands over constructing raw API calls. The `sentry docs` command queries Sentry's documentation directly from the terminal, the `sentry schema` command provides built-in API exploration, and `sentry api` handles authenticated requests for anything not covered by a dedicated command. The skill uses your existing CLI authentication, so you'll need to run `sentry auth login` first if you haven't already. diff --git a/apps/cli-docs/src/content/docs/getting-started.mdx b/apps/cli-docs/src/content/docs/getting-started.mdx index 101bb2fe61..ca55e7a469 100644 --- a/apps/cli-docs/src/content/docs/getting-started.mdx +++ b/apps/cli-docs/src/content/docs/getting-started.mdx @@ -34,6 +34,27 @@ The `--version` flag takes precedence over `SENTRY_VERSION` if both are set. The chosen channel is persisted so that `sentry cli upgrade` automatically tracks the same channel on future updates. +### Installer Flags + +The install script accepts additional flags to customize behavior: + +```bash +# Skip shell config modifications (~/.zshrc, ~/.bashrc, etc.) +curl https://cli.sentry.dev/install -fsS | bash -s -- --no-modify-path + +# Skip shell completion installation +curl https://cli.sentry.dev/install -fsS | bash -s -- --no-completions + +# Skip AI agent skill installation +curl https://cli.sentry.dev/install -fsS | bash -s -- --no-agent-skills +``` + +You can also set `SENTRY_INSTALL_DIR` to override the binary installation directory: + +```bash +SENTRY_INSTALL_DIR=~/.local/bin curl https://cli.sentry.dev/install -fsS | bash +``` + ### Supported Platforms {/* GENERATED:START platform-support */} diff --git a/apps/cli-docs/src/fragments/commands/auth.md b/apps/cli-docs/src/fragments/commands/auth.md index 9157ccb78f..4e1498febb 100644 --- a/apps/cli-docs/src/fragments/commands/auth.md +++ b/apps/cli-docs/src/fragments/commands/auth.md @@ -69,6 +69,12 @@ sentry auth logout ```bash sentry auth refresh + +# Refresh with read-only scopes +sentry auth refresh --read-only + +# Refresh with specific scopes +sentry auth refresh --scope project:read --scope org:read ``` ### Print stored token diff --git a/packages/cli/plugins/README.md b/packages/cli/plugins/README.md index ba62d5ed1e..ff0afb95c8 100644 --- a/packages/cli/plugins/README.md +++ b/packages/cli/plugins/README.md @@ -4,35 +4,28 @@ Agent skills for using the Sentry CLI, following the [Agent Skills](https://gith ## Installation -### Claude Code (from GitHub) +### Automatic (recommended) -```bash -# Add the marketplace -claude plugin marketplace add getsentry/cli +When you install the CLI via the install script, Homebrew, or a package manager, +`sentry cli setup` automatically installs skills into detected agent directories +(`~/.claude`, `~/.agents`). Skills are also refreshed on `sentry cli upgrade`. -# Install the plugin -claude plugin install sentry/cli -``` +### dotagents -### Claude Code (from local clone) +[dotagents](https://github.com/getsentry/dotagents) installs the skill from +the well-known source: ```bash -# Add the marketplace from local clone -claude plugin marketplace add /path/to/sentry/cli - -# Install the plugin -claude plugin install sentry/cli +npx @sentry/dotagents add https://cli.sentry.dev sentry-cli ``` -After installation, restart Claude Code. The skills will be automatically invoked when relevant to your task. - ### Cursor Skills are automatically available in `.cursor/skills/` for Cursor users. ### Other Agents -Copy the `plugins/sentry-cli/skills/` directory to your agent's skills location, or reference the SKILL.md files directly according to your agent's documentation. +Copy the `plugins/sentry-cli/skills/` directory to your agent's skills location, or reference the SKILL.md files directly according to your agent's documentation. Any agent that reads skills from `~/.agents` will pick up automatically installed skills. ## Available Skills From 6ebb57caadcc28f95197c44844e5a33f389c01f7 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 31 Aug 2026 12:22:37 +0000 Subject: [PATCH 2/2] chore: regenerate docs --- .../sentry-cli/skills/sentry-cli/SKILL.md | 22 +++++++++++++++++++ .../skills/sentry-cli/references/auth.md | 6 +++++ 2 files changed, 28 insertions(+) diff --git a/packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md b/packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md index d1f9190c72..803d6c4560 100644 --- a/packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md +++ b/packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md @@ -21,6 +21,7 @@ Best practices and operational guidance for AI coding agents using the Sentry CL - **Just run the command** — the CLI handles authentication and org/project detection automatically. Don't pre-authenticate or look up org/project before running commands. The CLI prompts for login if needed. - **Prefer CLI commands over raw API calls** — the CLI has dedicated commands for most tasks. Reach for `sentry issue view`, `sentry issue list`, `sentry trace view`, etc. before constructing API calls manually or fetching external documentation. +- **Use `sentry docs` for setup questions** — if you need to know how to configure a Sentry SDK or feature, run `sentry docs "your question"` to query the documentation directly. This is faster and more accurate than fetching docs externally. - **Use `sentry schema` to explore the API** — if you need to discover API endpoints, run `sentry schema` to browse interactively or `sentry schema ` to search. This is faster than fetching OpenAPI specs externally. - **Use `sentry issue view ` to investigate issues** — when asked about a specific issue (e.g., `CLI-G5`, `PROJECT-123`), use `sentry issue view` directly. - **Use `--json` for machine-readable output** — pipe through `jq` for filtering. Human-readable output includes formatting that is hard to parse. @@ -147,6 +148,26 @@ sentry local -f ai # Sentry.init({ spotlight: process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT ?? false }) ``` +#### Query Sentry Documentation + +```bash +# Ask a documentation question +sentry docs "How do I configure tracing in Next.js?" + +# Search the documentation index +sentry docs list "source maps" +``` + +#### Check Sentry Service Status + +```bash +# Show current status of Sentry services +sentry status + +# Machine-readable status +sentry status --json +``` + #### Explore the API Schema ```bash @@ -285,6 +306,7 @@ When querying the Events API (directly or via `sentry api`), valid dataset value - **Confusing `--query` syntax**: The `--query` flag uses Sentry search syntax (e.g., `is:unresolved`, `assigned:me`), not free text search. - **Not using `--web`**: View commands support `-w`/`--web` to open the resource in the browser — useful for sharing links. - **Fetching API schemas instead of using the CLI**: Prefer `sentry schema` to browse the API and `sentry api` to make requests — the CLI handles authentication and endpoint resolution, so there's rarely a need to download OpenAPI specs separately. +- **Fetching Sentry docs externally**: Use `sentry docs "your question"` to query Sentry's documentation from the CLI — this returns concise answers with source links, without needing to fetch or parse documentation pages. - **Release version mismatch**: The `org/version` positional is `/`, where `org/` is the org, not part of the version. `sentry release create sentry/1.0.0` creates version `1.0.0` in org `sentry`. If your `Sentry.init()` uses `release: "1.0.0"`, this is correct. Don't double-prefix like `sentry/myapp/1.0.0`. - **Running `set-commits --auto` without a git checkout**: `--auto` needs a local git repo to discover the origin remote URL and HEAD commit. In CI, ensure `actions/checkout` with `fetch-depth: 0` runs before `set-commits --auto`. - **Using `sentry api` when CLI commands suffice**: `sentry issue list --json` and `sentry issue view --json` already include `shortId`, `title`, `count`, `userCount`, `priority`, `level`, `status`, `permalink`, and other fields at the top level. When using `--fields` to select specific fields like `count` or `userCount`, the CLI automatically ensures these fields are present in the API response. Use `--fields` to select specific fields and `--help` to see all available fields. Only fall back to `sentry api` for data the CLI doesn't expose. diff --git a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/auth.md b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/auth.md index 8ce7b96d14..746f8ef333 100644 --- a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/auth.md +++ b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/auth.md @@ -64,6 +64,12 @@ Refresh your OAuth access token ```bash sentry auth refresh + +# Refresh with read-only scopes +sentry auth refresh --read-only + +# Refresh with specific scopes +sentry auth refresh --scope project:read --scope org:read ``` ### `sentry auth status`