feat(init): add init command for guided Sentry project setup (#283)

## Summary

Adds `sentry init` — an AI-powered wizard that walks users through
adding Sentry to their project. It detects the platform, installs the
SDK, instruments the code, and configures error monitoring, tracing, and
session replay.

## Changes

### Core wizard
- New `init` command backed by a Mastra AI workflow (hosted at
[getsentry/cli-init-api](https://github.com/getsentry/cli-init-api/))
that handles platform detection, SDK installation, and code
instrumentation
- ASCII banner, AI transparency note, and review reminder in the wizard
UX
- Tracing: unique trace IDs per wizard run with flattened span hierarchy
- Python platforms use venv for isolated dependency installation
- Magic values extracted into named constants (`constants.ts`)
- Docs page added to cli.sentry.dev

### Security hardening
- Shell metacharacter blocklist: `()` subshell bypass, `>` `<` `&`
redirection/background, `$` `'` `"` `\` expansion/escaping, `{` `}` `*`
`?` glob/brace expansion, `#` shell comment
- Environment variable injection blocking (`VAR=value cmd` pattern)
- Remote-supplied `cwd` validation against project directory
- Dangerous executable blocklist and path-traversal prevention
- File descriptor cleanup on `readSync` failure
- Cross-platform shell execution (`{ shell: true }` instead of hardcoded
`sh`)

### Performance
- Pre-computed directory listing sent with first API call to skip
initial `list-dir` round-trip
- `_prevPhases` cross-phase caching to reuse results across workflow
steps (#307)

### Testing & CI
- Wizard-runner unit tests (coverage 5.94% → 99.42%)
- Banner extracted to `src/lib/banner.ts` to break circular import
- Mock isolation fixes (`spyOn` instead of `mock.module` where possible)
- Simplified coverage pipeline (removed merge-lcov workaround)

## Eval suite

The eval suite validates that the wizard produces correct, buildable
Sentry instrumentation for each supported platform. It uses a **3-phase
test architecture**:

### Phase 1: Wizard run
Each test scaffolds a fresh project from a platform template, then runs
the full `sentry init` wizard against it. The wizard output (exit code,
stdout/stderr, git diff, new files) is captured for the next phases.

### Phase 2: Hard assertions (deterministic)
Five code-based pass/fail checks that run without any LLM:
1. **exit-code** — wizard exits 0
2. **sdk-installed** — the Sentry SDK package appears in the dependency
file (`package.json` / `requirements.txt`)
3. **init-present** — `Sentry.init` (or `sentry_sdk.init`) appears in
changed or new files
4. **no-placeholder-dsn** — no leftover placeholder DSNs
(`___PUBLIC_DSN___`, `YOUR_DSN_HERE`, etc.)
5. **build-succeeds** — `npm run build` / equivalent passes after the
wizard's changes

### Phase 3: LLM judge (per-feature)
For each feature (errors, tracing, replay, logs, profiling, etc.), an
LLM judge scores correctness:
- Official Sentry docs are fetched as ground truth (URLs mapped in
`feature-docs.json`)
- GPT-4o evaluates the wizard's diff + new files against the docs on 4
criteria: feature-initialized, correct-imports, no-syntax-errors,
follows-docs
- Each criterion is scored pass/fail/unknown; the overall feature score
must be >= 0.5

### Platforms
6 platform templates are covered:
| Platform | Template | SDK |
|----------|----------|-----|
| Express | `express/` | `@sentry/node` |
| Next.js | `nextjs/` | `@sentry/nextjs` |
| SvelteKit | `sveltekit/` | `@sentry/sveltekit` |
| React + Vite | `react-vite/` | `@sentry/react` |
| Flask | `python-flask/` | `sentry-sdk` |
| FastAPI | `python-fastapi/` | `sentry-sdk` |

### Running
```bash
bun run test:init-eval          # all platforms
```
Requires `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT`, and
optionally `OPENAI_API_KEY` (LLM judge is skipped without it).

## Test Plan

- [x] All init unit tests pass (124 tests across 7 files)
- [x] `bun run lint` and `bun run typecheck` pass
- [x] CI passes (unit tests, e2e, lint, typecheck, build)
- CI workflow for eval is tracked separately in #290

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Aditya Mathur <57684218+MathurAditya724@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 4 people

.gitignore

@@ -1,5 +1,6 @@
 # dependencies (bun install)
 node_modules
+package-lock.json
 
 # output
 out
@@ -36,6 +37,7 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .cache
 *.tsbuildinfo
 .turbo
+.mastra
 
 # docs
 docs/dist

biome.jsonc

@@ -2,7 +2,7 @@
   "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
   "extends": ["ultracite/core"],
   "files": {
-    "includes": ["!docs"]
+    "includes": ["!docs", "!test/init-eval/templates"]
   },
   "javascript": {
     "globals": ["Bun"]

bun.lock

@@ -0,0 +1,63 @@
+---
+title: init
+description: AI-powered project setup wizard for the Sentry CLI
+---
+
+Set up Sentry in your project with an AI-powered wizard. The `init` command detects your platform and framework, installs the Sentry SDK, and instruments your code for error monitoring, tracing, and more.
+
+**Prerequisites:** You must be authenticated first. Run `sentry auth login` if you haven't already.
+
+## Usage
+
+```bash
+sentry init [directory]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `[directory]` | Project directory (default: current directory) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Continue even if Sentry is already installed |
+| `-y, --yes` | Non-interactive mode (accept defaults) |
+| `--dry-run` | Preview changes without applying them |
+| `--features <list>` | Comma-separated features: `errors`, `tracing`, `logs`, `replay`, `metrics` |
+
+## Examples
+
+```bash
+# Run the wizard in the current directory
+sentry init
+
+# Target a subdirectory
+sentry init ./my-app
+
+# Preview what changes would be made
+sentry init --dry-run
+
+# Select specific features
+sentry init --features errors,tracing,logs
+
+# Non-interactive mode (accept all defaults)
+sentry init --yes
+```
+
+## What the wizard does
+
+1. **Detects your framework** — scans your project files to identify the platform and framework
+2. **Installs the SDK** — adds the appropriate Sentry SDK package to your project
+3. **Instruments your code** — configures error monitoring, tracing, and any selected features
+
+## Supported platforms
+
+The wizard currently supports:
+
+- **JavaScript / TypeScript** — Next.js, Express, SvelteKit, React
+- **Python** — Flask, FastAPI
+
+More platforms and frameworks are coming soon.

docs/src/content/docs/commands/init.md

@@ -106,6 +106,7 @@ Credentials are stored in a SQLite database at `~/.sentry/` with restricted file
 
 Once authenticated, you can start using the CLI:
 
+- [Initialize Sentry](../commands/init/) - Set up Sentry in your project with the guided wizard
 - [Organization commands](../commands/org/) - List and view organizations
 - [Project commands](../commands/project/) - Manage projects
 - [Issue commands](../commands/issue/) - Track and manage issues

docs/src/content/docs/getting-started.mdx

@@ -6,7 +6,10 @@
     "url": "git+https://github.com/getsentry/cli.git"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
     "@biomejs/biome": "2.3.8",
+    "@clack/prompts": "^0.11.0",
+    "@mastra/client-js": "^1.4.0",
     "@sentry/api": "^0.21.0",
     "@sentry/bun": "10.39.0",
     "@sentry/esbuild-plugin": "^2.23.0",
@@ -27,6 +30,7 @@
     "http-cache-semantics": "^4.2.0",
     "ignore": "^7.0.5",
     "marked": "^15",
+    "openai": "^6.22.0",
     "p-limit": "^7.2.0",
     "pretty-ms": "^9.3.0",
     "qrcode-terminal": "^0.12.0",
@@ -66,6 +70,7 @@
     "test:unit": "bun test --timeout 15000 test/lib test/commands test/types --coverage --coverage-reporter=lcov",
     "test:isolated": "bun test --timeout 15000 test/isolated",
     "test:e2e": "bun test --timeout 15000 test/e2e",
+    "test:init-eval": "bun test test/init-eval --timeout 600000 --concurrency 6",
     "generate:skill": "bun run script/generate-skill.ts",
     "check:skill": "bun run script/check-skill.ts",
     "check:deps": "bun run script/check-no-deps.ts"

package.json

@@ -630,6 +630,20 @@ View logs associated with a trace
 - `-q, --query <value> - Additional filter query (Sentry search syntax)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
 
+### Init
+
+Initialize Sentry in your project
+
+#### `sentry init <directory>`
+
+Initialize Sentry in your project
+
+**Flags:**
+- `--force - Continue even if Sentry is already installed`
+- `-y, --yes - Non-interactive mode (accept defaults)`
+- `--dry-run - Preview changes without applying them`
+- `--features <value> - Comma-separated features: errors,tracing,logs,replay,metrics`
+
 ### Issues
 
 List issues in a project

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

@@ -13,6 +13,7 @@ import { whoamiCommand } from "./commands/auth/whoami.js";
 import { cliRoute } from "./commands/cli/index.js";
 import { eventRoute } from "./commands/event/index.js";
 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 { logRoute } from "./commands/log/index.js";
@@ -64,6 +65,7 @@ export const routes = buildRouteMap({
     event: eventRoute,
     log: logRoute,
     trace: traceRoute,
+    init: initCommand,
     api: apiCommand,
     issues: issueListCommand,
     orgs: orgListCommand,

src/app.ts

@@ -0,0 +1,84 @@
+/**
+ * sentry init
+ *
+ * Initialize Sentry in a project using the remote wizard workflow.
+ * Communicates with the Mastra API via suspend/resume to perform
+ * local filesystem operations and interactive prompts.
+ */
+
+import path from "node:path";
+import type { SentryContext } from "../context.js";
+import { buildCommand } from "../lib/command.js";
+import { runWizard } from "../lib/init/wizard-runner.js";
+
+type InitFlags = {
+  readonly force: boolean;
+  readonly yes: boolean;
+  readonly "dry-run": boolean;
+  readonly features?: string;
+};
+
+export const initCommand = buildCommand<InitFlags, [string?], SentryContext>({
+  docs: {
+    brief: "Initialize Sentry in your project",
+    fullDescription:
+      "Runs the Sentry setup wizard to detect your project's framework, " +
+      "install the SDK, and configure error monitoring. Uses a remote " +
+      "workflow that coordinates local file operations through the CLI.",
+  },
+  parameters: {
+    positional: {
+      kind: "tuple",
+      parameters: [
+        {
+          placeholder: "directory",
+          brief: "Project directory (default: current directory)",
+          parse: String,
+          optional: true,
+        },
+      ],
+    },
+    flags: {
+      force: {
+        kind: "boolean",
+        brief: "Continue even if Sentry is already installed",
+        default: false,
+      },
+      yes: {
+        kind: "boolean",
+        brief: "Non-interactive mode (accept defaults)",
+        default: false,
+      },
+      "dry-run": {
+        kind: "boolean",
+        brief: "Preview changes without applying them",
+        default: false,
+      },
+      features: {
+        kind: "parsed",
+        parse: String,
+        brief: "Comma-separated features: errors,tracing,logs,replay,metrics",
+        optional: true,
+        placeholder: "list",
+      },
+    },
+    aliases: {
+      y: "yes",
+    },
+  },
+  async func(this: SentryContext, flags: InitFlags, directory?: string) {
+    const targetDir = directory ? path.resolve(this.cwd, directory) : this.cwd;
+    const featuresList = flags.features
+      ?.split(",")
+      .map((f) => f.trim())
+      .filter(Boolean);
+
+    await runWizard({
+      directory: targetDir,
+      force: flags.force,
+      yes: flags.yes,
+      dryRun: flags["dry-run"],
+      features: featuresList,
+    });
+  },
+});

src/commands/init.ts

@@ -46,6 +46,7 @@ import {
   resolveOrCreateTeam,
 } from "../../lib/resolve-team.js";
 import { buildProjectUrl } from "../../lib/sentry-urls.js";
+import { slugify } from "../../lib/utils.js";
 import type { SentryProject, Writer } from "../../types/index.js";
 
 /** Usage hint template — base command without positionals */
@@ -107,25 +108,6 @@ function normalizePlatform(platform: string, stderr: Writer): string {
   return corrected;
 }
 
-/**
- * Convert a project name to its expected Sentry slug.
- * Aligned with Sentry's canonical implementation:
- * https://github.com/getsentry/sentry/blob/master/static/app/utils/slugify.tsx
- *
- * @example slugify("My Cool App") // "my-cool-app"
- * @example slugify("my-app")      // "my-app"
- * @example slugify("Café Project") // "cafe-project"
- * @example slugify("my_app")      // "my_app"
- */
-function slugify(name: string): string {
-  return name
-    .normalize("NFKD")
-    .toLowerCase()
-    .replace(/[^a-z0-9_\s-]/g, "")
-    .replace(/[-\s]+/g, "-")
-    .replace(/^-|-$/g, "");
-}
-
 /**
  * Check whether an API error is about an invalid platform value.
  * Relies on Sentry's error message wording — may need updating if the API changes.