diff --git a/AGENTS.md b/AGENTS.md index 0141e32f4..993153b87 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,29 +1,10 @@ -# Jared (Outpost agent) +# AGENTS.md -Autonomous GitHub coding agent. Work in `/workspace/repo`. +This repository is a pnpm workspace. Guidelines for AI agents working on the +Sentry CLI live in [`packages/cli/AGENTS.md`](packages/cli/AGENTS.md). -## Model tiers + +## Long-term Knowledge -The primary model is chosen per event (see `src/agents/models.ts`): heavy for -code-producing situations, cheaper for lightweight ones. - -| Role | Subagent | Model | -| --- | --- | --- | -| Triage / plan / review (heavy) | (primary Jared) | Claude Opus 4.8 | -| Triage / plan / review (light) | (primary Jared) | xAI Grok 4.3 | -| Explore | `explore` | OpenAI gpt-5-mini | -| Implement | `implement` | Moonshot kimi-k2.7-code | -| Ship (commit/push/PR) | `ship` | xAI Grok (`grok-build-0.1`) | - -Pipeline: triage → explore → plan → implement → review → ship. -(`worker` is a deprecated alias of `implement`.) - -Operators also talk to Jared directly from the Outpost dashboard. Those turns -(`New operator chat` / `Operator guidance:`) skip triage — treat the request as -the task and answer in the conversation. - -Long-term project knowledge for *this* Outpost repo lives in `.lore.md` when present. -For target repositories, read their `AGENTS.md` / `CONTRIBUTING.md` first. - -Skills are under `.agents/skills/`, generated from the canonical `skills/` tree -by `scripts/sync-skills.mjs`. Always load `repo-setup` before situation skills. +For long-term knowledge entries managed by [lore](https://github.com/BYK/loreai) (gotchas, patterns, decisions, architecture), see [`.lore.md`](.lore.md) in the project root. + diff --git a/README.md b/README.md index a201255c5..e46e55f76 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ the Sentry CLI and Sentry MCP server into a single `getsentry/toolkit` monorepo. binary `sentry`). See [packages/cli/README.md](./packages/cli/README.md). - [`apps/cli-docs/`](./apps/cli-docs) — the CLI documentation site (Astro + Starlight, published to `cli.sentry.dev`). +- [`apps/local/`](./apps/local) — the Sentry Local UI used by `sentry local --open` + (Vite + React, published to `local.sentry.dev`). ## Development diff --git a/apps/cli-docs/src/content/docs/agent-guidance.md b/apps/cli-docs/src/content/docs/agent-guidance.md index d9b4eb20e..f5f99366a 100644 --- a/apps/cli-docs/src/content/docs/agent-guidance.md +++ b/apps/cli-docs/src/content/docs/agent-guidance.md @@ -34,7 +34,7 @@ The `sentry` CLI follows conventions from well-known tools — if you're familia ## Safety Rules -- Always confirm with the user before running destructive commands: `project delete`, `trial start` +- Always confirm with the user before running destructive commands: `project delete`, `release delete`, `alert issues delete`, `alert metrics delete`, `dashboard widget delete`, `issue merge`, `trial start` - For mutations, verify the org/project context looks correct in the command output before proceeding with further changes - Never store or log authentication tokens — the CLI manages credentials automatically - If the CLI reports the wrong org/project, override with explicit `/` arguments diff --git a/apps/cli-docs/src/content/docs/agentic-usage.md b/apps/cli-docs/src/content/docs/agentic-usage.md index 81012bb0a..53e0aa3b5 100644 --- a/apps/cli-docs/src/content/docs/agentic-usage.md +++ b/apps/cli-docs/src/content/docs/agentic-usage.md @@ -3,15 +3,15 @@ title: Agentic Usage description: Enable AI coding agents to use the Sentry CLI --- -AI coding agents can use the Sentry CLI through the skill system. The CLI detects and supports Claude Code (including Cowork), Cursor, Windsurf, GitHub Copilot, Gemini CLI, OpenAI Codex, Goose, Amp, Augment, OpenCode, Cline, Grok, Kimi, Junie, OpenClaw, and any agent that reads skills from `~/.agents`. This allows agents to interact with Sentry directly from your development environment. +AI coding agents can use the Sentry CLI through the skill system. The CLI detects and supports Claude Code (including Cowork), Cursor, Windsurf, GitHub Copilot, Gemini CLI, OpenAI Codex, Antigravity, Goose, Amp, Augment, OpenCode, Cline, Grok, Kimi, Junie, OpenClaw, and any agent that reads skills from `~/.agents`. This allows agents to interact with Sentry directly from your development environment. ## 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. +`sentry cli setup` installs the agent skill into the `~/.claude` and `~/.agents` directories when they already exist (the CLI never creates them). The install script and Homebrew run setup for you; after an npm, pnpm, yarn, or bun install, run `sentry cli setup` once. Skills are also refreshed on `sentry cli upgrade`. No network fetch is needed — skill files are embedded in the binary. This uses the same `~/.agents` convention as [dotagents](https://github.com/getsentry/dotagents), Sentry's first-party tool for installing agent skills. See [Manual Installation](#manual-installation) to add the skill with dotagents yourself. -To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli setup`. +To skip automatic skill installation, pass `--no-agent-skills` to the install script, `sentry cli setup`, or `sentry cli upgrade`. The opt-out is remembered for future upgrades; turn installation back on with `sentry cli defaults agent-skills on`. ## Manual Installation diff --git a/apps/cli-docs/src/content/docs/contributing.md b/apps/cli-docs/src/content/docs/contributing.md index 3e932f7cc..7106fc461 100644 --- a/apps/cli-docs/src/content/docs/contributing.md +++ b/apps/cli-docs/src/content/docs/contributing.md @@ -25,8 +25,12 @@ cd cli # Install dependencies pnpm install +# Generate build-time files (API schema, search parser, docs, skills) +pnpm run generate:schema +pnpm run generate:docs + # Run CLI in development mode -pnpm run cli -- --help +pnpm run cli --help # Run tests pnpm run test @@ -37,16 +41,22 @@ pnpm run test Create a `.env.local` file for development: ```bash -cp .env.example .env.local +cp packages/cli/.env.example packages/cli/.env.local ``` -Edit `.env.local` with your development credentials. +Edit `.env.local` with your development credentials. `pnpm run cli` loads it +automatically. See [DEVELOPMENT.md](https://github.com/getsentry/cli/blob/main/packages/cli/DEVELOPMENT.md) +for when `SENTRY_CLIENT_ID` is needed. ## Project Structure +The repository is a pnpm workspace. The CLI lives in `packages/cli/`, the +documentation site (Astro + Starlight) in `apps/cli-docs/`, and the Sentry +Local UI in `apps/local/`. + ``` -cli/ +packages/cli/ ├── src/ │ ├── bin.ts # Entry point │ ├── app.ts # Stricli application setup @@ -94,8 +104,7 @@ cli/ │ └── types/ # TypeScript types and Valibot schemas ├── test/ # Test files (mirrors src/ structure) ├── script/ # Build and utility scripts -├── plugins/ # Agent skill files -└── docs/ # Documentation site (Astro + Starlight) +└── plugins/ # Agent skill files ``` @@ -117,17 +126,18 @@ pnpm run bundle ## Testing ```bash -# Run all tests +# Run all unit tests (regenerates docs and the SDK first, with coverage) pnpm run test -# Run specific test file -pnpm run test -- test/path/to/test.ts +# Run a specific test file (path relative to packages/cli; skips the +# generate steps, so run `pnpm run test` once first) +pnpm --filter sentry exec vitest run test/path/to/test.ts -# Run with watch mode -pnpm run test -- --watch +# Run in watch mode +pnpm --filter sentry exec vitest -# Run with coverage -pnpm run test -- --coverage +# Run end-to-end tests +pnpm run test:e2e ``` ## Code Style diff --git a/apps/cli-docs/src/content/docs/getting-started.mdx b/apps/cli-docs/src/content/docs/getting-started.mdx index 42324ea60..d4e49faef 100644 --- a/apps/cli-docs/src/content/docs/getting-started.mdx +++ b/apps/cli-docs/src/content/docs/getting-started.mdx @@ -20,17 +20,18 @@ curl https://cli.sentry.dev/install -fsS | bash -s -- --version nightly ``` You can also use the `SENTRY_VERSION` environment variable to pin a version, -which is especially useful in CI/CD pipelines and Dockerfiles: +which is especially useful in CI/CD pipelines and Dockerfiles. Set it on the +`bash` side of the pipe (or `export` it) so the installer can read it: ```bash # Pin to a specific stable version -SENTRY_VERSION=0.42.2 curl https://cli.sentry.dev/install -fsS | bash +curl https://cli.sentry.dev/install -fsS | SENTRY_VERSION=0.42.2 bash # Pin to nightly -SENTRY_VERSION=nightly curl https://cli.sentry.dev/install -fsS | bash +curl https://cli.sentry.dev/install -fsS | SENTRY_VERSION=nightly bash ``` -The `--version` flag takes precedence over `SENTRY_VERSION` if both are set. +The `--version` flag (short form `-v`) 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. @@ -52,9 +53,17 @@ 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 +curl https://cli.sentry.dev/install -fsS | SENTRY_INSTALL_DIR=~/.local/bin bash ``` +Set `SENTRY_INIT=1` to launch the [`sentry init`](../commands/init/) setup wizard right after installation: + +```bash +curl https://cli.sentry.dev/install -fsS | SENTRY_INIT=1 bash +``` + +The install script reports installation failures to Sentry. Set `SENTRY_CLI_NO_TELEMETRY=1` to opt out. + ### Supported Platforms {/* GENERATED:START platform-support */} @@ -172,13 +181,15 @@ 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? Pass its URL with `--url` when you log in: ```bash -SENTRY_URL=https://sentry.example.com sentry auth +sentry auth login --url https://sentry.example.com ``` -See the [Self-Hosted](../self-hosted/) guide for full setup details. +`--url` saves the instance as your default URL, so later commands don't need +`SENTRY_URL`. OAuth login on self-hosted also requires `SENTRY_CLIENT_ID`; see +the [Self-Hosted](../self-hosted/) guide for full setup details. ## Configuration diff --git a/apps/cli-docs/src/content/docs/self-hosted.md b/apps/cli-docs/src/content/docs/self-hosted.md index 4301ef43e..ee58b1512 100644 --- a/apps/cli-docs/src/content/docs/self-hosted.md +++ b/apps/cli-docs/src/content/docs/self-hosted.md @@ -20,7 +20,7 @@ The OAuth device flow requires **Sentry 26.1.0 or later** and a public OAuth app 1. In your Sentry instance, go to **Settings → Developer Settings → Applications → Create New Application** (or visit `https://sentry.example.com/settings/account/api/applications/`) 2. Select **Public** as the application type 3. Fill in the required fields (name, redirect URL — can be any placeholder URL) -3. Save the application and copy the **Client ID** +4. Save the application and copy the **Client ID** #### 2. Log In @@ -66,13 +66,19 @@ SENTRY_HOST=https://sentry.example.com sentry auth login --token YOUR_TOKEN ## After Login -Once authenticated, the CLI stores your instance URL — you don't need to set `SENTRY_URL` on every command. All subsequent commands automatically use the correct instance: +When you log in with `--url`, the CLI saves the instance URL as your default (the same setting as `sentry cli defaults url`), so you don't need to set `SENTRY_HOST` or `SENTRY_URL` on every command. All subsequent commands automatically use the correct instance: ```bash sentry issue list sentry org list ``` +If you logged in by setting `SENTRY_HOST`/`SENTRY_URL` instead, the URL is not saved. Keep the variable set, or persist it: + +```bash +sentry cli defaults url https://sentry.example.com +``` + If you pass a self-hosted Sentry URL as a command argument (e.g., an issue or event URL), the CLI detects the instance automatically. ## TLS / Corporate Proxies diff --git a/apps/cli-docs/src/fragments/commands/alert.md b/apps/cli-docs/src/fragments/commands/alert.md index ee32b001f..3e014947d 100644 --- a/apps/cli-docs/src/fragments/commands/alert.md +++ b/apps/cli-docs/src/fragments/commands/alert.md @@ -49,8 +49,8 @@ sentry alert issues delete my-org/my-project/12345 --dry-run ### Create a metric alert rule ```bash -# Create an organization metric alert rule -sentry alert metrics create my-org \ +# Create an organization metric alert rule (trailing slash targets the org) +sentry alert metrics create my-org/ \ --name "P95 Latency" \ --query "environment:prod" \ --aggregate "p95(span.duration)" \ diff --git a/apps/cli-docs/src/fragments/commands/auth.md b/apps/cli-docs/src/fragments/commands/auth.md index ecf464b5c..81b95f368 100644 --- a/apps/cli-docs/src/fragments/commands/auth.md +++ b/apps/cli-docs/src/fragments/commands/auth.md @@ -57,6 +57,10 @@ For token-based auth with self-hosted: sentry auth --token YOUR_TOKEN --url https://sentry.example.com ``` +After a successful login, `--url` is saved as the default instance URL. A URL +supplied only through `SENTRY_URL` is not saved, so keep it set for later +commands. + See [Self-Hosted Sentry](../self-hosted/) for details. ### Logout diff --git a/apps/cli-docs/src/fragments/commands/cli.md b/apps/cli-docs/src/fragments/commands/cli.md index 9053b9483..b98b5d63f 100644 --- a/apps/cli-docs/src/fragments/commands/cli.md +++ b/apps/cli-docs/src/fragments/commands/cli.md @@ -57,7 +57,8 @@ The CLI detects how it was installed and uses the appropriate upgrade method: | brew | Binary in a Homebrew Cellar (`brew install getsentry/tools/sentry`) | | npm | Globally installed via `npm install -g sentry` | | pnpm | Globally installed via `pnpm add -g sentry` | -| bun | Globally installed via `bun install -g sentry` | +| bun | Globally installed via `bun add -g sentry` | +| yarn | Globally installed via `yarn global add sentry` | Nightly builds are only available as standalone binaries (via the curl install method). Switching to nightly from a package manager install will automatically migrate to a standalone binary. @@ -85,6 +86,12 @@ sentry cli defaults ca-cert /path/to/ca.pem # Disable telemetry sentry cli defaults telemetry off +# Stop installing agent skills on setup/upgrade (re-enable with "on") +sentry cli defaults agent-skills off + +# Disable inline terminal images (kitty/sixel) +sentry cli defaults graphics off + # Clear a single default sentry cli defaults org --clear @@ -149,7 +156,7 @@ sentry cli completion fish > ~/.config/fish/completions/sentry.fish # Run full setup (PATH, completions, agent skills) sentry cli setup -# Skip agent skill installation +# Skip agent skill installation (remembered for future upgrades) sentry cli setup --no-agent-skills # Skip PATH and completion modifications diff --git a/apps/cli-docs/src/fragments/commands/index.md b/apps/cli-docs/src/fragments/commands/index.md index d1ab7faf7..c8a21c12e 100644 --- a/apps/cli-docs/src/fragments/commands/index.md +++ b/apps/cli-docs/src/fragments/commands/index.md @@ -9,6 +9,19 @@ All commands support the following global options: - `--log-level ` - Set log verbosity (`error`, `warn`, `log`, `info`, `debug`, `trace`). Overrides `SENTRY_LOG_LEVEL` - `--verbose` - Shorthand for `--log-level debug` +## Targeting Organizations and Projects + +Many commands accept an optional `/` target, either as the first positional argument (list commands) or as a prefix of an ID (e.g. `my-org/my-project/`). When you omit it, the CLI auto-detects the org and project (see [Resolution Priority](../configuration/#resolution-priority)). + +| Target | Meaning | +|--------|---------| +| _(omitted)_ | Auto-detect org and project | +| `/` | That project in that organization | +| `/` | The whole organization (trailing slash) | +| `` | A project named `` in any accessible organization. If no project matches, commands that accept an organization use the org named `` instead | + +When a project and an organization share the same slug, the bare form selects the project. Add the trailing slash (`my-org/`) to target the organization explicitly. + ## JSON Output Most list and view commands support `--json` flag for JSON output, making it easy to integrate with other tools: diff --git a/apps/cli-docs/src/fragments/commands/init.md b/apps/cli-docs/src/fragments/commands/init.md index 12cf0eff5..9daf08330 100644 --- a/apps/cli-docs/src/fragments/commands/init.md +++ b/apps/cli-docs/src/fragments/commands/init.md @@ -39,7 +39,7 @@ sentry init --features profiling,replay | _(omitted)_ | Auto-detect org and project | | `acme/` | Use org `acme`, auto-detect or create project | | `acme/my-app` | Use org `acme` and project `my-app` | -| `my-app` | Search for project `my-app` across all accessible orgs | +| `my-app` | Use existing project `my-app` from any accessible org; if none exists, use org `my-app` when one matches, otherwise create a new project named `my-app` | Path-like arguments (starting with `.`, `/`, or `~`) are always treated as the directory. The order of target and directory can be swapped — the CLI will auto-correct with a warning. diff --git a/apps/cli-docs/src/fragments/configuration.md b/apps/cli-docs/src/fragments/configuration.md index b9673a933..518ad075b 100644 --- a/apps/cli-docs/src/fragments/configuration.md +++ b/apps/cli-docs/src/fragments/configuration.md @@ -61,15 +61,19 @@ If you previously used the legacy `sentry-cli` and have a `~/.sentryclirc` file, ## Persistent Defaults -Use `sentry cli defaults` to set persistent defaults for organization, project, URL, and telemetry. These are stored in the CLI's local database and apply to all commands. +Use `sentry cli defaults` to set persistent defaults for organization, project, Sentry URL, custom headers, CA certificate, telemetry, agent skill installation, and inline terminal graphics. These are stored in the CLI's local database and apply to all commands. ```bash -sentry cli defaults org my-org # Set default organization -sentry cli defaults project my-project # Set default project -sentry cli defaults url https://... # Set Sentry URL (self-hosted) -sentry cli defaults telemetry off # Disable telemetry -sentry cli defaults # Show all current defaults -sentry cli defaults org --clear # Clear a specific default +sentry cli defaults org my-org # Set default organization +sentry cli defaults project my-project # Set default project +sentry cli defaults url https://... # Set Sentry URL (self-hosted) +sentry cli defaults headers "X-IAP: token" # Custom HTTP headers (self-hosted) +sentry cli defaults ca-cert /path/to/ca.pem # Trust a custom CA certificate +sentry cli defaults telemetry off # Disable telemetry +sentry cli defaults agent-skills off # Stop installing agent skills on setup/upgrade +sentry cli defaults graphics off # Disable inline terminal images +sentry cli defaults # Show all current defaults +sentry cli defaults org --clear # Clear a specific default ``` See [`sentry cli defaults`](./commands/cli/#sentry-cli-defaults) for full usage. @@ -123,4 +127,4 @@ When installed via the install script, the CLI binary is placed in an XDG-aligne Older installs placed the binary in `~/.sentry/bin`. Running `sentry cli setup` moves an existing `~/.sentry/bin` binary into the resolved install directory (updating your `PATH` and recorded install metadata to match) and migrates any legacy `~/.sentry` config data (`cli.db`, `config.json`) into the XDG config directory. Both migrations are skipped when a binary or config already exists at the target. -`sentry upgrade` runs `setup` on the new binary, so it migrates too — but conservatively, because upgrade never edits your `PATH`. A legacy `~/.sentry/bin` binary is relocated to the XDG install directory **only when that directory is already on your `PATH`**, so the moved binary stays discoverable. If the XDG directory isn't on `PATH`, upgrade leaves the binary in place (a mislocated binary that vanished from `PATH` would break the command); run `sentry cli setup` explicitly to relocate it and update `PATH`. Legacy config data is migrated on upgrade regardless. +`sentry cli upgrade` runs `setup` on the new binary, so it migrates too — but conservatively, because upgrade never edits your `PATH`. A legacy `~/.sentry/bin` binary is relocated to the XDG install directory **only when that directory is already on your `PATH`**, so the moved binary stays discoverable. If the XDG directory isn't on `PATH`, upgrade leaves the binary in place (a mislocated binary that vanished from `PATH` would break the command); run `sentry cli setup` explicitly to relocate it and update `PATH`. Legacy config data is migrated on upgrade regardless. diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md index d238f2dd2..a50116ef7 100644 --- a/packages/cli/AGENTS.md +++ b/packages/cli/AGENTS.md @@ -38,8 +38,9 @@ Before working on this codebase, read the Cursor rules: ```bash # Development pnpm install # Install dependencies (from repo root) +pnpm run generate:schema # Fetch the API schema (needed once before cli/typecheck/test) pnpm run dev # Run CLI in dev mode -pnpm run cli -- # Run the CLI with arguments +pnpm run cli # Run the CLI with arguments # Build pnpm run build # Build for current platform @@ -102,9 +103,9 @@ const result = execFileSync("id", ["-u", "username"], { encoding: "utf-8", stdio ## Architecture -The full project-structure tree — including the live command/subcommand list and the -domain API modules — is generated from the route tree and lives in -[`apps/cli-docs/src/content/docs/contributing.md`](apps/cli-docs/src/content/docs/contributing.md) +The full project-structure tree — including the live command/subcommand list — is +generated from the route tree and lives in +[`apps/cli-docs/src/content/docs/contributing.md`](../../apps/cli-docs/src/content/docs/contributing.md) (the `project-structure` block produced by `script/generate-docs-sections.ts`). It is kept in sync automatically, so it is **not** duplicated here to avoid drift. For the current command list run `ls src/commands/` or `sentry --help`. @@ -428,11 +429,11 @@ Use `"date"` for timestamp-based sort (not `"time"`). Export sort types from the ### Generated Docs & Skills -All command docs and skill files are generated via `pnpm run generate:docs` (which runs `generate:command-docs` then `generate:skill`). This runs automatically as part of `dev`, `build`, `typecheck`, and `test` scripts. +All command docs and skill files are generated via `pnpm run generate:docs` (which runs `generate:banner`, `generate:parser`, `generate:command-docs`, `generate:skill`, then `generate:docs-sections`). This runs automatically as part of `dev`, `build`, `typecheck`, and `test` scripts. It needs `src/generated/api-schema.json`, so run `pnpm run generate:schema` first on a fresh checkout (`dev` and `build` do this for you). -- **Command docs** (`docs/src/content/docs/commands/*.md`) are **gitignored** and generated from CLI metadata + hand-written fragments in `docs/src/fragments/commands/`. +- **Command docs** (`apps/cli-docs/src/content/docs/commands/*.md`) and `configuration.md` are **gitignored** and generated from CLI metadata + hand-written fragments in `apps/cli-docs/src/fragments/`. - **Skill files** (`plugins/sentry-cli/skills/sentry-cli/`) are **committed** (consumed by external plugin systems) and auto-committed by CI when stale. -- Edit fragments in `docs/src/fragments/commands/` for custom examples and guides. +- Edit fragments in `apps/cli-docs/src/fragments/commands/` for custom examples and guides. - `pnpm run check:fragments` validates fragment ↔ route consistency. - Positional `placeholder` values must be descriptive: `"org/project/trace-id"` not `"args"`. @@ -1017,8 +1018,8 @@ vi.mock("./some-module", () => ({ | Add unit tests | `test/` (mirror `src/` structure) | | Add E2E tests | `test/e2e/` | | Test helpers | `test/model-based/helpers.ts` | -| Add documentation | `docs/src/content/docs/` | -| Hand-written command doc content | `docs/src/fragments/commands/` | +| Add documentation | `apps/cli-docs/src/content/docs/` (repo root) | +| Hand-written command doc content | `apps/cli-docs/src/fragments/commands/` (repo root) | ## Automated Fix PRs (BugBot / agents) @@ -1055,5 +1056,5 @@ duplication and staleness that caused five overlapping PRs to pile up: ## Long-term Knowledge -For long-term knowledge entries managed by [lore](https://github.com/BYK/loreai) (gotchas, patterns, decisions, architecture), see [`.lore.md`](.lore.md) in the project root. +For long-term knowledge entries managed by [lore](https://github.com/BYK/loreai) (gotchas, patterns, decisions, architecture), see [`.lore.md`](../../.lore.md) in the repository root. diff --git a/packages/cli/CONTRIBUTING.md b/packages/cli/CONTRIBUTING.md index 4397e3b86..6d1e8253c 100644 --- a/packages/cli/CONTRIBUTING.md +++ b/packages/cli/CONTRIBUTING.md @@ -19,7 +19,7 @@ sentry issue list [/] [--json] **Target syntax**: - `/` - Explicit organization and project (e.g., `my-org/frontend`) - `/` - All projects in the specified organization -- `` - Search for project by name across all accessible organizations +- `` - Search for project by name across all accessible organizations; when no project matches, commands that accept an organization fall back to an org with that slug - *(omit)* - Auto-detect from DSN or config **Rationale**: Positional arguments follow `gh` CLI conventions and are more concise than flags. diff --git a/packages/cli/DEVELOPMENT.md b/packages/cli/DEVELOPMENT.md index 2b68d8d48..3172264cd 100644 --- a/packages/cli/DEVELOPMENT.md +++ b/packages/cli/DEVELOPMENT.md @@ -6,32 +6,50 @@ - [Node.js](https://nodejs.org/) v22.15+ installed - [pnpm](https://pnpm.io/) v10.11+ installed -- A Sentry OAuth application (create one at https://sentry.io/settings/account/api/applications/) +- A Sentry OAuth application, only if you test against a self-hosted instance or your own OAuth app (create one at https://sentry.io/settings/account/api/applications/) ## Setup -1. Install dependencies: +1. Install dependencies (from the repository root): ```bash pnpm install ``` -2. Create a `.env.local` file in the project root: +2. Generate the build-time files the CLI imports (the API schema is fetched + from GitHub, so this needs network access): + +```bash +pnpm run generate:schema +pnpm run generate:docs +``` + +`typecheck`, `test:unit`, and `test:e2e` regenerate docs but not the API +schema, so run `generate:schema` again after changing the `@sentry/api` version. + +3. Optionally, create `packages/cli/.env.local` from the example file: + +```bash +cp packages/cli/.env.example packages/cli/.env.local +``` + +`pnpm run cli` loads `.env.local` automatically. Without `SENTRY_CLIENT_ID`, +local runs use the CLI's public sentry.io OAuth client ID. Set it when testing +against a self-hosted instance or your own OAuth app: ``` SENTRY_CLIENT_ID=your-sentry-oauth-client-id ``` -Get the client ID from your Sentry OAuth application settings. +`pnpm run build` and `pnpm run bundle` require `SENTRY_CLIENT_ID`, because the +value is baked into the built CLI. **Note:** No client secret is needed - the CLI uses OAuth 2.0 Device Authorization Grant (RFC 8628) which is designed for public clients. ## Running Locally -Load environment variables from `.env.local` (e.g. via `dotenv` or `export $(cat .env.local | xargs)`), then: - ```bash -pnpm run cli -- auth login +pnpm run cli auth login ``` ## Testing the Device Flow @@ -39,7 +57,7 @@ pnpm run cli -- auth login 1. Run the CLI login command: ```bash -pnpm run cli -- auth login +pnpm run cli auth login ``` 2. You'll see output like: diff --git a/packages/cli/README.md b/packages/cli/README.md index e3d41cce4..9896fb49e 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -39,6 +39,8 @@ bun add -g sentry > The npm/pnpm/yarn packages require Node.js 20+. On Node.js 22.15+ the CLI uses the built-in `node:sqlite`; on Node.js 20–22.14 it transparently falls back to a bundled WASM SQLite driver. +Package manager installs don't set up shell completions or agent skills. Run `sentry cli setup` once to enable them. + ### Run Without Installing ```bash @@ -134,16 +136,20 @@ Errors are thrown as `SentryError` with `.exitCode` and `.stderr`. git clone https://github.com/getsentry/cli.git cd cli pnpm install + +# Generate build-time files (API schema, search parser, docs, skills) +pnpm run generate:schema +pnpm run generate:docs ``` ### Running Locally ```bash # Run CLI in development mode -pnpm run cli -- --help +pnpm run cli --help -# With environment variables (create .env.local first, see DEVELOPMENT.md) -pnpm run cli -- --help +# Loads packages/cli/.env.local automatically when present (see DEVELOPMENT.md) +pnpm run cli auth status ``` ### Scripts diff --git a/packages/cli/install b/packages/cli/install index f8d15deb4..c848385e0 100755 --- a/packages/cli/install +++ b/packages/cli/install @@ -97,8 +97,8 @@ Examples: curl -fsSL https://cli.sentry.dev/install | SENTRY_INIT=1 bash curl -fsSL https://cli.sentry.dev/install | bash -s -- --version nightly curl -fsSL https://cli.sentry.dev/install | bash -s -- --version 0.42.2 - SENTRY_VERSION=nightly curl -fsSL https://cli.sentry.dev/install | bash - SENTRY_INSTALL_DIR=~/.local/bin curl -fsSL https://cli.sentry.dev/install | bash + curl -fsSL https://cli.sentry.dev/install | SENTRY_VERSION=nightly bash + curl -fsSL https://cli.sentry.dev/install | SENTRY_INSTALL_DIR=~/.local/bin bash EOF } diff --git a/packages/cli/plugins/README.md b/packages/cli/plugins/README.md index ff0afb95c..456cc2de0 100644 --- a/packages/cli/plugins/README.md +++ b/packages/cli/plugins/README.md @@ -6,9 +6,13 @@ Agent skills for using the Sentry CLI, following the [Agent Skills](https://gith ### Automatic (recommended) -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`. +`sentry cli setup` installs the skill into the `~/.claude` and `~/.agents` +directories when they already exist. The install script and Homebrew run setup +automatically; after an npm, pnpm, yarn, or bun install, run `sentry cli setup` +once. Skills are also refreshed on `sentry cli upgrade`. + +Pass `--no-agent-skills` to opt out. The choice is remembered for future +upgrades; re-enable with `sentry cli defaults agent-skills on`. ### dotagents @@ -19,9 +23,19 @@ the well-known source: npx @sentry/dotagents add https://cli.sentry.dev sentry-cli ``` +### skills + +```bash +npx skills add https://cli.sentry.dev +``` + +The docs site publishes the skill files and their discovery manifest under +`https://cli.sentry.dev/.well-known/skills/`. + ### Cursor -Skills are automatically available in `.cursor/skills/` for Cursor users. +The repository ships Cursor skill symlinks in +`packages/cli/.cursor/skills/sentry-cli/`, pointing at the files below. ### Other Agents @@ -48,13 +62,14 @@ The skill will guide the assistant to provide accurate CLI commands. ## Repository Structure ``` -cli/ # Repository root +packages/cli/ ├── .claude-plugin/ │ └── marketplace.json # Marketplace manifest ├── .cursor/ │ └── skills/ │ └── sentry-cli/ -│ └── SKILL.md # Symlink to plugins location +│ ├── SKILL.md # Symlink to plugins location +│ └── references # Symlink to plugins location ├── plugins/ │ ├── README.md # This file │ └── sentry-cli/ @@ -62,11 +77,15 @@ cli/ # Repository root │ │ └── plugin.json # Plugin manifest │ └── skills/ │ └── sentry-cli/ -│ └── SKILL.md # CLI usage skill (auto-generated) +│ ├── SKILL.md # CLI usage skill (auto-generated) +│ └── references/ # One file per command group (auto-generated) └── script/ - └── generate-skill.ts # Generates SKILL.md from CLI commands + └── generate-skill.ts # Generates SKILL.md and references/ ``` +The docs site serves the same files, plus the generated `index.json` discovery +manifest, from `apps/cli-docs/public/.well-known/skills/`. + ## Updating SKILL.md The SKILL.md file is **auto-generated** from the CLI's command definitions. Do not edit it manually. 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 34b5fde3d..ce545f2dd 100644 --- a/packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md +++ b/packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md @@ -46,7 +46,7 @@ The `sentry` CLI follows conventions from well-known tools — if you're familia ### Safety Rules -- Always confirm with the user before running destructive commands: `project delete`, `trial start` +- Always confirm with the user before running destructive commands: `project delete`, `release delete`, `alert issues delete`, `alert metrics delete`, `dashboard widget delete`, `issue merge`, `trial start` - For mutations, verify the org/project context looks correct in the command output before proceeding with further changes - Never store or log authentication tokens — the CLI manages credentials automatically - If the CLI reports the wrong org/project, override with explicit `/` arguments diff --git a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/alert.md b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/alert.md index 9d6525dae..12b70df2d 100644 --- a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/alert.md +++ b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/alert.md @@ -166,8 +166,8 @@ Create a metric alert rule **Examples:** ```bash -# Create an organization metric alert rule -sentry alert metrics create my-org \ +# Create an organization metric alert rule (trailing slash targets the org) +sentry alert metrics create my-org/ \ --name "P95 Latency" \ --query "environment:prod" \ --aggregate "p95(span.duration)" \ diff --git a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/cli.md b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/cli.md index 2d9b28f38..63ef28ff8 100644 --- a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/cli.md +++ b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/cli.md @@ -60,6 +60,12 @@ sentry cli defaults ca-cert /path/to/ca.pem # Disable telemetry sentry cli defaults telemetry off +# Stop installing agent skills on setup/upgrade (re-enable with "on") +sentry cli defaults agent-skills off + +# Disable inline terminal images (kitty/sixel) +sentry cli defaults graphics off + # Clear a single default sentry cli defaults org --clear @@ -129,7 +135,7 @@ Configure shell integration **Flags:** - `--install - Install the binary from a temp location to the system path` -- `--method - Installation method (curl, npm, pnpm, bun, yarn)` +- `--method - Installation method (curl, brew, npm, pnpm, bun, yarn)` - `--channel - Release channel to persist (stable or nightly)` - `--no-modify-path - Skip PATH modification` - `--no-completions - Skip shell completion installation` @@ -142,7 +148,7 @@ Configure shell integration # Run full setup (PATH, completions, agent skills) sentry cli setup -# Skip agent skill installation +# Skip agent skill installation (remembered for future upgrades) sentry cli setup --no-agent-skills # Skip PATH and completion modifications @@ -154,7 +160,7 @@ sentry cli setup --no-modify-path --no-completions Uninstall Sentry CLI **Flags:** -- `--keep-config - Keep the config directory (~/.sentry) and auth tokens` +- `--keep-config - Keep the config directory (default ~/.config/sentry) and auth tokens` - `-y, --yes - Skip confirmation prompt` - `-f, --force - Force the operation without confirmation` - `-n, --dry-run - Show what would happen without making changes` diff --git a/packages/cli/script/generate-docs-sections.ts b/packages/cli/script/generate-docs-sections.ts index 782cf2718..edd4a0971 100644 --- a/packages/cli/script/generate-docs-sections.ts +++ b/packages/cli/script/generate-docs-sections.ts @@ -157,7 +157,7 @@ function getSubcommandLabel(route: RouteInfo): string { function generateProjectStructure(allRoutes: RouteInfo[]): string { const lines: string[] = []; lines.push("```"); - lines.push("cli/"); + lines.push("packages/cli/"); lines.push("├── src/"); lines.push("│ ├── bin.ts # Entry point"); lines.push("│ ├── app.ts # Stricli application setup"); @@ -210,10 +210,7 @@ function generateProjectStructure(allRoutes: RouteInfo[]): string { lines.push("│ └── types/ # TypeScript types and Valibot schemas"); lines.push("├── test/ # Test files (mirrors src/ structure)"); lines.push("├── script/ # Build and utility scripts"); - lines.push("├── plugins/ # Agent skill files"); - lines.push( - "└── docs/ # Documentation site (Astro + Starlight)" - ); + lines.push("└── plugins/ # Agent skill files"); lines.push("```"); return lines.join("\n"); diff --git a/packages/cli/src/commands/cli/setup.ts b/packages/cli/src/commands/cli/setup.ts index d4892f864..569d61838 100644 --- a/packages/cli/src/commands/cli/setup.ts +++ b/packages/cli/src/commands/cli/setup.ts @@ -611,7 +611,7 @@ export const setupCommand = buildCommand({ method: { kind: "parsed", parse: parseInstallationMethod, - brief: "Installation method (curl, npm, pnpm, bun, yarn)", + brief: "Installation method (curl, brew, npm, pnpm, bun, yarn)", placeholder: "method", optional: true, }, diff --git a/packages/cli/src/commands/cli/uninstall.ts b/packages/cli/src/commands/cli/uninstall.ts index b285c6ce2..7dd30d9f0 100644 --- a/packages/cli/src/commands/cli/uninstall.ts +++ b/packages/cli/src/commands/cli/uninstall.ts @@ -435,7 +435,8 @@ export const uninstallCommand = buildDeleteCommand({ flags: { "keep-config": { kind: "boolean", - brief: "Keep the config directory (~/.sentry) and auth tokens", + brief: + "Keep the config directory (default ~/.config/sentry) and auth tokens", default: false, optional: true, },