feat(local): add local dev server for capturing SDK events

docs/src/content/docs/contributing.md

@@ -56,6 +56,7 @@ cli/
 │   │   ├── dashboard/   # list, view, create, add, edit, delete, revisions, restore
 │   │   ├── event/       # view, list
 │   │   ├── issue/       # list, events, explain, plan, view, resolve, unresolve, archive, merge
+│   │   ├── local/       # serve, run
 │   │   ├── log/         # list, view
 │   │   ├── org/         # list, view
 │   │   ├── project/     # create, delete, list, view

docs/src/fragments/commands/local.md

@@ -0,0 +1,66 @@
+
+
+`sentry local` runs a local development server that captures Sentry SDK envelopes from your dev stack and surfaces errors, traces, and logs in real time — right in your terminal. No authentication required.
+
+If a server is already running on the port, the command attaches as an SSE consumer instead of starting a duplicate.
+
+## Examples
+
+```bash
+# Start the server and tail events (default)
+sentry local
+
+# Run your app with the local server auto-enabled
+sentry local run -- npm run dev
+sentry local run -- python manage.py runserver
+
+# Use a custom port
+sentry local --port 9000
+
+# Only show errors and logs (filter out transactions)
+sentry local -f error -f log
+
+# Run quietly (suppress per-envelope tail output)
+sentry local --quiet
+```
+
+## `sentry local run`
+
+Runs a command with `SENTRY_SPOTLIGHT` injected into the environment. The Sentry SDK automatically detects this variable and sends envelopes to the local server. No code changes needed.
+
+Env vars injected into the child process:
+
+| Variable | Value |
+|----------|-------|
+| `SENTRY_SPOTLIGHT` | `http://localhost:<port>/stream` |
+| `NEXT_PUBLIC_SENTRY_SPOTLIGHT` | `http://localhost:<port>/stream` |
+| `SENTRY_TRACES_SAMPLE_RATE` | `1` |
+
+## Endpoints
+
+| Method | Path                            | Description                                        |
+|--------|---------------------------------|----------------------------------------------------|
+| `POST` | `/stream`                       | Envelope ingest                                    |
+| `POST` | `/api/{projectId}/envelope/`    | Sentry SDK ingest path                             |
+| `GET`  | `/stream`                       | Server-Sent Events feed of incoming envelopes      |
+| `GET`  | `/health`                       | Liveness check (returns `OK`)                      |
+
+## Tail output
+
+By default, incoming envelopes are pretty-printed to the terminal:
+
+```
+14:32:01 [ERROR]   [SERVER]  TypeError: x is not a function [app.ts:42:5] [handleRequest]
+14:32:02 [TRACE]   [BROWSER] [http.client] GET /api/users [245ms] [3 spans]
+14:32:03 [INFO]    [SERVER]  User logged in [user_id=1234] [region=us]
+```
+
+Errors show the exception type, message, and top stack frame. Transactions show the operation, duration, and span count. Logs show the severity level, message, and custom attributes.
+
+Use `--filter` / `-f` to narrow the output to specific event types (repeatable):
+
+```bash
+sentry local -f error -f log    # only errors and logs
+```
+
+Use `--quiet` to suppress tail output entirely if you only need the SSE stream.

package.json

@@ -10,11 +10,13 @@
     "@anthropic-ai/sdk": "^0.39.0",
     "@biomejs/biome": "2.3.8",
     "@clack/prompts": "0.11.0",
+    "@hono/node-server": "^2.0.0",
     "@mastra/client-js": "^1.4.0",
     "@sentry/api": "^0.141.0",
     "@sentry/core": "10.50.0",
     "@sentry/node-core": "10.50.0",
     "@sentry/sqlish": "^1.0.0",
+    "@spotlightjs/spotlight": "^4.11.3",
     "@stricli/auto-complete": "^1.2.4",
     "@stricli/core": "^1.2.4",
     "@types/bun": "latest",
@@ -30,6 +32,7 @@
     "consola": "^3.4.2",
     "esbuild": "^0.25.0",
     "fast-check": "^4.5.3",
+    "hono": "^4.12.15",
     "http-cache-semantics": "^4.2.0",
     "ignore": "^7.0.5",
     "ink": "^7.0.1",
@@ -116,5 +119,10 @@
     "check:docs-sections": "bun run script/generate-docs-sections.ts --check"
   },
   "type": "module",
-  "types": "./dist/index.d.cts"
+  "types": "./dist/index.d.cts",
+  "patchedDependencies": {
+    "@stricli/core@1.2.5": "patches/@stricli%2Fcore@1.2.5.patch",
+    "@sentry/node-core@10.50.0": "patches/@sentry%2Fnode-core@10.50.0.patch",
+    "@sentry/core@10.50.0": "patches/@sentry%2Fcore@10.50.0.patch"
+  }
 }

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -469,6 +469,15 @@ Initialize Sentry in your project (experimental)
 
 → Full flags and examples: `references/init.md`
 
+### Local
+
+Sentry for local development
+
+- `sentry local serve` — Start the local dev server and tail events
+- `sentry local run <command...>` — Run a command with the local dev server enabled
+
+→ Full flags and examples: `references/local.md`
+
 ### Schema
 
 Browse the Sentry API schema

plugins/sentry-cli/skills/sentry-cli/references/local.md

@@ -0,0 +1,54 @@
+---
+name: sentry-cli-local
+version: 0.35.0-dev.0
+description: Sentry for local development
+requires:
+  bins: ["sentry"]
+  auth: true
+---
+
+# Local Commands
+
+Sentry for local development
+
+### `sentry local serve`
+
+Start the local dev server and tail events
+
+**Flags:**
+- `-p, --port <value> - Port to listen on (default 8969) - (default: "8969")`
+- `-H, --host <value> - Hostname to bind to (default localhost) - (default: "localhost")`
+- `-q, --quiet - Suppress per-envelope tail output`
+- `-f, --filter <value>... - Only show items of this type (repeatable: error, transaction, log)`
+
+### `sentry local run <command...>`
+
+Run a command with the local dev server enabled
+
+**Flags:**
+- `-p, --port <value> - Port for the local server (default 8969) - (default: "8969")`
+- `--host <value> - Hostname for the local server (default localhost) - (default: "localhost")`
+
+**Examples:**
+
+```bash
+# Start the server and tail events (default)
+sentry local
+
+# Run your app with the local server auto-enabled
+sentry local run -- npm run dev
+sentry local run -- python manage.py runserver
+
+# Use a custom port
+sentry local --port 9000
+
+# Only show errors and logs (filter out transactions)
+sentry local -f error -f log
+
+# Run quietly (suppress per-envelope tail output)
+sentry local --quiet
+
+sentry local -f error -f log    # only errors and logs
+```
+
+All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.