From 33dd00577ee0e79768019cd6a2587e004d267992 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 12:10:13 +0000 Subject: [PATCH 1/3] =?UTF-8?q?fix:=20replace=20stale=20Bun=20prerequisite?= =?UTF-8?q?=20with=20Node.js=20=E2=89=A522.15?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The build pipeline uses fossilize (Node SEA) + esbuild, not Bun. The generate-docs-sections.ts script was hard-coding Bun as a prerequisite even though packageManager is pnpm and runtime is Node.js. - Update generateDevPrereq() to reference Node.js instead of Bun - Update DEVELOPMENT.md build section to mention fossilize/esbuild - Update generated sections in README.md, contributing.md, library-usage.md Co-authored-by: Miguel Betegón --- DEVELOPMENT.md | 4 +- DOCS-AUDIT.md | 218 ++++++++++++++++++++++++++ README.md | 4 +- docs/src/content/docs/contributing.md | 2 +- script/generate-docs-sections.ts | 25 +-- 5 files changed, 230 insertions(+), 23 deletions(-) create mode 100644 DOCS-AUDIT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index b5310089b..e7e748a44 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -2,7 +2,7 @@ ## Prerequisites -- [Bun](https://bun.sh/) installed +- [Node.js](https://nodejs.org/) v22.15 or later - A Sentry OAuth application (create one at https://sentry.io/settings/account/api/applications/) ## Setup @@ -88,7 +88,7 @@ The table below lists the most common development variables. For the complete re ## Building -Building the native binary still requires Bun: +Build the native binary (uses esbuild for bundling and fossilize for Node SEA packaging): ```bash pnpm run build diff --git a/DOCS-AUDIT.md b/DOCS-AUDIT.md new file mode 100644 index 000000000..2356124e9 --- /dev/null +++ b/DOCS-AUDIT.md @@ -0,0 +1,218 @@ +# Documentation Audit Report + +Audit of the Sentry CLI repository comparing implementation (`src/`) to documentation +(`README.md`, `DEVELOPMENT.md`, `AGENTS.md`, `docs/src/content/docs/`, `docs/src/fragments/`). + +Generated: 2026-05-25 + +--- + +## A. Undocumented or Missing Commands/Subcommands + +Command docs are auto-generated from code metadata plus hand-written fragments in +`docs/src/fragments/commands/`. The fragment-to-route mapping is CI-enforced and currently +1:1 complete. However, several **subcommands within a route** lack coverage in their fragment: + +| Command | Source | Fragment (`docs/src/fragments/commands/`) | Gap | +|---------|--------|-------------------------------------------|-----| +| `sentry issue events` | `src/commands/issue/events.ts` | `issue.md` | No example or mention in fragment; only covered indirectly via `event.md` (`sentry event list`) | +| `sentry dashboard revisions` | `src/commands/dashboard/revisions.ts` | `dashboard.md` | Not mentioned in fragment | +| `sentry dashboard restore` | `src/commands/dashboard/restore.ts` | `dashboard.md` | Not mentioned in fragment | +| `sentry cli import` | `src/commands/cli/import.ts` | `cli.md` | No example in fragment | +| `sentry cli defaults` | `src/commands/cli/defaults.ts` | `cli.md` | No example in fragment (documented only in `configuration.md` fragment) | + +**Note:** `sentry cli defaults` being in `configuration.md` may be intentional, but the +`cli.md` fragment has zero mention of it, which is confusing since it's under `sentry cli`. + +--- + +## B. Undocumented Flags + +These non-hidden flags are defined in code but not demonstrated or mentioned in their +corresponding fragment. The auto-generated reference tables do include them, but the +hand-written examples and prose do not cover them: + +| Command | Flag | Fragment | +|---------|------|----------| +| `sentry auth login` | `--url`, `--timeout`, `--force` | `auth.md` — only env-based self-hosted shown | +| `sentry explore` | `--environment` / `-e` | `explore.md` | +| `sentry explore` | `--dataset replays` | `explore.md` | +| `sentry log list` | `--period` / `-t` | `log.md` | +| `sentry log list` | `--sort` / `-s` | `log.md` | +| `sentry local serve` | `--host` / `-H` | `local.md` | +| `sentry local run` | `--host`, `--port` flags | `local.md` — only bare example shown | +| `sentry local serve` | `--filter ai` value | `local.md` — `ai` not listed as filter option | +| `sentry api` | `--silent`, `--raw-field` / `-f` | `api.md` | +| `sentry dashboard widget add` | `--dataset` | `dashboard.md` — rich docs only in code `fullDescription` | +| `sentry issue view` | `--spans` | `issue.md` | +| `sentry issue archive` | `--until` compound syntax | `issue.md` — basic syntax shown, compound mode underdocumented | + +--- + +## C. Missing Usage Examples + +These subcommands exist in the CLI but have no bash examples in any fragment: + +| Command | Fragment | +|---------|----------| +| `sentry issue events` | `issue.md` | +| `sentry dashboard revisions` | `dashboard.md` | +| `sentry dashboard restore` | `dashboard.md` | +| `sentry cli import` | `cli.md` | +| `sentry cli defaults` (in `cli.md`) | `cli.md` (examples exist in `configuration.md` only) | + +--- + +## D. Stale Descriptions + +| Location | Doc says | Code says | Impact | +|----------|----------|-----------|--------| +| `README.md` (GENERATED:START dev-prereq) | "Bun v1.3+" as prerequisite | Build uses `fossilize` (Node SEA), not Bun. `AGENTS.md` says "built with Node.js". `packageManager` is `pnpm@10.11.0`. | **High** — misleads contributors into installing Bun unnecessarily | +| `DEVELOPMENT.md` line 5 | "Bun installed" as prerequisite | Same as above — Bun not needed for dev or build | **High** | +| `DEVELOPMENT.md` line 91 | "Building the native binary still requires Bun" | Build uses `fossilize` + Node SEA, not Bun | **High** | +| `contributing.md` (GENERATED) | "Bun runtime (v1.3 or later)" | Same | **High** | +| `script/generate-docs-sections.ts` | `generateDevPrereq()` hard-codes Bun | Should reference Node.js ≥22.15 or just pnpm | **Root cause** of all Bun prerequisite mentions | +| `AGENTS.md` line 15 | "Native binaries via Node SEA" | Correct ✓ | N/A | +| `library-usage.md` | "Node.js (≥22.15) or Bun" | Library API works via CJS bundle — Bun runtime support is plausible but untested; `engines` only lists Node | Low | + +--- + +## E. Missing Route Mappings in Skill Generator + +The `ROUTE_TO_REFERENCE` map no longer exists in `script/generate-skill.ts`. It was +replaced by a 1:1 `groupRoutesByReference()` function that generates a reference file +per visible route. **All visible routes are covered.** Hidden plural aliases and `whoami` +are correctly excluded. + +No gaps found in this section. + +--- + +## F. Installation / Distribution Gaps + +| Gap | Source | Doc location | Details | +|-----|--------|--------------|---------| +| **Bun prerequisite is wrong** | `script/generate-docs-sections.ts` → `generateDevPrereq()` | `README.md`, `DEVELOPMENT.md`, `contributing.md` | Build uses fossilize/Node SEA; Bun is not required. The generator falls back to "1.3" when `packageManager` doesn't contain `bun@` | +| `SENTRY_INSTALL_DIR` | `install` script, `src/commands/cli/setup.ts` | Not in `getting-started.mdx` | Install dir override documented only in generated `configuration.md`; should be mentioned in install script docs | +| `SENTRY_INIT` | `install` script | Not in `getting-started.mdx` | Post-install init wizard trigger not mentioned | +| Install script `--no-*` flags | `install` script accepts `--no-modify-path`, `--no-completions`, `--no-agent-skills` | `getting-started.mdx` | Only `--version nightly` shown; skip flags undocumented | +| Install directory precedence | `install` script: `SENTRY_INSTALL_DIR` → `~/.local/bin` → `~/bin` → `~/.sentry/bin` | Not documented | Users may want to control where the binary lands | +| Alpine/musl auto-install | Install script auto-installs `libstdc++ libgcc` on Alpine | Not documented | Affects Docker/CI users on Alpine | +| `yarn global add sentry` | Package manager support in code | `getting-started.mdx` has yarn; `README.md` does not list yarn | Minor inconsistency | +| `pnpm dlx`, `yarn dlx`, `bunx` | Supported in `getting-started.mdx` | `README.md` only shows `npx` | Minor inconsistency | +| Nightly not available via package managers | `upgrade.ts` migrates to curl binary when switching to nightly from npm/pnpm/bun/yarn | Not documented in `getting-started.mdx` | Users switching to nightly may be surprised by binary location change | + +--- + +## G. Undocumented Environment Variables + +The environment variable reference is generated from `src/lib/env-registry.ts` into +`docs/src/content/docs/configuration.md` (gitignored). The registry is comprehensive. + +**Variables in code but NOT in `env-registry.ts`:** + +| Variable | Used in | Notes | +|----------|---------|-------| +| `SENTRY_SPOTLIGHT` | `src/commands/local/run.ts` | Injected by `sentry local run`; not user-facing (internal to Sentry SDK) | +| `SENTRY_TRACES_SAMPLE_RATE` | `src/commands/local/run.ts` | Injected by `sentry local run`; not user-facing | +| `SENTRY_CLIENT_ID_BUILD` | `src/lib/oauth.ts` | Build-time embedded client ID; not user-configurable | +| `SENTRY_OUTPUT_FORMAT` | `src/lib/env-registry.ts` | In registry ✓ but not in `self-hosted.md` env table — probably fine since it's a library API concern | + +**Verdict:** The env-registry is well-maintained. The above are internal/build-time variables that appropriately aren't user-documented. + +**However**, `docs/src/content/docs/configuration.md` does not exist as a committed file — +it is gitignored and generated. This means the full environment variable reference is only +accessible via the built doc site. Users reading the repo directly cannot find it. + +--- + +## H. Auth / Self-Hosted Gaps + +| Gap | Source | Doc location | Details | +|-----|--------|--------------|---------| +| Host trust model | `src/commands/auth/login.ts` — refuses untrusted hosts unless `--url` explicitly passed | `self-hosted.md` | Not explained; users may not understand why login fails without `--url` | +| `auth login --force` flag | `src/commands/auth/login.ts` | `auth.md` fragment, `self-hosted.md` | Not documented in fragments | +| `auth login --timeout` flag | `src/commands/auth/login.ts` (default 900s) | `auth.md` fragment | Not documented | +| `SENTRY_CLIENT_ID_BUILD` fallback | `src/lib/oauth.ts` — committed default client ID for SaaS | Not documented | Intentionally internal; no gap | +| OAuth scope `event:write` | `src/lib/oauth.ts` — in `OAUTH_SCOPES` | `DEVELOPMENT.md`, `self-hosted.md` | Both correctly show the scopes (generated) ✓ | +| Token storage host scoping | `src/lib/db/auth.ts` — tokens bound to host origin | Not mentioned in docs | Defense-in-depth measure not documented; users switching instances may be confused | +| `SENTRY_FORCE_ENV_TOKEN` | `src/lib/db/auth.ts` | `self-hosted.md` ✓, `DEVELOPMENT.md` ✓ | Covered | +| `sentry auth refresh --force` | `src/commands/auth/refresh.ts` | `auth.md` | Fragment has no example for `--force` specifically, but the command is documented | + +--- + +## I. Plugin/Skills Gaps + +| Gap | Source | Doc location | Details | +|-----|--------|--------------|---------| +| `~/.agents/` install path | `src/lib/agent-skills.ts` — installs to `~/.agents/skills/sentry-cli/` | `agentic-usage.md` — mentions `~/.agents` | Covered ✓ | +| `~/.claude/` install path | `src/lib/agent-skills.ts` — installs to `~/.claude/skills/sentry-cli/` | `agentic-usage.md` — mentions `~/.claude` | Covered ✓ | +| Cursor IDE support | `plugins/README.md` — `.cursor/skills/sentry-cli/` | `agentic-usage.md` | Says "Cursor" reads from `~/.agents` but doesn't mention `.cursor/skills/` in repo | +| Claude Code marketplace install | `plugins/README.md` — `claude plugin marketplace add getsentry/cli` | `agentic-usage.md` | Not mentioned; only `npx skills add` shown | +| Plugin manifest version | `plugins/sentry-cli/.claude-plugin/plugin.json` — version "0.35.0" | Not documented | Internal detail; no gap | +| `--no-agent-skills` flag | `src/commands/cli/setup.ts` | `agentic-usage.md` ✓ | Covered | +| Skills embedded in binary | `src/lib/agent-skills.ts` — reads from generated `skill-content.ts` | `agentic-usage.md` — says "No network fetch needed" | Covered ✓ | +| Skill refresh on upgrade | `src/commands/cli/upgrade.ts` → spawns `cli setup` | `agentic-usage.md` ✓ | Covered | + +--- + +## J. README / DEVELOPMENT.md Drift + +| Claim | File | Reality | Severity | +|-------|------|---------|----------| +| **"Bun v1.3+"** as dev prerequisite | `README.md` (generated section) | Build uses fossilize/Node SEA; runtime is Node.js ≥22.15; `packageManager` is pnpm. Bun is not a prerequisite. | **Critical** | +| **"Bun installed"** as prerequisite | `DEVELOPMENT.md` line 5 | Same as above | **Critical** | +| **"Building the native binary still requires Bun"** | `DEVELOPMENT.md` line 91 | Build uses `fossilize` (Node SEA), esbuild for bundling. No Bun dependency. | **Critical** | +| **"Bun runtime (v1.3 or later)"** | `contributing.md` (generated) | Same as above | **Critical** | +| `pnpm run dev` description | `AGENTS.md` | `package.json` script `dev` runs generate + tsx — correct ✓ | N/A | +| `pnpm test` runs unit tests | `AGENTS.md` | `package.json`: `"test": "pnpm run test:unit"` — correct ✓ | N/A | +| OAuth scopes | `DEVELOPMENT.md` (generated) | Matches `src/lib/oauth.ts` — correct ✓ | N/A | +| License "FSL-1.1-Apache-2.0" | `README.md` | Matches `package.json` ✓ | N/A | +| Node.js engine `>=22.15` | `package.json` | README library usage says "Node.js (≥22.15)" — correct ✓ | N/A | +| `git clone https://github.com/getsentry/cli.git` | `README.md`, `contributing.md` | Matches `package.json` repository URL ✓ | N/A | + +--- + +## Top 5 Most Impactful Fixes (Prioritized) + +### 1. Fix Bun prerequisite in doc generator (Critical) + +**File:** `script/generate-docs-sections.ts` + +The `generateDevPrereq()` function hard-codes "Bun" as a prerequisite. The build +pipeline uses fossilize (Node SEA) + esbuild. The runtime is Node.js. This affects +`README.md`, `DEVELOPMENT.md`, and `contributing.md` via generated sections. + +**Fix:** Update `generateDevPrereq()` to reference Node.js ≥22.15 and pnpm instead +of Bun. Update the non-generated parts of `DEVELOPMENT.md` that mention Bun. + +### 2. Add missing subcommand examples to fragments (High) + +**Files:** `docs/src/fragments/commands/dashboard.md`, `issue.md`, `cli.md` + +Three subcommands have zero documentation in fragments: +- `sentry dashboard revisions` / `sentry dashboard restore` +- `sentry issue events` +- `sentry cli import` + +### 3. Document `auth login` flags in fragment (High) + +**File:** `docs/src/fragments/commands/auth.md` + +The `--url`, `--timeout`, and `--force` flags for `sentry auth login` are important +for self-hosted users and automation but have no examples in the auth fragment. + +### 4. Document install script flags and env vars in getting-started (Medium) + +**File:** `docs/src/content/docs/getting-started.mdx` + +The install script accepts `--no-modify-path`, `--no-completions`, `--no-agent-skills`, +and the env vars `SENTRY_INSTALL_DIR` and `SENTRY_INIT`. These are useful for CI/Docker +but undocumented in getting-started. + +### 5. Add `@latest` / `@most_frequent` magic selectors to issue fragment (Medium) + +**File:** `docs/src/fragments/commands/issue.md` + +The issue route's `fullDescription` mentions `@latest` and `@most_frequent` selectors +for `sentry issue view @latest`, but no fragment documents them with examples. diff --git a/README.md b/README.md index 13ef12000..064994357 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ Credentials are stored in `~/.sentry/` with restricted permissions (mode 600). ## Library Usage -Use Sentry CLI programmatically in Node.js (≥22.15) or Bun without spawning a subprocess: +Use Sentry CLI programmatically in Node.js (≥22.15) without spawning a subprocess: ```typescript @@ -118,7 +118,7 @@ Errors are thrown as `SentryError` with `.exitCode` and `.stderr`. ### Prerequisites -- [Bun](https://bun.sh) v1.3+ +- [Node.js](https://nodejs.org) v22.15+ ### Setup diff --git a/docs/src/content/docs/contributing.md b/docs/src/content/docs/contributing.md index f6fad5c42..e95f96628 100644 --- a/docs/src/content/docs/contributing.md +++ b/docs/src/content/docs/contributing.md @@ -10,7 +10,7 @@ We welcome contributions to the Sentry CLI! This guide will help you get started ### Prerequisites -- [Bun](https://bun.sh) runtime (v1.3 or later) +- [Node.js](https://nodejs.org) v22.15 or later - Git diff --git a/script/generate-docs-sections.ts b/script/generate-docs-sections.ts index 9d594fa27..780ae8d76 100644 --- a/script/generate-docs-sections.ts +++ b/script/generate-docs-sections.ts @@ -261,39 +261,28 @@ function generateScopesInline(scopes: readonly string[]): string { // Section: Prerequisites (README.md, contributing.md) // --------------------------------------------------------------------------- -const BUN_VERSION_RE = /bun@(\d+\.\d+)/; const SEMVER_RE = /(\d+\.\d+)/; -/** - * Extract the Bun major.minor version from the `packageManager` field. - * `bun@1.3.13` → `1.3` - */ -function extractBunVersion(): string { - const pm: string = pkg.packageManager ?? ""; - const match = pm.match(BUN_VERSION_RE); - return match ? match[1] : "1.3"; -} - -/** Extract the Node.js minimum version from `engines.node` (e.g., `>=22.12` → `22.12`). */ +/** Extract the Node.js minimum version from `engines.node` (e.g., `>=22.15` → `22.15`). */ function extractNodeVersion(): string { - const constraint: string = pkg.engines?.node ?? ">=22.12"; + const constraint: string = pkg.engines?.node ?? ">=22.15"; const match = constraint.match(SEMVER_RE); - return match ? match[1] : "22.12"; + return match ? match[1] : "22.15"; } -/** Generate dev prerequisite line for README.md and contributing.md. */ +/** Generate dev prerequisite line for README.md. */ function generateDevPrereq(): string { - return `- [Bun](https://bun.sh) v${extractBunVersion()}+`; + return `- [Node.js](https://nodejs.org) v${extractNodeVersion()}+`; } /** Also used by contributing.md (same content, different phrasing). */ function generateDevPrereqContributing(): string { - return `- [Bun](https://bun.sh) runtime (v${extractBunVersion()} or later)`; + return `- [Node.js](https://nodejs.org) v${extractNodeVersion()} or later`; } /** Generate the library-usage prerequisite line for README.md. */ function generateLibraryPrereq(): string { - return `Use Sentry CLI programmatically in Node.js (≥${extractNodeVersion()}) or Bun without spawning a subprocess:`; + return `Use Sentry CLI programmatically in Node.js (≥${extractNodeVersion()}) without spawning a subprocess:`; } // --------------------------------------------------------------------------- From 228794f8031f67679ec262a9b10ca16aae2e29f5 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 25 May 2026 12:11:21 +0000 Subject: [PATCH 2/3] docs: add missing subcommand examples and flag documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add dashboard revisions/restore examples to dashboard.md fragment - Add issue events subcommand and @latest/@most_frequent selectors to issue.md - Add cli defaults and cli import examples to cli.md fragment - Document auth login --url, --force, --timeout flags in auth.md - Document install script flags and env vars in getting-started.mdx Co-authored-by: Miguel Betegón --- docs/src/content/docs/getting-started.mdx | 23 ++++++++++++ docs/src/fragments/commands/auth.md | 21 ++++++++--- docs/src/fragments/commands/cli.md | 46 +++++++++++++++++++++++ docs/src/fragments/commands/dashboard.md | 23 ++++++++++++ docs/src/fragments/commands/issue.md | 35 +++++++++++++++++ 5 files changed, 143 insertions(+), 5 deletions(-) diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx index b71060cd7..ea7d8f79c 100644 --- a/docs/src/content/docs/getting-started.mdx +++ b/docs/src/content/docs/getting-started.mdx @@ -36,6 +36,29 @@ 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. +#### Install Script Options + +The install script accepts these flags (passed after `--`): + +```bash +# Skip PATH modification (e.g., in CI where PATH is managed externally) +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 agent skill installation (for Claude Code, Cursor, etc.) +curl https://cli.sentry.dev/install -fsS | bash -s -- --no-agent-skills +``` + +Environment variables: + +| Variable | Description | +|----------|-------------| +| `SENTRY_VERSION` | Pin version (e.g., `0.19.0`) or channel (`nightly`) | +| `SENTRY_INSTALL_DIR` | Override binary install directory (default: `~/.sentry/bin`) | +| `SENTRY_INIT` | Set to `1` to run `sentry init` after install | + #### Supported Platforms {/* GENERATED:START platform-support */} diff --git a/docs/src/fragments/commands/auth.md b/docs/src/fragments/commands/auth.md index 9d5afa16b..7dcb24ff2 100644 --- a/docs/src/fragments/commands/auth.md +++ b/docs/src/fragments/commands/auth.md @@ -22,17 +22,28 @@ sentry auth login --token YOUR_SENTRY_API_TOKEN ### Self-hosted Sentry +The `--url` flag is required when first connecting to a self-hosted instance. +This registers the host as trusted so subsequent commands don't need the flag: + ```bash -SENTRY_URL=https://sentry.example.com sentry auth login +# OAuth login to a self-hosted instance (requires --url on first use) +sentry auth login --url https://sentry.example.com + +# Token-based auth with self-hosted +sentry auth login --token YOUR_TOKEN --url https://sentry.example.com ``` -For token-based auth with self-hosted: +See [Self-Hosted Sentry](../self-hosted/) for details. + +### Re-authenticate and timeouts ```bash -SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN -``` +# Force re-authentication (skip "already logged in" prompt) +sentry auth login --force -See [Self-Hosted Sentry](../self-hosted/) for details. +# Set a custom timeout for the OAuth flow (default: 900 seconds) +sentry auth login --timeout 300 +``` ### Logout diff --git a/docs/src/fragments/commands/cli.md b/docs/src/fragments/commands/cli.md index a0aa5bc21..7bd3f1afc 100644 --- a/docs/src/fragments/commands/cli.md +++ b/docs/src/fragments/commands/cli.md @@ -91,3 +91,49 @@ sentry cli setup --no-agent-skills # Skip PATH and completion modifications sentry cli setup --no-modify-path --no-completions ``` + +### View and manage defaults + +```bash +# Show all current defaults +sentry cli defaults + +# Set default organization +sentry cli defaults org my-org + +# Set default project +sentry cli defaults project my-project + +# Set Sentry URL (self-hosted) +sentry cli defaults url https://sentry.example.com + +# Disable telemetry +sentry cli defaults telemetry off + +# Clear a specific default +sentry cli defaults org --clear + +# Clear all defaults (with confirmation) +sentry cli defaults --clear +``` + +See [Configuration](../configuration/#persistent-defaults) for more details on defaults. + +### Import settings from legacy `.sentryclirc` + +```bash +# Scan for and import legacy .sentryclirc settings +sentry cli import + +# Preview what would be imported +sentry cli import --dry-run + +# Skip confirmation prompts +sentry cli import --yes + +# Trust a specific self-hosted URL during import +sentry cli import --url https://sentry.example.com + +# Skip API validation of the imported token +sentry cli import --skip-validation +``` diff --git a/docs/src/fragments/commands/dashboard.md b/docs/src/fragments/commands/dashboard.md index a532548a9..0f2e5d307 100644 --- a/docs/src/fragments/commands/dashboard.md +++ b/docs/src/fragments/commands/dashboard.md @@ -108,6 +108,29 @@ sentry dashboard widget delete 'My Dashboard' --title 'Error Count' sentry dashboard widget delete 12345 --index 2 ``` +### View revision history + +```bash +# List revisions for a dashboard +sentry dashboard revisions 'Frontend Performance' + +# By dashboard ID +sentry dashboard revisions 12345 + +# Paginate through revision history +sentry dashboard revisions 12345 -c next +``` + +### Restore a previous revision + +```bash +# Restore a specific revision (use `revisions` to find the revision ID) +sentry dashboard restore 'Frontend Performance' --revision 3 + +# Restore by dashboard ID +sentry dashboard restore 12345 --revision 1 +``` + ## Query Shorthand The `--query` flag supports shorthand for aggregate functions: diff --git a/docs/src/fragments/commands/issue.md b/docs/src/fragments/commands/issue.md index db8b3a5fd..bf6ca8105 100644 --- a/docs/src/fragments/commands/issue.md +++ b/docs/src/fragments/commands/issue.md @@ -79,6 +79,41 @@ Latest event: sentry issue view FRONT-ABC -w ``` +### List events for an issue + +```bash +# List recent events for an issue +sentry issue events FRONT-ABC + +# With search filter +sentry issue events FRONT-ABC --query "browser:Chrome" + +# Include full event body with stacktraces +sentry issue events FRONT-ABC --full + +# Limit and time range +sentry issue events FRONT-ABC --limit 50 --period 24h + +# Paginate through events +sentry issue events FRONT-ABC -c next +``` + +### Magic selectors + +Use `@latest` and `@most_frequent` to quickly access common issues without looking up IDs: + +```bash +# View the most recently seen issue +sentry issue view @latest + +# Explain the most frequently occurring issue +sentry issue explain @most_frequent + +# Works with any issue subcommand +sentry issue plan @latest +sentry issue events @latest --limit 5 +``` + ### Explain and plan with Seer AI ```bash From 6a18bb42f4bc2638b5d707fabac9b16f06b90f59 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 25 May 2026 12:12:38 +0000 Subject: [PATCH 3/3] chore: regenerate docs --- .../skills/sentry-cli/references/auth.md | 12 ++++- .../skills/sentry-cli/references/cli.md | 44 +++++++++++++++++++ .../skills/sentry-cli/references/dashboard.md | 23 ++++++++++ .../skills/sentry-cli/references/issue.md | 29 ++++++++++++ 4 files changed, 106 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 1b06207f7..9e4e8bb56 100644 --- a/plugins/sentry-cli/skills/sentry-cli/references/auth.md +++ b/plugins/sentry-cli/skills/sentry-cli/references/auth.md @@ -28,9 +28,17 @@ sentry auth login sentry auth login --token YOUR_SENTRY_API_TOKEN -SENTRY_URL=https://sentry.example.com sentry auth login +# OAuth login to a self-hosted instance (requires --url on first use) +sentry auth login --url https://sentry.example.com -SENTRY_URL=https://sentry.example.com sentry auth login --token YOUR_TOKEN +# Token-based auth with self-hosted +sentry auth login --token YOUR_TOKEN --url https://sentry.example.com + +# Force re-authentication (skip "already logged in" prompt) +sentry auth login --force + +# Set a custom timeout for the OAuth flow (default: 900 seconds) +sentry auth login --timeout 300 ``` ### `sentry auth logout` diff --git a/plugins/sentry-cli/skills/sentry-cli/references/cli.md b/plugins/sentry-cli/skills/sentry-cli/references/cli.md index 4ba56845d..a3e47e883 100644 --- a/plugins/sentry-cli/skills/sentry-cli/references/cli.md +++ b/plugins/sentry-cli/skills/sentry-cli/references/cli.md @@ -20,6 +20,31 @@ View and manage default settings - `-y, --yes - Skip confirmation prompt` - `-f, --force - Force the operation without confirmation` +**Examples:** + +```bash +# Show all current defaults +sentry cli defaults + +# Set default organization +sentry cli defaults org my-org + +# Set default project +sentry cli defaults project my-project + +# Set Sentry URL (self-hosted) +sentry cli defaults url https://sentry.example.com + +# Disable telemetry +sentry cli defaults telemetry off + +# Clear a specific default +sentry cli defaults org --clear + +# Clear all defaults (with confirmation) +sentry cli defaults --clear +``` + ### `sentry cli feedback ` Send feedback about the CLI @@ -57,6 +82,25 @@ Import settings from legacy .sentryclirc files - `--url - Explicitly trust this URL (bypasses same-file trust check)` - `--skip-validation - Skip token validation against the Sentry API` +**Examples:** + +```bash +# Scan for and import legacy .sentryclirc settings +sentry cli import + +# Preview what would be imported +sentry cli import --dry-run + +# Skip confirmation prompts +sentry cli import --yes + +# Trust a specific self-hosted URL during import +sentry cli import --url https://sentry.example.com + +# Skip API validation of the imported token +sentry cli import --skip-validation +``` + ### `sentry cli setup` Configure shell integration diff --git a/plugins/sentry-cli/skills/sentry-cli/references/dashboard.md b/plugins/sentry-cli/skills/sentry-cli/references/dashboard.md index 4a8df0d38..ab6470704 100644 --- a/plugins/sentry-cli/skills/sentry-cli/references/dashboard.md +++ b/plugins/sentry-cli/skills/sentry-cli/references/dashboard.md @@ -175,6 +175,19 @@ List dashboard revisions - `-n, --limit - Maximum number of revisions to list - (default: "25")` - `-c, --cursor - Navigate pages: "next", "prev", "first" (or raw cursor string)` +**Examples:** + +```bash +# List revisions for a dashboard +sentry dashboard revisions 'Frontend Performance' + +# By dashboard ID +sentry dashboard revisions 12345 + +# Paginate through revision history +sentry dashboard revisions 12345 -c next +``` + ### `sentry dashboard restore ` Restore a dashboard revision @@ -182,4 +195,14 @@ Restore a dashboard revision **Flags:** - `-r, --revision - Revision ID to restore` +**Examples:** + +```bash +# Restore a specific revision (use `revisions` to find the revision ID) +sentry dashboard restore 'Frontend Performance' --revision 3 + +# Restore by dashboard ID +sentry dashboard restore 12345 --revision 1 +``` + All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags. diff --git a/plugins/sentry-cli/skills/sentry-cli/references/issue.md b/plugins/sentry-cli/skills/sentry-cli/references/issue.md index 448b6546b..423ecd6b5 100644 --- a/plugins/sentry-cli/skills/sentry-cli/references/issue.md +++ b/plugins/sentry-cli/skills/sentry-cli/references/issue.md @@ -111,6 +111,35 @@ List events for a specific issue | `crashFile` | string \| null | Crash file URL | | `metadata` | object \| null | Event metadata | +**Examples:** + +```bash +# List recent events for an issue +sentry issue events FRONT-ABC + +# With search filter +sentry issue events FRONT-ABC --query "browser:Chrome" + +# Include full event body with stacktraces +sentry issue events FRONT-ABC --full + +# Limit and time range +sentry issue events FRONT-ABC --limit 50 --period 24h + +# Paginate through events +sentry issue events FRONT-ABC -c next + +# View the most recently seen issue +sentry issue view @latest + +# Explain the most frequently occurring issue +sentry issue explain @most_frequent + +# Works with any issue subcommand +sentry issue plan @latest +sentry issue events @latest --limit 5 +``` + ### `sentry issue explain ` Analyze an issue's root cause using Seer AI