feat: expose CLI as a programmatic library (#565)

## Summary

Exposes the Sentry CLI as a JavaScript/TypeScript library with a typed
SDK that auto-generates methods for every CLI command.

```typescript
import createSentrySDK from "sentry";

const sdk = createSentrySDK({ token: "sntrys_..." });

// Typed methods — use CLI route names directly
const orgs = await sdk.org.list();
const issues = await sdk.issues.list({ org: "acme", project: "frontend", limit: 5 });
const issue = await sdk.issue.view({ issueId: "ACME-123" });
await sdk.issue.explain({ issueId: "ACME-123" });

// Nested commands
await sdk.dashboard.widget.add({ ... });

// Escape hatch for any command
const raw = await sdk.run("api", "/organizations/", "--method", "GET");
```

44 commands auto-discovered from the route tree. Zero manual config.

## API

`createSentrySDK(options?)` is the **single entry point** (default
export).

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `token` | `string` | Auto-detected from env | Auth token (falls back
to `SENTRY_AUTH_TOKEN` / `SENTRY_TOKEN`) |
| `text` | `boolean` | `false` | Return human-readable text instead of
parsed JSON |
| `cwd` | `string` | `process.cwd()` | Working directory for DSN
auto-detection |

- Typed methods bypass Stricli's string dispatch — flags as objects,
direct `Command.loader()` invocation
- `sdk.run(...args)` escape hatch routes through Stricli for commands
not yet typed or interactive workflows
- Errors throw `SentryError` with `.exitCode` and `.stderr`

## Architecture

### Auto-generated SDK (`script/generate-sdk.ts`)
Build-time codegen walks the route tree via Stricli introspection:
- Discovers all commands recursively, skips hidden routes (plural
aliases)
- Uses CLI route names as-is: `org.list`, `issue.explain`,
`dashboard.widget.add`
- Extracts flag definitions → typed parameter interfaces
- Reads `__jsonSchema` (#582) → typed return types from Zod schemas
- Derives positional params from placeholder strings
- Zero config — new commands are automatically included

### Direct command invocation (`src/lib/sdk-invoke.ts`)
`buildInvoker()` resolves commands from the route tree (cached), calls
`Command.loader()` directly with pre-built flag objects. `buildRunner()`
provides the `sdk.run()` escape hatch via Stricli's `run()`.

### Env registry (`src/lib/env.ts`)
`getEnv()`/`setEnv()` replaces all direct `process.env` reads (~14
files). Library mode creates an isolated env copy — consumer's
`process.env` is never mutated.

### CLI extraction (`src/cli.ts`)
CLI runner extracted from `bin.ts`. Both the npm bin wrapper and library
share the same internals.

### Single npm bundle
esbuild entry: `src/index.ts` → `dist/index.cjs`. Tiny `dist/bin.cjs`
wrapper (~200 bytes) for CLI. Package size stays flat.

### Zero-copy return
`captureObject` duck-type on Writer hands back in-memory objects
directly.

### Library-safe telemetry
`initSentry({ libraryMode: true })` strips global-polluting
integrations.

### Lazy `node:sqlite`
Polyfill defers `node:sqlite` import to first DB access, so
`require("sentry")` doesn't crash.

## Tests
- `test/lib/env.test.ts` — env registry (5 tests)
- `test/lib/index.test.ts` — `createSentrySDK` + `sdk.run()` (7 tests)
- `test/lib/sdk.test.ts` — typed SDK methods + namespaces (7 tests)
- `test/e2e/library.test.ts` — bundled library via Node.js subprocesses
(17 tests)

## Documentation
- README "Library Usage" section
- Full docs page at `docs/src/content/docs/library-usage.md`

## Related
- #566 / #582 — Schema registration on OutputConfig (landed, used for
return types)

Author: BYK

.gitignore

@@ -54,6 +54,8 @@ docs/.astro
 
 # Generated files (rebuilt at build time)
 src/generated/
+src/sdk.generated.ts
+src/sdk.generated.d.cts
 
 # OpenCode
 .opencode/

AGENTS.md

@@ -83,6 +83,38 @@ For detailed documentation, visit [cli.sentry.dev](https://cli.sentry.dev).
 
 Credentials are stored in `~/.sentry/` with restricted permissions (mode 600).
 
+## Library Usage
+
+Use Sentry CLI programmatically in Node.js (≥22) or Bun without spawning a subprocess:
+
+```typescript
+import createSentrySDK from "sentry";
+
+const sdk = createSentrySDK({ token: "sntrys_..." });
+
+// Typed methods for every CLI command
+const orgs = await sdk.org.list();
+const issues = await sdk.issue.list({ orgProject: "acme/frontend", limit: 5 });
+const issue = await sdk.issue.view({ issue: "ACME-123" });
+
+// Nested commands
+await sdk.dashboard.widget.add({ display: "line", query: "count" }, "my-org/my-dashboard");
+
+// Escape hatch for any CLI command
+const version = await sdk.run("--version");
+const text = await sdk.run("issue", "list", "-l", "5");
+```
+
+Options (all optional):
+- `token` — Auth token. Falls back to `SENTRY_AUTH_TOKEN` / `SENTRY_TOKEN` env vars.
+- `url` — Sentry instance URL for self-hosted (e.g., `"sentry.example.com"`).
+- `org` — Default organization slug (avoids passing it on every call).
+- `project` — Default project slug.
+- `text` — Return human-readable string instead of parsed JSON (affects `run()` only).
+- `cwd` — Working directory for DSN auto-detection. Defaults to `process.cwd()`.
+
+Errors are thrown as `SentryError` with `.exitCode` and `.stderr`.
+
 ---
 
 ## Development

README.md

@@ -67,12 +67,14 @@
       }
     },
     {
+      // src/index.ts is the library entry point — re-exports SentryError, SentryOptions, SentrySDK
       // db/index.ts exports db connection utilities - not a barrel file but triggers the rule
       // api-client.ts is a barrel that re-exports from src/lib/api/ domain modules
       // to preserve the existing import path for all consumers
       // markdown.ts re-exports isPlainOutput from plain-detect.ts for backward compat
       // script/debug-id.ts re-exports from src/lib/sourcemap/debug-id.ts for build scripts
       "includes": [
+        "src/index.ts",
         "src/lib/db/index.ts",
         "src/lib/api-client.ts",
         "src/lib/formatters/markdown.ts",

biome.jsonc

@@ -199,6 +199,7 @@ export default defineConfig({
             { label: "Installation", slug: "getting-started" },
             { label: "Self-Hosted", slug: "self-hosted" },
             { label: "Configuration", slug: "configuration" },
+            { label: "Library Usage", slug: "library-usage" },
           ],
         },
         {

docs/astro.config.mjs

@@ -0,0 +1,223 @@
+---
+title: Library Usage
+description: Use the Sentry CLI programmatically in Node.js or Bun
+---
+
+The Sentry CLI can be used as a JavaScript/TypeScript library, running commands
+in-process without spawning a subprocess. This is useful for AI coding agents,
+build tools, CI scripts, and other tools that want structured Sentry data.
+
+## Installation
+
+```bash
+npm install sentry
+```
+
+## Quick Start
+
+```typescript
+import createSentrySDK from "sentry";
+
+const sdk = createSentrySDK({ token: "sntrys_..." });
+
+// Typed methods for every CLI command
+const orgs = await sdk.org.list();
+const issues = await sdk.issue.list({ orgProject: "acme/frontend", limit: 5 });
+```
+
+## Typed SDK
+
+`createSentrySDK()` returns an object with typed methods for **every** CLI command,
+organized by the CLI route hierarchy:
+
+```typescript
+import createSentrySDK from "sentry";
+
+const sdk = createSentrySDK({ token: "sntrys_..." });
+```
+
+### Organizations
+
+```typescript
+const orgs = await sdk.org.list();
+const org = await sdk.org.view({ org: "acme" });
+```
+
+### Projects
+
+```typescript
+const projects = await sdk.project.list({ orgProject: "acme/" });
+const project = await sdk.project.view({ orgProject: "acme/frontend" });
+```
+
+### Issues
+
+```typescript
+const issues = await sdk.issue.list({
+  orgProject: "acme/frontend",
+  limit: 10,
+  query: "is:unresolved",
+  sort: "date",
+});
+
+const issue = await sdk.issue.view({ issue: "ACME-123" });
+```
+
+### Events, Traces, Spans
+
+```typescript
+const event = await sdk.event.view({}, "abc123...");
+
+const traces = await sdk.trace.list({ orgProject: "acme/frontend" });
+const trace = await sdk.trace.view({}, "abc123...");
+
+const spans = await sdk.span.list({}, "acme/frontend");
+```
+
+### Dashboards
+
+```typescript
+const dashboards = await sdk.dashboard.list({}, "acme/");
+const dashboard = await sdk.dashboard.view({}, "acme/", "my-dashboard");
+
+// Nested widget commands
+await sdk.dashboard.widget.add(
+  { display: "line", query: "count" },
+  "acme/", "my-dashboard"
+);
+```
+
+### Teams
+
+```typescript
+const teams = await sdk.team.list({ orgProject: "acme/" });
+```
+
+### Authentication
+
+```typescript
+await sdk.auth.login();
+await sdk.auth.status();
+const whoami = await sdk.auth.whoami();
+```
+
+The typed SDK invokes command handlers directly — bypassing CLI string parsing
+for zero overhead beyond the command's own logic.
+
+## Escape Hatch: `run()`
+
+For commands not easily expressed through the typed API, or when you want to
+pass raw CLI flags, use `sdk.run()`:
+
+```typescript
+// Run any CLI command — returns parsed JSON by default
+const version = await sdk.run("--version");
+const issues = await sdk.run("issue", "list", "-l", "5");
+const help = await sdk.run("help", "issue");
+```
+
+## Authentication
+
+The `token` option provides an auth token for the current invocation. When
+omitted, it falls back to environment variables and stored credentials:
+
+1. `token` option (highest priority)
+2. `SENTRY_AUTH_TOKEN` environment variable
+3. `SENTRY_TOKEN` environment variable
+4. Stored OAuth token from `sentry auth login`
+
+```typescript
+// Explicit token
+const sdk = createSentrySDK({ token: "sntrys_..." });
+
+// Or set the env var — it's picked up automatically
+process.env.SENTRY_AUTH_TOKEN = "sntrys_...";
+const sdk = createSentrySDK();
+```
+
+## Options
+
+All options are optional. Pass them when creating the SDK:
+
+```typescript
+const sdk = createSentrySDK({ token: "...", text: true, cwd: "/my/project" });
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `token` | `string` | Auto-detected | Auth token for this invocation |
+| `url` | `string` | `sentry.io` | Sentry instance URL for self-hosted |
+| `org` | `string` | Auto-detected | Default organization slug |
+| `project` | `string` | Auto-detected | Default project slug |
+| `text` | `boolean` | `false` | Return human-readable text instead of parsed JSON (`run()` only) |
+| `cwd` | `string` | `process.cwd()` | Working directory for DSN auto-detection |
+
+## Return Values
+
+Typed SDK methods return **parsed JavaScript objects** with zero serialization
+overhead (via zero-copy capture). The `run()` escape hatch returns parsed JSON
+by default, or a trimmed string for commands without JSON support.
+
+```typescript
+// Typed methods → typed return
+const issues = await sdk.issue.list({ orgProject: "acme/frontend" });
+// IssueListResult type with known fields
+
+// run() → parsed JSON or string
+const version = await sdk.run("--version");
+// "sentry 0.21.0"
+```
+
+## Error Handling
+
+Commands that fail throw a `SentryError`:
+
+```typescript
+import createSentrySDK, { SentryError } from "sentry";
+
+const sdk = createSentrySDK();
+
+try {
+  await sdk.issue.view({ issue: "NONEXISTENT-1" });
+} catch (err) {
+  if (err instanceof SentryError) {
+    console.error(err.message);   // Clean error message (no ANSI codes)
+    console.error(err.exitCode);  // Non-zero exit code
+    console.error(err.stderr);    // Raw stderr output
+  }
+}
+```
+
+## Environment Isolation
+
+The library never mutates `process.env`. Each invocation creates an isolated
+copy of the environment. This means:
+
+- Your application's env vars are never touched
+- Multiple sequential calls are safe
+- Auth tokens passed via `token` don't leak to subsequent calls
+
+:::note
+Concurrent calls are not supported in the current version.
+Calls should be sequential (awaited one at a time).
+:::
+
+## Comparison with Subprocess
+
+| | Library (`createSentrySDK()`) | Subprocess (`child_process`) |
+|---|---|---|
+| **Startup** | ~0ms (in-process) | ~200ms (process spawn + init) |
+| **Output** | Parsed object (zero-copy) | String (needs JSON.parse) |
+| **Errors** | `SentryError` with typed fields | Exit code + stderr string |
+| **Auth** | `token` option or env vars | Env vars only |
+| **Node.js** | >=22 required | Any version |
+
+## Requirements
+
+- **Node.js >= 22** (required for `node:sqlite`)
+- Or **Bun** (any recent version)
+
+:::caution
+Streaming flags (`--refresh`, `--follow`) are not supported in library mode
+and will throw a `SentryError`. Use the CLI binary directly for live-streaming commands.
+:::

docs/src/content/docs/library-usage.md

@@ -46,12 +46,23 @@
   "bin": {
     "sentry": "./dist/bin.cjs"
   },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.cts",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.cjs"
+    }
+  },
   "description": "Sentry CLI - A command-line interface for using Sentry built by robots and humans for robots and humans",
   "engines": {
     "node": ">=22"
   },
   "files": [
-    "dist/bin.cjs"
+    "dist/bin.cjs",
+    "dist/index.cjs",
+    "dist/index.d.cts"
   ],
   "license": "FSL-1.1-Apache-2.0",
   "packageManager": "bun@1.3.11",
@@ -61,18 +72,19 @@
     "@sentry/node-core@10.44.0": "patches/@sentry%2Fnode-core@10.44.0.patch"
   },
   "scripts": {
-    "dev": "bun run generate:schema && bun run src/bin.ts",
-    "build": "bun run generate:schema && bun run script/build.ts --single",
-    "build:all": "bun run generate:schema && bun run script/build.ts",
-    "bundle": "bun run generate:schema && bun run script/bundle.ts",
-    "typecheck": "tsc --noEmit",
+    "dev": "bun run generate:schema && bun run generate:sdk && bun run src/bin.ts",
+    "build": "bun run generate:schema && bun run generate:sdk && bun run script/build.ts --single",
+    "build:all": "bun run generate:schema && bun run generate:sdk && bun run script/build.ts",
+    "bundle": "bun run generate:schema && bun run generate:sdk && bun run script/bundle.ts",
+    "typecheck": "bun run generate:sdk && tsc --noEmit",
     "lint": "bunx ultracite check",
     "lint:fix": "bunx ultracite fix",
     "test": "bun run test:unit && bun run test:isolated",
-    "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:unit": "bun run generate:sdk && bun test --timeout 15000 test/lib test/commands test/types --coverage --coverage-reporter=lcov",
+    "test:isolated": "bun run generate:sdk && bun test --timeout 15000 test/isolated",
+    "test:e2e": "bun run generate:sdk && bun test --timeout 15000 test/e2e",
     "test:init-eval": "bun test test/init-eval --timeout 600000 --concurrency 6",
+    "generate:sdk": "bun run script/generate-sdk.ts",
     "generate:skill": "bun run script/generate-skill.ts",
     "generate:schema": "bun run script/generate-api-schema.ts",
     "generate:command-docs": "bun run script/generate-command-docs.ts",