feat: expose CLI as a programmatic library

Add a variadic `sentry()` function that runs CLI commands in-process
and returns parsed JSON objects (or raw text). This enables AI coding
agents, build tools, and other JS/TS consumers to use the CLI without
spawning a subprocess.

## API

```typescript
import sentry from "sentry";

const issues = await sentry("issue", "list", "-l", "5");
const orgs = await sentry("org", "list", { token: "sntrys_..." });
```

Options: `token` (auth override), `text` (human output), `cwd` (working dir).
Errors throw `SentryError` with `.exitCode` and `.stderr`.

## Architecture

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

- **Zero-copy return**: `renderCommandOutput` duck-types a `captureObject`
  method on the Writer to hand back the in-memory object directly, avoiding
  the `JSON.stringify` → buffer → `JSON.parse` round-trip.

- **Single npm bundle**: esbuild entry point changes from `src/bin.ts` to
  `src/index.ts`. A tiny `dist/bin.cjs` wrapper (~200 bytes) calls
  `require("./index.cjs")._cli()`. npm package size stays flat.

- **Library-safe telemetry**: `initSentry({ libraryMode: true })` strips
  all global-polluting integrations (process listeners, HTTP trace headers,
  Function.prototype wrapping). Manual `client.flush()` replaces beforeExit.

- **CLI extraction**: `src/bin.ts` logic moved to `src/cli.ts` (exported
  functions, no top-level execution). `bin.ts` becomes a thin bun compile
  entry point.

- **`SENTRY_OUTPUT_FORMAT=json`**: New env var in `command.ts` forces JSON
  mode without `--json` flag — how the library gets JSON by default.

Author: BYK

AGENTS.md

