feat(local): add command to run a local Spotlight sidecar

docs/src/content/docs/contributing.md

@@ -70,6 +70,7 @@ cli/
 │   │   ├── explore.ts   # Query aggregate event data (Explore)
 │   │   ├── help.ts      # Help command
 │   │   ├── init.ts      # Initialize Sentry in your project (experimental)
+│   │   ├── local.ts     # Run a local Spotlight sidecar to capture dev SDK events
 │   │   └── schema.ts    # Browse the Sentry API schema
 │   ├── lib/            # Shared utilities
 │   └── types/          # TypeScript types and Zod schemas

docs/src/fragments/commands/local.md

@@ -0,0 +1,50 @@
+
+
+[Spotlight](https://spotlightjs.com) is "Sentry for Development" — a lightweight local proxy that ingests Sentry envelopes from SDKs running in your dev stack and surfaces them in real time. `sentry local` runs a minimal [Hono](https://hono.dev/) HTTP server that's wire-compatible with Spotlight's sidecar protocol, so your existing SDKs and the [Spotlight overlay](https://spotlightjs.com/about/) work without any changes.
+
+No authentication is required — the sidecar binds to `localhost` by default and is purely a development tool.
+
+## Examples
+
+```bash
+# Start the sidecar on the default port (8969)
+sentry local
+
+# Use a custom port and bind to all interfaces
+sentry local --port 9000 --host 0.0.0.0
+
+# Run quietly (suppress per-envelope tail output)
+sentry local --quiet
+
+# Open the SSE endpoint in a browser on startup
+sentry local --open
+```
+
+## Endpoints
+
+| Method | Path                            | Description                                        |
+|--------|---------------------------------|----------------------------------------------------|
+| `POST` | `/stream`                       | Spotlight-compatible 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`)                      |
+
+## Pointing your SDK at the sidecar
+
+Set a localhost DSN that resolves to the sidecar's port — the public key and project ID can be any non-empty value because the sidecar accepts everything:
+
+```bash
+SENTRY_DSN=http://public@localhost:8969/1
+```
+
+Or configure your SDK's transport explicitly to send envelopes to `http://localhost:8969/stream`.
+
+## Tail output
+
+By default, every envelope received is logged as a single line:
+
+```
+14:32:01.456 • event+attachment
+```
+
+The label is the joined list of envelope item types (`event`, `transaction`, `log`, `attachment`, etc.). Use `--quiet` to suppress this output if you only need the SSE stream for the Spotlight overlay.

package.json

@@ -10,10 +10,12 @@
     "@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.113.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",
@@ -28,6 +30,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",
     "marked": "^15",

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

@@ -456,6 +456,14 @@ Initialize Sentry in your project (experimental)
 
 → Full flags and examples: `references/init.md`
 
+### Local
+
+Run a local Spotlight sidecar to capture dev SDK events
+
+- `sentry local` — Run a local Spotlight sidecar to capture dev SDK events
+
+→ 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,42 @@
+---
+name: sentry-cli-local
+version: 0.31.0-dev.0
+description: Run a local Spotlight sidecar to capture dev SDK events
+requires:
+  bins: ["sentry"]
+  auth: true
+---
+
+# Local Commands
+
+Run a local Spotlight sidecar to capture dev SDK events
+
+### `sentry local`
+
+Run a local Spotlight sidecar to capture dev SDK events
+
+**Flags:**
+- `-p, --port <value> - Port to listen on (default 8969) - (default: "8969")`
+- `-H, --host <value> - Hostname to bind to (default localhost) - (default: "localhost")`
+- `-o, --open - Open the sidecar SSE URL in a browser`
+- `-q, --quiet - Suppress per-envelope tail output`
+
+**Examples:**
+
+```bash
+# Start the sidecar on the default port (8969)
+sentry local
+
+# Use a custom port and bind to all interfaces
+sentry local --port 9000 --host 0.0.0.0
+
+# Run quietly (suppress per-envelope tail output)
+sentry local --quiet
+
+# Open the SSE endpoint in a browser on startup
+sentry local --open
+
+SENTRY_DSN=http://public@localhost:8969/1
+```
+
+All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

src/app.ts

@@ -18,6 +18,7 @@ import { helpCommand } from "./commands/help.js";
 import { initCommand } from "./commands/init.js";
 import { issueRoute } from "./commands/issue/index.js";
 import { listCommand as issueListCommand } from "./commands/issue/list.js";
+import { localCommand } from "./commands/local.js";
 import { logRoute } from "./commands/log/index.js";
 import { listCommand as logListCommand } from "./commands/log/list.js";
 import { orgRoute } from "./commands/org/index.js";
@@ -99,6 +100,7 @@ export const routes = buildRouteMap({
     trace: traceRoute,
     trial: trialRoute,
     init: initCommand,
+    local: localCommand,
     api: apiCommand,
     schema: schemaCommand,
     dashboards: dashboardListCommand,