onepatch 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damasqas, Corp.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# onepatch
+
+The [OnePatch](https://onepatch.dev) CLI. Query your telemetry, read and reply to agent chats, and inspect incidents from a terminal or from a coding agent. It speaks to the same MCP endpoint the product serves at `/mcp`, so it has exact functional parity with connecting an MCP client.
+
+Requires [Bun](https://bun.sh).
+
+```sh
+bun install -g onepatch   # or: npm install -g onepatch
+onepatch login
+```
+
+`login` uses a device flow: it prints a URL, you approve in the browser, and credentials land in `~/.config/onepatch/credentials.json` (0600). Tokens refresh automatically.
+
+## Commands
+
+```sh
+onepatch otel query "SELECT count() FROM otel.logs WHERE ts > now() - INTERVAL 1 HOUR"
+onepatch otel ingest-config
+
+onepatch chats list
+onepatch chats read <id> [--from-turn N] [--turns N] [--tool-io]
+onepatch chats start "why is checkout slow?"
+onepatch chats reply <id> "focus on the EU region"
+
+onepatch incidents list [--scope open|all] [--severity P0|P1|P2|P3] [--limit N]
+onepatch incidents read <num> [--raw]
+
+onepatch tools     # list the server's MCP tools
+onepatch whoami
+```
+
+Pass `-` to read SQL or message text from stdin. `--json` prints raw MCP content blocks. `--api <url>` (or `ONEPATCH_API_URL`) targets a different deployment.
+
+## Programmatic use
+
+```ts
+import { onepatch } from "onepatch";
+
+const op = onepatch(); // credentials from `onepatch login`
+const logs = await op.otel.query("SELECT count() FROM otel.logs");
+const incidents = await op.incidents.list({ severity: "P1" });
+const digest = await op.chats.start("investigate the p95 spike on /checkout");
+await op.close();
+```
+
+All methods return the same plain-text digests the MCP tools produce. `op.call(name, args)` reaches any tool directly.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "onepatch",
+  "version": "0.2.0",
+  "description": "OnePatch CLI: query your telemetry, chats, and incidents from a terminal or a coding agent",
+  "license": "MIT",
+  "homepage": "https://onepatch.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1patch/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/1patch/cli/issues"
+  },
+  "keywords": ["onepatch", "observability", "sre", "cli", "mcp", "opentelemetry"],
+  "type": "module",
+  "bin": {
+    "onepatch": "./src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": ["src", "README.md", "LICENSE"],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "test": "bun test",
+    "fmt": "biome check --write .",
+    "check": "biome ci . && bun run typecheck && bun test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.8",
+    "@types/bun": "^1.3.14",
+    "@typescript/native-preview": "^7.0.0-dev.20260506.1",
+    "typescript": "^5.5.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,63 @@
+// Token lifecycle: read the stored credentials for an API base, refresh when
+// the access token is close to expiry (they live 1 hour), and persist the
+// rotated refresh token every time.
+import { type Credentials, loadCredentials, saveCredentials } from "./credentials";
+import { refreshTokens } from "./workos";
+
+export class NotLoggedInError extends Error {
+	constructor(api: string) {
+		super(`Not logged in to ${api}. Run \`onepatch login\` first.`);
+		this.name = "NotLoggedInError";
+	}
+}
+
+// Payload-only JWT decode; no signature check. The CLI never trusts these
+// claims for anything security-relevant — the server re-verifies every call —
+// it only reads `exp` for proactive refresh and identity fields for display.
+export function decodeJwtClaims(token: string): Record<string, unknown> {
+	const payload = token.split(".")[1];
+	if (!payload) return {};
+	try {
+		return JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as Record<
+			string,
+			unknown
+		>;
+	} catch {
+		return {};
+	}
+}
+
+export function tokenExpiresSoon(token: string, skewSeconds = 60): boolean {
+	const exp = decodeJwtClaims(token).exp;
+	if (typeof exp !== "number") return true;
+	return exp * 1000 - Date.now() < skewSeconds * 1000;
+}
+
+async function refreshAndSave(api: string, creds: Credentials): Promise<Credentials> {
+	const tokens = await refreshTokens(creds.clientId, creds.refreshToken);
+	const next: Credentials = {
+		...creds,
+		accessToken: tokens.accessToken,
+		refreshToken: tokens.refreshToken,
+		orgId: tokens.organizationId ?? creds.orgId,
+	};
+	saveCredentials(api, next);
+	return next;
+}
+
+export async function getValidAccessToken(api: string): Promise<string> {
+	let creds = loadCredentials(api);
+	if (!creds) throw new NotLoggedInError(api);
+	if (tokenExpiresSoon(creds.accessToken)) {
+		creds = await refreshAndSave(api, creds);
+	}
+	return creds.accessToken;
+}
+
+// Unconditional refresh — the retry path after a server-side 401 on a token
+// that still looked fresh locally (clock skew, revoked session rotated keys).
+export async function forceRefreshAccessToken(api: string): Promise<string> {
+	const creds = loadCredentials(api);
+	if (!creds) throw new NotLoggedInError(api);
+	return (await refreshAndSave(api, creds)).accessToken;
+}

package/src/cli.ts

@@ -0,0 +1,243 @@
+#!/usr/bin/env bun
+// The `onepatch` command. Thin noun-verb shell over OnepatchClient (src/client.ts);
+// all product behavior lives server-side behind /mcp.
+import { parseArgs } from "node:util";
+import { decodeJwtClaims, getValidAccessToken } from "./auth";
+import { OnepatchClient } from "./client";
+import { fetchBootstrap, resolveApiUrl } from "./config";
+import { deleteCredentials, loadCredentials, saveCredentials } from "./credentials";
+import { pollForDeviceToken, startDeviceAuthorization } from "./workos";
+
+const USAGE = `onepatch — OnePatch from the terminal
+
+Usage:
+  onepatch login                      Sign in (device flow, opens a browser code)
+  onepatch logout                     Forget stored credentials for this API
+  onepatch whoami                     Show the signed-in identity
+
+  onepatch otel query <sql|->         Run SQL against your telemetry (otel.spans/logs/metrics/histograms)
+  onepatch otel ingest-config         Ingest endpoint + token for sending telemetry
+
+  onepatch chats list                 List agent chats
+  onepatch chats read <id>            Read a chat transcript digest
+      [--from-turn N] [--turns N] [--tool-io] [--block-chars N]
+  onepatch chats start <text|->       Start a new agent chat
+  onepatch chats reply <id> <text|->  Reply in an existing chat
+
+  onepatch incidents list             List incidents
+      [--scope open|all] [--severity P0|P1|P2|P3] [--waiting-on X] [--limit N]
+  onepatch incidents read <num> [--raw]   Read one incident by number
+
+  onepatch tools                      List the server's MCP tools
+
+Global flags:
+  --api <url>    Deployment base URL (default: $ONEPATCH_API_URL or https://app.onepatch.dev)
+  --json         Print raw MCP content blocks as JSON
+  -h, --help     Show this help
+
+Pass "-" for <sql> or <text> to read it from stdin.`;
+
+function fail(message: string): never {
+	console.error(message);
+	process.exit(1);
+}
+
+async function resolveText(arg: string | undefined, what: string): Promise<string> {
+	if (arg === undefined) fail(`missing ${what}\n\n${USAGE}`);
+	if (arg !== "-") return arg;
+	const text = (await Bun.stdin.text()).trim();
+	if (!text) fail(`stdin was empty; pipe the ${what} in or pass it as an argument`);
+	return text;
+}
+
+function intFlag(value: string | undefined, name: string): number | undefined {
+	if (value === undefined) return undefined;
+	const n = Number.parseInt(value, 10);
+	if (!Number.isFinite(n)) fail(`--${name} must be an integer`);
+	return n;
+}
+
+async function login(api: string): Promise<void> {
+	const { clientId } = await fetchBootstrap(api);
+	const device = await startDeviceAuthorization(clientId);
+	console.log(`To sign in, open:\n\n  ${device.verification_uri_complete}\n`);
+	console.log(`or go to ${device.verification_uri} and enter code ${device.user_code}.\n`);
+	console.log("Waiting for approval…");
+	const tokens = await pollForDeviceToken(clientId, device);
+	const claims = decodeJwtClaims(tokens.accessToken);
+	const orgId =
+		tokens.organizationId ?? (typeof claims.org_id === "string" ? claims.org_id : undefined);
+	saveCredentials(api, {
+		clientId,
+		accessToken: tokens.accessToken,
+		refreshToken: tokens.refreshToken,
+		userId: tokens.user?.id,
+		email: tokens.user?.email,
+		orgId,
+	});
+	console.log(`\nLogged in to ${api} as ${tokens.user?.email ?? "unknown user"}.`);
+	if (orgId) {
+		console.log(`Organization: ${orgId}`);
+	} else {
+		console.log(
+			"Warning: this session is not scoped to an organization; API calls will be " +
+				"rejected. Sign in to the web app, make sure you belong to an organization, " +
+				"and run `onepatch login` again.",
+		);
+	}
+}
+
+async function whoami(api: string, json: boolean): Promise<void> {
+	const stored = loadCredentials(api);
+	if (!stored) fail(`Not logged in to ${api}. Run \`onepatch login\` first.`);
+	// Refreshes if expired, so whoami doubles as a session health check.
+	const token = await getValidAccessToken(api);
+	const claims = decodeJwtClaims(token);
+	const info = {
+		api,
+		email: stored.email ?? null,
+		userId: typeof claims.sub === "string" ? claims.sub : (stored.userId ?? null),
+		orgId: typeof claims.org_id === "string" ? claims.org_id : (stored.orgId ?? null),
+		tokenExpires: typeof claims.exp === "number" ? new Date(claims.exp * 1000).toISOString() : null,
+	};
+	if (json) {
+		console.log(JSON.stringify(info, null, 2));
+		return;
+	}
+	console.log(`api:     ${info.api}`);
+	console.log(`email:   ${info.email ?? "unknown"}`);
+	console.log(`user:    ${info.userId ?? "unknown"}`);
+	console.log(`org:     ${info.orgId ?? "none"}`);
+	console.log(`expires: ${info.tokenExpires ?? "unknown"}`);
+}
+
+async function main(): Promise<void> {
+	const { values: flags, positionals } = parseArgs({
+		args: process.argv.slice(2),
+		allowPositionals: true,
+		options: {
+			api: { type: "string" },
+			json: { type: "boolean", default: false },
+			help: { type: "boolean", short: "h", default: false },
+			"from-turn": { type: "string" },
+			turns: { type: "string" },
+			"tool-io": { type: "boolean", default: false },
+			"block-chars": { type: "string" },
+			scope: { type: "string" },
+			severity: { type: "string" },
+			"waiting-on": { type: "string" },
+			limit: { type: "string" },
+			raw: { type: "boolean", default: false },
+		},
+	});
+
+	const [noun, verb, ...rest] = positionals;
+	if (flags.help || !noun) {
+		console.log(USAGE);
+		return;
+	}
+
+	const api = resolveApiUrl(flags.api);
+
+	if (noun === "login") return await login(api);
+	if (noun === "logout") {
+		console.log(deleteCredentials(api) ? `Logged out of ${api}.` : `No credentials for ${api}.`);
+		return;
+	}
+	if (noun === "whoami") return await whoami(api, flags.json);
+
+	const client = new OnepatchClient({ api });
+	const emit = async (name: string, args: Record<string, unknown>) => {
+		if (flags.json) {
+			console.log(JSON.stringify(await client.call(name, args), null, 2));
+		} else {
+			const blocks = await client.call(name, args);
+			console.log(
+				blocks
+					.filter((b) => b.type === "text" && typeof b.text === "string")
+					.map((b) => b.text)
+					.join("\n"),
+			);
+		}
+	};
+
+	try {
+		switch (noun) {
+			case "tools": {
+				const tools = await client.tools();
+				if (flags.json) {
+					console.log(JSON.stringify(tools, null, 2));
+				} else {
+					for (const t of tools) console.log(`${t.name}\n  ${t.description.split("\n")[0]}`);
+				}
+				return;
+			}
+			case "otel": {
+				if (verb === "query") {
+					return await emit("query_otel", { sql: await resolveText(rest[0], "SQL") });
+				}
+				if (verb === "ingest-config") return await emit("get_ingest_config", {});
+				fail(`unknown otel command: ${verb ?? "(none)"}\n\n${USAGE}`);
+				break;
+			}
+			case "chats": {
+				if (verb === "list") return await emit("list_chats", {});
+				if (verb === "read") {
+					const chatId = rest[0] ?? fail(`missing chat id\n\n${USAGE}`);
+					return await emit("read_chat", {
+						chatId,
+						...(intFlag(flags["from-turn"], "from-turn") !== undefined
+							? { fromTurn: intFlag(flags["from-turn"], "from-turn") }
+							: {}),
+						...(intFlag(flags.turns, "turns") !== undefined
+							? { turnLimit: intFlag(flags.turns, "turns") }
+							: {}),
+						...(flags["tool-io"] ? { includeToolIo: true } : {}),
+						...(intFlag(flags["block-chars"], "block-chars") !== undefined
+							? { blockChars: intFlag(flags["block-chars"], "block-chars") }
+							: {}),
+					});
+				}
+				if (verb === "start") {
+					return await emit("start_chat", { text: await resolveText(rest[0], "message") });
+				}
+				if (verb === "reply") {
+					const chatId = rest[0] ?? fail(`missing chat id\n\n${USAGE}`);
+					return await emit("send_chat_reply", {
+						chatId,
+						text: await resolveText(rest[1], "message"),
+					});
+				}
+				fail(`unknown chats command: ${verb ?? "(none)"}\n\n${USAGE}`);
+				break;
+			}
+			case "incidents": {
+				if (verb === "list") {
+					return await emit("list_incidents", {
+						...(flags.scope ? { scope: flags.scope } : {}),
+						...(flags.severity ? { severity: flags.severity } : {}),
+						...(flags["waiting-on"] ? { waiting_on: flags["waiting-on"] } : {}),
+						...(intFlag(flags.limit, "limit") !== undefined
+							? { limit: intFlag(flags.limit, "limit") }
+							: {}),
+					});
+				}
+				if (verb === "read") {
+					const num = intFlag(rest[0], "incident number");
+					if (num === undefined) fail(`missing incident number\n\n${USAGE}`);
+					return await emit("read_incident", { num, ...(flags.raw ? { raw: true } : {}) });
+				}
+				fail(`unknown incidents command: ${verb ?? "(none)"}\n\n${USAGE}`);
+				break;
+			}
+			default:
+				fail(`unknown command: ${noun}\n\n${USAGE}`);
+		}
+	} finally {
+		await client.close();
+	}
+}
+
+main().catch((err: unknown) => {
+	fail(err instanceof Error ? err.message : String(err));
+});

package/src/client.ts

@@ -0,0 +1,154 @@
+// The programmatic surface: a fluent, promise-returning client over the
+// OnePatch MCP endpoint. Exact functional parity with the served MCP tools —
+// the CLI is an MCP client, so no server behavior is duplicated here.
+//
+//   const op = onepatch();                      // creds from `onepatch login`
+//   await op.otel.query("SELECT count() FROM otel.logs");
+//   await op.incidents.list({ severity: "P1" });
+//   const { chatId } = await op.chats.start("why is checkout slow?");
+//   await op.chats.reply(chatId, "focus on the EU region");
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { forceRefreshAccessToken, getValidAccessToken } from "./auth";
+import { resolveApiUrl } from "./config";
+
+export type OnepatchClientOptions = {
+	// Base URL of the deployment, e.g. https://app.onepatch.dev. Defaults to
+	// ONEPATCH_API_URL, then the hosted production URL.
+	api?: string;
+	// Bypass the credential store with an explicit bearer token (headless use).
+	accessToken?: string;
+};
+
+export type ReadChatOptions = {
+	fromTurn?: number;
+	turnLimit?: number;
+	includeToolIo?: boolean;
+	blockChars?: number;
+};
+
+export type ListIncidentsOptions = {
+	scope?: "open" | "all";
+	severity?: "P0" | "P1" | "P2" | "P3";
+	waitingOn?: string;
+	limit?: number;
+};
+
+export type ToolContentBlock = { type: string; text?: string; [key: string]: unknown };
+
+function textOf(blocks: ToolContentBlock[]): string {
+	return blocks
+		.filter((b) => b.type === "text" && typeof b.text === "string")
+		.map((b) => b.text as string)
+		.join("\n");
+}
+
+export class OnepatchClient {
+	readonly api: string;
+	private readonly accessTokenOverride: string | null;
+	private clientPromise: Promise<Client> | null = null;
+
+	constructor(options: OnepatchClientOptions = {}) {
+		this.api = resolveApiUrl(options.api);
+		this.accessTokenOverride = options.accessToken ?? null;
+	}
+
+	readonly otel = {
+		query: (sql: string) => this.callText("query_otel", { sql }),
+		ingestConfig: () => this.callText("get_ingest_config", {}),
+	};
+
+	readonly chats = {
+		list: () => this.callText("list_chats", {}),
+		read: (chatId: string, opts: ReadChatOptions = {}) =>
+			this.callText("read_chat", { chatId, ...opts }),
+		// Returns the digest text, which leads with the new chat id.
+		start: (text: string) => this.callText("start_chat", { text }),
+		reply: (chatId: string, text: string) => this.callText("send_chat_reply", { chatId, text }),
+	};
+
+	readonly incidents = {
+		list: (opts: ListIncidentsOptions = {}) =>
+			this.callText("list_incidents", {
+				...(opts.scope ? { scope: opts.scope } : {}),
+				...(opts.severity ? { severity: opts.severity } : {}),
+				...(opts.waitingOn ? { waiting_on: opts.waitingOn } : {}),
+				...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+			}),
+		read: (num: number, opts: { raw?: boolean } = {}) =>
+			this.callText("read_incident", { num, ...opts }),
+	};
+
+	async tools(): Promise<{ name: string; description: string }[]> {
+		const client = await this.connect();
+		const res = await client.listTools();
+		return res.tools.map((t) => ({ name: t.name, description: t.description ?? "" }));
+	}
+
+	// Raw tool call — returns the MCP content blocks (for --json and new tools
+	// this client has no sugar for yet). Throws on tool-level errors.
+	async call(name: string, args: Record<string, unknown>): Promise<ToolContentBlock[]> {
+		const blocks = await this.callWithAuthRetry(name, args);
+		return blocks;
+	}
+
+	async close(): Promise<void> {
+		if (!this.clientPromise) return;
+		const client = await this.clientPromise.catch(() => null);
+		this.clientPromise = null;
+		await client?.close().catch(() => {});
+	}
+
+	private async callText(name: string, args: Record<string, unknown>): Promise<string> {
+		return textOf(await this.callWithAuthRetry(name, args));
+	}
+
+	private async callWithAuthRetry(
+		name: string,
+		args: Record<string, unknown>,
+	): Promise<ToolContentBlock[]> {
+		try {
+			return await this.callOnce(name, args);
+		} catch (err) {
+			// A 401 mid-session means the token aged out server-side; refresh once
+			// and retry on a fresh connection. Explicit-token clients can't refresh.
+			if (this.accessTokenOverride || !/\b401\b/.test(String(err))) throw err;
+			this.clientPromise = null;
+			await forceRefreshAccessToken(this.api);
+			return await this.callOnce(name, args);
+		}
+	}
+
+	private async callOnce(name: string, args: Record<string, unknown>): Promise<ToolContentBlock[]> {
+		const client = await this.connect();
+		const result = await client.callTool({ name, arguments: args });
+		const blocks = (result.content ?? []) as ToolContentBlock[];
+		if (result.isError) {
+			throw new Error(textOf(blocks) || `tool ${name} failed`);
+		}
+		return blocks;
+	}
+
+	private connect(): Promise<Client> {
+		if (!this.clientPromise) {
+			this.clientPromise = (async () => {
+				const token = this.accessTokenOverride ?? (await getValidAccessToken(this.api));
+				const transport = new StreamableHTTPClientTransport(new URL(`${this.api}/mcp`), {
+					requestInit: { headers: { authorization: `Bearer ${token}` } },
+				});
+				const client = new Client({ name: "onepatch-cli", version: "0.1.0" });
+				await client.connect(transport);
+				return client;
+			})().catch((err) => {
+				// Don't cache a failed connection — the next call retries fresh.
+				this.clientPromise = null;
+				throw err;
+			});
+		}
+		return this.clientPromise;
+	}
+}
+
+export function onepatch(options: OnepatchClientOptions = {}): OnepatchClient {
+	return new OnepatchClient(options);
+}

package/src/config.ts

@@ -0,0 +1,31 @@
+// Which OnePatch deployment the CLI talks to. Everything else — the WorkOS
+// client id for login, the MCP endpoint — is discovered from this one URL via
+// `GET /.well-known/onepatch-cli`, so the CLI ships with zero baked-in config.
+export const DEFAULT_API_URL = "https://app.onepatch.dev";
+
+export function resolveApiUrl(flag?: string): string {
+	const raw = flag ?? process.env.ONEPATCH_API_URL ?? DEFAULT_API_URL;
+	return raw.replace(/\/+$/, "");
+}
+
+export type CliBootstrap = { clientId: string; mcpUrl: string };
+
+// Fetch the server's CLI bootstrap document. The client id is public by
+// design (it already ships in the web app's browser bundle).
+export async function fetchBootstrap(
+	api: string,
+	fetchImpl: typeof fetch = fetch,
+): Promise<CliBootstrap> {
+	const res = await fetchImpl(`${api}/.well-known/onepatch-cli`);
+	if (!res.ok) {
+		throw new Error(
+			`${api} did not answer the CLI bootstrap probe (${res.status}). ` +
+				"Check the URL, or pass --api <url> if this deployment lives elsewhere.",
+		);
+	}
+	const doc = (await res.json()) as { client_id?: unknown; mcp_url?: unknown };
+	if (typeof doc.client_id !== "string" || typeof doc.mcp_url !== "string") {
+		throw new Error(`${api} returned a malformed CLI bootstrap document.`);
+	}
+	return { clientId: doc.client_id, mcpUrl: doc.mcp_url };
+}

package/src/credentials.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	credentialsPath,
+	deleteCredentials,
+	loadCredentials,
+	saveCredentials,
+} from "./credentials";
+
+const CREDS = {
+	clientId: "client_01TEST",
+	accessToken: "at",
+	refreshToken: "rt",
+	email: "dev@example.com",
+};
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "onepatch-cli-test-"));
+	process.env.ONEPATCH_CONFIG_DIR = dir;
+});
+
+afterEach(() => {
+	delete process.env.ONEPATCH_CONFIG_DIR;
+	rmSync(dir, { recursive: true, force: true });
+});
+
+describe("credential store", () => {
+	test("round-trips per API base and deletes cleanly", () => {
+		expect(loadCredentials("https://a.example")).toBeNull();
+		saveCredentials("https://a.example", CREDS);
+		saveCredentials("https://b.example", { ...CREDS, email: "other@example.com" });
+		expect(loadCredentials("https://a.example")?.email).toBe("dev@example.com");
+		expect(loadCredentials("https://b.example")?.email).toBe("other@example.com");
+		expect(deleteCredentials("https://a.example")).toBe(true);
+		expect(loadCredentials("https://a.example")).toBeNull();
+		expect(loadCredentials("https://b.example")?.email).toBe("other@example.com");
+		expect(deleteCredentials("https://a.example")).toBe(false);
+	});
+
+	test("credential file is written 0600", () => {
+		saveCredentials("https://a.example", CREDS);
+		const mode = statSync(credentialsPath()).mode & 0o777;
+		expect(mode).toBe(0o600);
+	});
+});