@@ -927,4 +927,36 @@ mock.module("./some-module", () => ({
 
 <!-- lore:019cb3e6-da61-7dfe-83c2-17fe3257bece -->
 * **PR workflow: address review comments, resolve threads, wait for CI**: User's PR workflow after creation: (1) Wait for CI checks to pass, (2) Check for unresolved review comments via \`gh api\` for PR review comments, (3) Fix issues in follow-up commits (not amends), (4) Reply to the comment thread explaining the fix, (5) Resolve the thread programmatically via \`gh api graphql\` with \`resolveReviewThread\` mutation, (6) Push and wait for CI again, (7) Final sweep for any remaining unresolved comments. Use \`git notes add\` to attach implementation plans to commits. Branch naming: \`fix/descriptive-slug\` or \`feat/descriptive-slug\`.
+<!-- lore:019d2690-4df2-7ac8-82c4-54656d987339 -->
+* **Bundle uses esbuild with bun:sqlite polyfill plugin for Node.js compatibility**: \`script/bundle.ts\` uses esbuild (not Bun.build) to produce a Node.js-compatible CJS bundle at \`dist/bin.cjs\`. Key setup: \`bunSqlitePlugin\` replaces \`bun:sqlite\` imports with a polyfill from \`script/node-polyfills.ts\`. Build defines \`SENTRY\_CLI\_VERSION\` and \`SENTRY\_CLIENT\_ID\_BUILD\`, externalizes \`node:\*\` builtins. A \`sentrySourcemapPlugin\` handles debug ID injection and sourcemap upload. \*\*Bundle size constraint\*\*: the npm package size must not increase. Two output files are acceptable — one Node-optimized bundle (serves both \`npx\` CLI and library import) and a separate file for \`bun compile\` — but total npm size must stay flat. A shebang in the library bundle is acceptable. Debug IDs solve sourcemap deduplication when both bundles share the same source. Having the library entry point in the same bundle as the CLI (single file) is preferred over a second bundle when possible.
+
+<!-- lore:019d2690-4de7-75ed-b6c6-fb3deaf8871e -->
+* **getConfigDir and getAuthToken read global process.env directly**: ~14 files read \`process.env\` directly for \`SENTRY\_\*\` vars instead of using Stricli's \`context.env\`. The planned fix is \`src/lib/env.ts\` — a module-level env registry: \`getEnv()\` defaults to \`process.env\`, \`setEnv(env)\` swaps it. Library entry (\`src/index.ts\`) calls \`setEnv({ ...process.env, ...overrides })\` before Stricli, restores in \`finally\`. All \`process.env.SENTRY\_\*\` reads across ~14 files get ported to \`getEnv().SENTRY\_\*\`. Key files: \`db/auth.ts\`, \`db/index.ts\`, \`constants.ts\`, \`resolve-target.ts\`, \`telemetry.ts\`, \`formatters/plain-detect.ts\`, \`sentry-url-parser.ts\` (which also WRITES env vars). CLI mode never calls \`setEnv()\` so behavior is unchanged. Existing tests using \`useTestConfigDir()\` (which mutates \`process.env\`) continue to work since \`getEnv()\` defaults to \`process.env\`.
+
+<!-- lore:019d26a2-8d2f-7a31-81aa-e665b4dde197 -->
+* **Library API: variadic sentry() function with last-arg options detection**: The \`sentry()\` library export in \`src/index.ts\` uses variadic args with optional trailing options object: \`sentry("issue", "list", { token: "..." })\`. Last-arg detection: if final arg is an object (not string), it's \`SentryOptions\`. Options: \`token?\` (auth override, auto-fills from \`SENTRY\_AUTH\_TOKEN\`/\`SENTRY\_TOKEN\` env vars), \`text?\` (return human-readable string instead of parsed JSON), \`cwd?\` (working directory for DSN detection). Default behavior: JSON output via \`SENTRY\_OUTPUT\_FORMAT=json\` env var, parsed into object. Non-zero exit throws \`SentryError\` with \`.exitCode\` and \`.stderr\`. Successful stderr (hints/tips) silently discarded. Telemetry runs in library mode (no process listeners, no HTTP instrumentation). Env isolation via \`setEnv({ ...process.env })\` — consumer's \`process.env\` never mutated.
+
+<!-- lore:019d26a2-8d34-76ef-a855-c28a7e7796d1 -->
+* **Library mode telemetry strips all global-polluting Sentry integrations**: When \`initSentry(enabled, { libraryMode: true })\` is called, the Sentry SDK initializes without integrations that pollute the host process: no \`OnUncaughtException\`, \`OnUnhandledRejection\`, \`ProcessSession\` (process listeners), no \`Http\`/\`NodeFetch\` (trace header injection on consumer's HTTP), no \`FunctionToString\` (wraps \`Function.prototype.toString\`), no \`ChildProcess\`/\`NodeContext\`. Also disables \`enableLogs\` and \`sendClientReports\` (both use timers/\`beforeExit\`). Keeps pure integrations: \`eventFiltersIntegration\`, \`linkedErrorsIntegration\`. Library entry manually calls \`client.flush(3000)\` after command completion instead of relying on \`beforeExit\` handler. Only unavoidable global: \`globalThis.\_\_SENTRY\_\_\[SDK\_VERSION]\`.
+
+### Decision
+
+<!-- lore:019d26a2-8d3b-770a-866c-10ca04a374e7 -->
+* **OutputError propagates via throw instead of process.exit()**: The \`process.exit()\` call in \`command.ts\` (OutputError handler, line ~441) is replaced with \`throw err\` to support library mode. \`OutputError\` is re-thrown through Stricli via \`exceptionWhileRunningCommand\` in \`app.ts\` (added before the \`AuthError\` check), so Stricli never writes an error message for it. Both entry points catch it: \`bin.ts\` sets \`process.exitCode\` silently, \`index.ts\` sets \`fakeProcess.exitCode\`. Data was already rendered to stdout by the \`buildCommand\` wrapper before the throw. This eliminates the only \`process.exit()\` outside of \`bin.ts\`, making the CLI safe for in-process library invocation.
+
+### Pattern
+
+<!-- lore:019d26a2-8d37-72ea-b7bd-14fef8556fea -->
+* **SENTRY\_OUTPUT\_FORMAT env var enables JSON mode from env instead of --json flag**: In \`src/lib/command.ts\`, the \`wrappedFunc\` checks \`env.SENTRY\_OUTPUT\_FORMAT === "json"\` to force JSON output mode without passing \`--json\` on the command line. This is how the library entry point (\`src/index.ts\`) gets JSON by default — it sets this env var in the isolated env. The check runs after \`cleanRawFlags\` and only when the command has an \`output\` config (supports JSON). Commands without JSON support (help, version) are unaffected. ~5-line addition to \`command.ts\`.
+
+<!-- lore:019d2495-54da-7506-b6ba-fee422164bca -->
+* **Target argument 4-mode parsing convention (project-search-first)**: \`parseOrgProjectArg()\` in \`src/lib/arg-parsing.ts\` returns a 4-mode discriminated union: \`auto-detect\` (empty), \`explicit\` (\`org/project\`), \`org-all\` (\`org/\` trailing slash), \`project-search\` (bare slug). Bare slugs are ALWAYS \`project-search\` first. The "is this an org?" check is secondary: list commands with \`orgSlugMatchBehavior\` pre-check cached orgs (\`redirect\` or \`error\` mode), and \`handleProjectSearch()\` has a safety net checking orgs after project search fails. Non-list commands (init, view) treat bare slugs purely as project search with no org pre-check. For \`init\`, unmatched bare slugs become new project names. Key files: \`src/lib/arg-parsing.ts\` (parsing), \`src/lib/org-list.ts\` (dispatch + org pre-check), \`src/lib/resolve-target.ts\` (resolution cascade).
+
+<!-- lore:019d2690-4df5-7b2d-8194-00771eb3a9ce -->
+* **Writer type is the minimal output interface for streams and mocks**: The \`Writer\` type in \`src/types/index.ts\` is just \`{ write(data: string): void }\` — deliberately minimal to avoid Node.js stream dependencies. Used for \`context.stdout\` and \`context.stderr\` in \`SentryContext\`. Library wrappers and test harnesses can implement this trivially with string concatenation buffers instead of needing real Node.js writable streams. The \`buildContext()\` function in \`src/context.ts\` assigns \`process.stdout\`/\`process.stderr\` as writers, but any object with a \`write\` method works.
+
+### Preference
+
+<!-- lore:019d26db-3ed0-7773-85ff-72226b404b98 -->
+* **Library features require README and docs site updates**: When adding new features like the library API, documentation must be updated in both places: the root \`README.md\` (library usage section goes between Configuration and Development sections, before the \`---\` divider) and the docs website at \`docs/src/content/docs/\`. The docs site uses Astro + Starlight with sidebar defined in \`docs/astro.config.mjs\`. New pages outside \`commands/\` must be manually added to the sidebar config. Note: \`features.md\` and \`agent-guidance.md\` exist but are NOT in the sidebar — they're only reachable via direct URL.
 <!-- End lore-managed section -->

README.md

@@ -83,6 +83,35 @@ 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 sentry from "sentry";
+
+// Returns parsed JSON — same as `sentry issue list --json`
+const issues = await sentry("issue", "list", "-l", "5");
+
+// Explicit auth token (auto-fills from SENTRY_AUTH_TOKEN env var)
+const orgs = await sentry("org", "list", { token: "sntrys_..." });
+
+// Human-readable text output
+const text = await sentry("issue", "list", { text: true });
+
+// Errors are thrown as SentryError with .exitCode and .stderr
+try {
+  await sentry("issue", "view", "NONEXISTENT-1");
+} catch (err) {
+  console.error(err.exitCode, err.stderr);
+}
+```
+
+Options (all optional):
+- `token` — Auth token. Falls back to `SENTRY_AUTH_TOKEN` / `SENTRY_TOKEN` env vars.
+- `text` — Return human-readable string instead of parsed JSON.
+- `cwd` — Working directory for DSN auto-detection. Defaults to `process.cwd()`.
+
 ---
 
 ## Development

docs/astro.config.mjs

@@ -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/src/content/docs/library-usage.md

@@ -0,0 +1,133 @@
+---
+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 sentry from "sentry";
+
+// Run any CLI command — returns parsed JSON by default
+const issues = await sentry("issue", "list", "-l", "5");
+console.log(issues.data); // Array of issue objects
+```
+
+## 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 orgs = await sentry("org", "list", { token: "sntrys_..." });
+
+// Or set the env var — it's picked up automatically
+process.env.SENTRY_AUTH_TOKEN = "sntrys_...";
+const orgs = await sentry("org", "list");
+```
+
+## Options
+
+All options are optional. Pass them as the last argument:
+
+```typescript
+await sentry("issue", "list", { token: "...", text: true, cwd: "/my/project" });
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `token` | `string` | Auto-detected | Auth token for this invocation |
+| `text` | `boolean` | `false` | Return human-readable text instead of parsed JSON |
+| `cwd` | `string` | `process.cwd()` | Working directory for DSN auto-detection |
+
+## Return Values
+
+By default, commands that support JSON output return a **parsed JavaScript object**
+— no serialization overhead. Commands without JSON support (like `help` or `--version`)
+return a trimmed string.
+
+```typescript
+// Data commands → parsed object
+const issues = await sentry("issue", "list");
+// { data: [...], hasMore: true, nextCursor: "..." }
+
+// Single-entity commands → parsed object
+const issue = await sentry("issue", "view", "PROJ-123");
+// { id: "123", title: "Bug", status: "unresolved", ... }
+
+// Text commands → string
+const version = await sentry("--version");
+// "sentry 0.21.0"
+```
+
+### Text Mode
+
+Pass `{ text: true }` to get the human-readable output as a string:
+
+```typescript
+const text = await sentry("issue", "list", { text: true });
+// "ID       TITLE              STATUS\n..."
+```
+
+## Error Handling
+
+Commands that exit with a non-zero code throw a `SentryError`:
+
+```typescript
+import sentry, { SentryError } from "sentry";
+
+try {
+  await sentry("issue", "view", "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 to `sentry()` are not supported in the current version.
+Calls should be sequential (awaited one at a time).
+:::
+
+## Comparison with Subprocess
+
+| | Library (`sentry()`) | 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)

package.json

@@ -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",

script/bundle.ts

@@ -178,20 +178,17 @@ if (process.env.SENTRY_AUTH_TOKEN) {
 }
 
 const result = await build({
-  entryPoints: ["./src/bin.ts"],
+  entryPoints: ["./src/index.ts"],
   bundle: true,
   minify: true,
   banner: {
-    // Check Node.js version (>= 22 required for node:sqlite) and suppress warnings
-    js: `#!/usr/bin/env node
-if(parseInt(process.versions.node)<22){console.error("Error: sentry requires Node.js 22 or later (found "+process.version+").\\n\\nEither upgrade Node.js, or install the standalone binary instead:\\n  curl -fsSL https://cli.sentry.dev/install | bash\\n");process.exit(1)}
-{let e=process.emit;process.emit=function(n,...a){return n==="warning"?!1:e.apply(this,[n,...a])}}`,
+    js: `{let e=process.emit;process.emit=function(n,...a){return n==="warning"?!1:e.apply(this,[n,...a])}}`,
   },
   sourcemap: true,
   platform: "node",
   target: "node22",
   format: "cjs",
-  outfile: "./dist/bin.cjs",
+  outfile: "./dist/index.cjs",
   // Inject Bun polyfills and import.meta.url shim for CJS compatibility
   inject: ["./script/node-polyfills.ts", "./script/import-meta-url.js"],
   define: {
@@ -207,11 +204,45 @@ if(parseInt(process.versions.node)<22){console.error("Error: sentry requires Nod
   plugins,
 });
 
+// Write the CLI bin wrapper (tiny — shebang + version check + dispatch)
+const BIN_WRAPPER = `#!/usr/bin/env node
+if(parseInt(process.versions.node)<22){console.error("Error: sentry requires Node.js 22 or later (found "+process.version+").\\n\\nEither upgrade Node.js, or install the standalone binary instead:\\n  curl -fsSL https://cli.sentry.dev/install | bash\\n");process.exit(1)}
+require('./index.cjs')._cli().catch(()=>{});
+`;
+await Bun.write("./dist/bin.cjs", BIN_WRAPPER);
+
+// Write TypeScript declarations for the library API
+const TYPE_DECLARATIONS = `export type SentryOptions = {
+  /** Auth token. Auto-filled from SENTRY_AUTH_TOKEN / SENTRY_TOKEN env vars. */
+  token?: string;
+  /** Return human-readable text instead of parsed JSON. */
+  text?: boolean;
+  /** Working directory (affects DSN detection, project root). Defaults to process.cwd(). */
+  cwd?: string;
+};
+
+export declare class SentryError extends Error {
+  readonly exitCode: number;
+  readonly stderr: string;
+  constructor(message: string, exitCode: number, stderr: string);
+}
+
+export declare function sentry(...args: string[]): Promise<unknown>;
+export declare function sentry(...args: [...string[], SentryOptions]): Promise<unknown>;
+
+export { sentry };
+export default sentry;
+`;
+await Bun.write("./dist/index.d.cts", TYPE_DECLARATIONS);
+
+console.log("  -> dist/bin.cjs (CLI wrapper)");
+console.log("  -> dist/index.d.cts (type declarations)");
+
 // Calculate bundle size (only the main bundle, not source maps)
-const bundleOutput = result.metafile?.outputs["dist/bin.cjs"];
+const bundleOutput = result.metafile?.outputs["dist/index.cjs"];
 const bundleSize = bundleOutput?.bytes ?? 0;
 const bundleSizeKB = (bundleSize / 1024).toFixed(1);
 
-console.log(`\n  -> dist/bin.cjs (${bundleSizeKB} KB)`);
+console.log(`\n  -> dist/index.cjs (${bundleSizeKB} KB)`);
 console.log(`\n${"=".repeat(40)}`);
 console.log("Bundle complete!");