diff --git a/apps/cli-docs/src/content/docs/agent-guidance.md b/apps/cli-docs/src/content/docs/agent-guidance.md index c42d460cc..d21dfaacf 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 ffe68dc14..56233087e 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 101bb2fe6..ca55e7a46 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 9157ccb78..4e1498feb 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 ba62d5ed1..ff0afb95c 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 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 d1f9190c7..803d6c456 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 8ce7b96d1..746f8ef33 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`