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,60 @@
+
+
+[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
+
+# Only show errors and logs (filter out transactions)
+sentry local -f error -f log
+```
+
+## 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, 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]
+```
+
+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 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/dashboard.md

@@ -42,7 +42,7 @@ View a dashboard
 - `-w, --web - Open in browser`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-r, --refresh <value> - Auto-refresh interval in seconds (default: 60, min: 10)`
-- `-t, --period <value> - Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01"`
+- `-t, --period <value> - Time range: "7d", "2026-04-01..2026-05-01", ">=2026-04-01"`
 
 **Examples:**
 

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

@@ -37,7 +37,7 @@ List events for an issue
 - `-n, --limit <value> - Number of events (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `--full - Include full event body (stacktraces)`
-- `-t, --period <value> - Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-04-01..2026-05-01", ">=2026-04-01" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

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

@@ -21,7 +21,7 @@ Query aggregate event data (Explore)
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-s, --sort <value> - Sort field (prefix with - for desc, e.g., "-count()")`
 - `-n, --limit <value> - Number of rows (1-1000) - (default: "25")`
-- `-t, --period <value> - Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01" - (default: "24h")`
+- `-t, --period <value> - Time range: "7d", "2026-04-01..2026-05-01", ">=2026-04-01" - (default: "24h")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

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

@@ -19,7 +19,7 @@ List issues in a project
 - `-q, --query <value> - Search query (Sentry syntax, implicit AND, no OR operator)`
 - `-n, --limit <value> - Maximum number of issues to list - (default: "25")`
 - `-s, --sort <value> - Sort by: date, new, freq, user - (default: "date")`
-- `-t, --period <value> - Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01" - (default: "90d")`
+- `-t, --period <value> - Time range: "7d", "2026-04-01..2026-05-01", ">=2026-04-01" - (default: "90d")`
 - `-c, --cursor <value> - Pagination cursor (use "next" for next page, "prev" for previous)`
 - `--compact - Single-line rows for compact output (auto-detects if omitted)`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
@@ -87,7 +87,7 @@ List events for a specific issue
 - `-n, --limit <value> - Number of events (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `--full - Include full event body (stacktraces)`
-- `-t, --period <value> - Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-04-01..2026-05-01", ">=2026-04-01" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

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

@@ -0,0 +1,43 @@
+---
+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`
+- `-f, --filter <value>... - Only show items of this type (repeatable: error, transaction, log)`
+
+**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.

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

@@ -19,7 +19,7 @@ List logs from a project
 - `-n, --limit <value> - Number of log entries (1-1000) - (default: "100")`
 - `-q, --query <value> - Filter query (e.g., "level:error", "project:backend", "project:[a,b]")`
 - `-f, --follow <value> - Stream logs (optionally specify poll interval in seconds)`
-- `-t, --period <value> - Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01"`
+- `-t, --period <value> - Time range: "7d", "2026-04-01..2026-05-01", ">=2026-04-01"`
 - `-s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")`
 - `--fresh - Bypass cache, re-detect projects, and fetch fresh data`
 

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

@@ -19,7 +19,7 @@ List spans in a project or trace
 - `-n, --limit <value> - Number of spans (<=1000) - (default: "25")`
 - `-q, --query <value> - Filter spans (e.g., "op:db", "project:backend", "project:[cli,api]")`
 - `-s, --sort <value> - Sort order: date, duration - (default: "date")`
-- `-t, --period <value> - Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-04-01..2026-05-01", ">=2026-04-01" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

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

@@ -19,7 +19,7 @@ List recent traces in a project
 - `-n, --limit <value> - Number of traces (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-s, --sort <value> - Sort by: date, duration - (default: "date")`
-- `-t, --period <value> - Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01" - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-04-01..2026-05-01", ">=2026-04-01" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
@@ -91,7 +91,7 @@ View logs associated with a trace
 
 **Flags:**
 - `-w, --web - Open trace in browser`
-- `-t, --period <value> - Time range: "7d", "2026-03-01..2026-04-01", ">=2026-03-01" - (default: "14d")`
+- `-t, --period <value> - Time range: "7d", "2026-04-01..2026-05-01", ">=2026-04-01" - (default: "14d")`
 - `-n, --limit <value> - Number of log entries (<=1000) - (default: "100")`
 - `-q, --query <value> - Filter query (e.g., "level:error", "project:backend", "project:[a,b]")`
 - `-s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")`

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,