package/src/credentials.ts

@@ -0,0 +1,59 @@
+// On-disk credential store: one JSON file keyed by API base URL, so a login
+// against staging and one against prod coexist. The file holds real bearer
+// material (access + refresh tokens), so it is written 0600 inside a 0700 dir.
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type Credentials = {
+	clientId: string;
+	accessToken: string;
+	refreshToken: string;
+	userId?: string;
+	email?: string;
+	orgId?: string;
+};
+
+type CredentialsFile = Record<string, Credentials>;
+
+export function credentialsPath(): string {
+	const dir =
+		process.env.ONEPATCH_CONFIG_DIR ??
+		join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "onepatch");
+	return join(dir, "credentials.json");
+}
+
+function readFile(): CredentialsFile {
+	try {
+		return JSON.parse(readFileSync(credentialsPath(), "utf8")) as CredentialsFile;
+	} catch {
+		return {};
+	}
+}
+
+export function loadCredentials(api: string): Credentials | null {
+	return readFile()[api] ?? null;
+}
+
+export function saveCredentials(api: string, creds: Credentials): void {
+	const path = credentialsPath();
+	const dir = join(path, "..");
+	mkdirSync(dir, { recursive: true, mode: 0o700 });
+	const all = readFile();
+	all[api] = creds;
+	writeFileSync(path, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+	// mkdir/write modes only apply on creation; converge pre-existing files too.
+	chmodSync(path, 0o600);
+}
+
+export function deleteCredentials(api: string): boolean {
+	const all = readFile();
+	if (!(api in all)) return false;
+	delete all[api];
+	if (Object.keys(all).length === 0) {
+		rmSync(credentialsPath(), { force: true });
+	} else {
+		writeFileSync(credentialsPath(), `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+	}
+	return true;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// Programmatic entry point:  import { onepatch } from "onepatch";
+export {
+	type ListIncidentsOptions,
+	OnepatchClient,
+	type OnepatchClientOptions,
+	onepatch,
+	type ReadChatOptions,
+	type ToolContentBlock,
+} from "./client";
+export { DEFAULT_API_URL, resolveApiUrl } from "./config";

package/src/workos.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { type DeviceAuthorization, pollForDeviceToken, refreshTokens } from "./workos";
+
+const DEVICE: DeviceAuthorization = {
+	device_code: "dev_123",
+	user_code: "ABCD-1234",
+	verification_uri: "https://auth.example/device",
+	verification_uri_complete: "https://auth.example/device?code=ABCD-1234",
+	expires_in: 300,
+	interval: 5,
+};
+
+// A fetch stub that answers the authenticate endpoint from a scripted queue.
+function scriptedFetch(responses: Array<{ status: number; body: unknown }>): {
+	fetchImpl: typeof fetch;
+	requests: URLSearchParams[];
+} {
+	const requests: URLSearchParams[] = [];
+	const fetchImpl = (async (_url: string | URL | Request, init?: RequestInit) => {
+		requests.push(new URLSearchParams(String(init?.body ?? "")));
+		const next = responses.shift();
+		if (!next) throw new Error("scripted fetch exhausted");
+		return Response.json(next.body, { status: next.status });
+	}) as typeof fetch;
+	return { fetchImpl, requests };
+}
+
+const TOKENS = {
+	access_token: "at_new",
+	refresh_token: "rt_new",
+	user: { id: "user_1", email: "dev@example.com" },
+	organization_id: "org_1",
+};
+
+describe("pollForDeviceToken", () => {
+	test("keeps polling through authorization_pending, widens on slow_down, then succeeds", async () => {
+		const sleeps: number[] = [];
+		const { fetchImpl, requests } = scriptedFetch([
+			{ status: 400, body: { error: "authorization_pending" } },
+			{ status: 400, body: { error: "slow_down" } },
+			{ status: 200, body: TOKENS },
+		]);
+		const result = await pollForDeviceToken("client_01TEST", DEVICE, {
+			fetchImpl,
+			sleep: async (ms) => {
+				sleeps.push(ms);
+			},
+		});
+		expect(result.accessToken).toBe("at_new");
+		expect(result.refreshToken).toBe("rt_new");
+		expect(result.user?.email).toBe("dev@example.com");
+		expect(result.organizationId).toBe("org_1");
+		// 5s while pending, then 5+5=10s after slow_down.
+		expect(sleeps).toEqual([5000, 10000]);
+		expect(requests[0]?.get("grant_type")).toBe("urn:ietf:params:oauth:grant-type:device_code");
+		expect(requests[0]?.get("device_code")).toBe("dev_123");
+	});
+
+	test("access_denied stops with a clear error", async () => {
+		const { fetchImpl } = scriptedFetch([{ status: 400, body: { error: "access_denied" } }]);
+		await expect(
+			pollForDeviceToken("client_01TEST", DEVICE, { fetchImpl, sleep: async () => {} }),
+		).rejects.toThrow(/denied/);
+	});
+
+	test("expired_token tells the user to log in again", async () => {
+		const { fetchImpl } = scriptedFetch([{ status: 400, body: { error: "expired_token" } }]);
+		await expect(
+			pollForDeviceToken("client_01TEST", DEVICE, { fetchImpl, sleep: async () => {} }),
+		).rejects.toThrow(/login/);
+	});
+});
+
+describe("refreshTokens", () => {
+	test("sends the refresh grant and parses rotated tokens", async () => {
+		const { fetchImpl, requests } = scriptedFetch([{ status: 200, body: TOKENS }]);
+		const result = await refreshTokens("client_01TEST", "rt_old", fetchImpl);
+		expect(result.refreshToken).toBe("rt_new");
+		expect(requests[0]?.get("grant_type")).toBe("refresh_token");
+		expect(requests[0]?.get("refresh_token")).toBe("rt_old");
+	});
+
+	test("a rejected refresh surfaces as a re-login prompt", async () => {
+		const { fetchImpl } = scriptedFetch([{ status: 400, body: { error: "invalid_grant" } }]);
+		await expect(refreshTokens("client_01TEST", "rt_old", fetchImpl)).rejects.toThrow(/login/);
+	});
+});

package/src/workos.ts

@@ -0,0 +1,150 @@
+// WorkOS user-management device-authorization grant (RFC 8628), spoken as a
+// public client: client_id only, no secret anywhere. The server accepts the
+// resulting access token on /mcp via its first-party issuer branch.
+//
+// Empirically verified against WorkOS staging 2026-08-31:
+//   - POST /user_management/authorize/device is form-encoded, client_id only.
+//   - Polling POST /user_management/authenticate answers `authorization_pending`
+//     until approval, `slow_down` to widen the interval, and
+//     `expired_token` / `access_denied` / `invalid_grant` terminally.
+//   - Tokens refresh with grant_type=refresh_token + client_id (rotating
+//     refresh token: every refresh answer carries a NEW one — always persist it).
+const WORKOS_API = "https://api.workos.com";
+
+export type DeviceAuthorization = {
+	device_code: string;
+	user_code: string;
+	verification_uri: string;
+	verification_uri_complete: string;
+	expires_in: number;
+	interval: number;
+};
+
+export type AuthUser = { id: string; email: string };
+
+export type AuthTokens = {
+	accessToken: string;
+	refreshToken: string;
+	user: AuthUser | null;
+	organizationId: string | null;
+};
+
+type FetchLike = typeof fetch;
+
+async function postForm(
+	path: string,
+	params: Record<string, string>,
+	fetchImpl: FetchLike,
+): Promise<{ status: number; body: Record<string, unknown> }> {
+	const res = await fetchImpl(`${WORKOS_API}${path}`, {
+		method: "POST",
+		headers: { "content-type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams(params).toString(),
+	});
+	let body: Record<string, unknown> = {};
+	try {
+		body = (await res.json()) as Record<string, unknown>;
+	} catch {
+		// Non-JSON error bodies fall through with an empty object.
+	}
+	return { status: res.status, body };
+}
+
+function parseTokens(body: Record<string, unknown>): AuthTokens {
+	const accessToken = body.access_token;
+	const refreshToken = body.refresh_token;
+	if (typeof accessToken !== "string" || typeof refreshToken !== "string") {
+		throw new Error("WorkOS returned a token response without access/refresh tokens.");
+	}
+	const rawUser = body.user as { id?: unknown; email?: unknown } | undefined;
+	const user =
+		rawUser && typeof rawUser.id === "string" && typeof rawUser.email === "string"
+			? { id: rawUser.id, email: rawUser.email }
+			: null;
+	return {
+		accessToken,
+		refreshToken,
+		user,
+		organizationId: typeof body.organization_id === "string" ? body.organization_id : null,
+	};
+}
+
+export async function startDeviceAuthorization(
+	clientId: string,
+	fetchImpl: FetchLike = fetch,
+): Promise<DeviceAuthorization> {
+	const { status, body } = await postForm(
+		"/user_management/authorize/device",
+		{ client_id: clientId },
+		fetchImpl,
+	);
+	if (status !== 200 || typeof body.device_code !== "string") {
+		throw new Error(`WorkOS refused device authorization (${status}): ${JSON.stringify(body)}`);
+	}
+	return body as unknown as DeviceAuthorization;
+}
+
+export type PollOptions = {
+	fetchImpl?: FetchLike;
+	sleep?: (ms: number) => Promise<void>;
+	onPending?: () => void;
+};
+
+export async function pollForDeviceToken(
+	clientId: string,
+	device: DeviceAuthorization,
+	opts: PollOptions = {},
+): Promise<AuthTokens> {
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+	let intervalSeconds = device.interval > 0 ? device.interval : 5;
+	const deadline = Date.now() + device.expires_in * 1000;
+
+	while (Date.now() < deadline) {
+		const { status, body } = await postForm(
+			"/user_management/authenticate",
+			{
+				grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+				device_code: device.device_code,
+				client_id: clientId,
+			},
+			fetchImpl,
+		);
+		if (status === 200) return parseTokens(body);
+		const error = typeof body.error === "string" ? body.error : "unknown_error";
+		switch (error) {
+			case "authorization_pending":
+				opts.onPending?.();
+				break;
+			case "slow_down":
+				intervalSeconds += 5;
+				break;
+			case "access_denied":
+				throw new Error("Sign-in was denied in the browser.");
+			case "expired_token":
+			case "invalid_grant":
+				throw new Error("The sign-in request expired. Run `onepatch login` again.");
+			default:
+				throw new Error(`WorkOS authentication failed (${status}): ${error}`);
+		}
+		await sleep(intervalSeconds * 1000);
+	}
+	throw new Error("The sign-in request expired. Run `onepatch login` again.");
+}
+
+export async function refreshTokens(
+	clientId: string,
+	refreshToken: string,
+	fetchImpl: FetchLike = fetch,
+): Promise<AuthTokens> {
+	const { status, body } = await postForm(
+		"/user_management/authenticate",
+		{ grant_type: "refresh_token", refresh_token: refreshToken, client_id: clientId },
+		fetchImpl,
+	);
+	if (status !== 200) {
+		const error = typeof body.error === "string" ? body.error : `http_${status}`;
+		throw new Error(`Session expired (${error}). Run \`onepatch login\` again.`);
+	}
+	return parseTokens(body);
+}