onepatch

The OnePatch 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.

# From the repo you want OnePatch to look after:
curl -fsSL https://app.onepatch.dev/install.sh | sh

# or, with Node:
npm install -g onepatch
onepatch onboard

The CLI is a single self-contained binary (compiled with Bun, so Bun is not needed). npm install -g onepatch installs a small Node launcher that fetches the binary for your platform from https://releases.onepatch.dev/v<version>/ and verifies its SHA-256 against the checksum shipped inside the package; the installer script does the same without Node. Releases carry binaries for macOS (arm64, x64), Linux (x64, arm64), and Windows (x64).

onboard does the whole sign-up from the terminal: sign in or create an account (one browser step), create your workspace, wait for it to come up, connect GitHub (one more browser step), and link the repo you ran it in. Re-running it is safe; it picks up wherever you left off. --workspace <name>, --repo <owner/repo>, --org <name|id> override what it would infer, --no-browser prints URLs without opening them, and ONEPATCH_NO_ONBOARD=1 makes the installer stop after installing.

Outside a GitHub checkout, an interactive run asks you to choose a repository. Without a terminal, pass --repo owner/repo. Onboarding exits unsuccessfully if a required setup step or coding-agent installation fails; rerun it to resume. Each agent's MCP sign-in and Cursor's in-app plugin installation remain explicit follow-up steps printed by the installer.

login on its own uses the same device flow: it prints a URL, you approve in the browser, and credentials land in ~/.config/onepatch/credentials.json (0600). Tokens refresh automatically.

Commands

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

onepatch install   # wire this machine's coding agents (Claude Code, Codex, Cursor)

Pass - to read SQL or message text from stdin. --json prints a versioned domain result ({schemaVersion:1,data:...}). --raw-json preserves the pre-0.8 MCP content-block array. Tools without structured data return data:null and content; the CLI never guesses fields by parsing prose. --api <url> (or ONEPATCH_API_URL) targets a different deployment.

Coding agents

onepatch install detects Claude Code, Codex, and Cursor and wires each one to OnePatch: the OnePatch plugin (a skill that teaches the agent the tools above) plus the remote MCP server, discovered from the deployment's /.well-known/onepatch-cli. It is idempotent — re-run it any time to repair or upgrade. Target one agent with onepatch install <claude|codex|cursor>, or install by hand from claude-code-plugin, codex-plugin, or cursor-plugin.

Installing with --api updates existing MCP connections to that deployment. Claude's plugin receives the discovered endpoint through its user configuration; Codex keeps the plugin's skills and hooks and uses one configured MCP connection. Agent hooks remember their installed deployment without changing the default for ordinary CLI commands. Switching deployments requires signing in to the new MCP endpoint.

Updates

The CLI keeps itself current. Once a day, in a detached background process, it asks the npm registry for the latest version; when one exists it either reinstalls itself through the package manager that owns the copy (npm or bun) or, for a standalone binary, downloads the new release, verifies it, and swaps it in place. It prints a one-line notice to stderr. The command you typed is never delayed and never fails because of update machinery. Set ONEPATCH_NO_UPDATE=1 to disable it, or run onepatch update to update on demand. Running from a source checkout never auto-updates. Self-update of a standalone binary isn't available on Windows yet; re-run the installer there.

Programmatic use

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. The programmatic API runs under Bun (it imports the TypeScript sources shipped in the package) and needs @modelcontextprotocol/sdk installed alongside; the CLI itself has no dependencies.

Agent workflows (0.8)

onepatch context --json
onepatch tools list
onepatch tools describe query_otel
onepatch tools run list_dashboards --input '{}' --json
onepatch skills list
onepatch skills read onepatch-investigate
onepatch skills install                       # bundled workflows, ~/.agents/skills
onepatch skills install onepatch-deploy-check --directory ./review-skills
onepatch chats start "Investigate the checkout error spike after the deploy" --wait --json
onepatch chats wait <chatId> --send-id <sendId> --timeout 300 --json

Tool discovery fetches the current server catalog, including paginated tools. list stays compact; describe loads one complete schema and side-effect annotations. tools run accepts a JSON object, or --input - for stdin. Calls use the same authenticated workspace and permissions as MCP.

context bounds repository, service and incident lists and reports total counts. Telemetry covers the last hour and excludes OnePatch-generated signals. Unavailable sections are explicit; empty data is not a health claim. Skills include the public workspace catalog plus three self-contained SRE workflows. Installation writes Markdown only; it never runs scripts or follows skill-supplied file paths, and refuses to overwrite differing local documents. Bundled skill reads and installation work offline. An explicit skills install <id> can install a public workspace skill; supporting assets are not copied.

Chat start/reply return structured {chatId,sendId,status:"accepted"} receipts. --wait follows that exact message, not the latest answer in a busy chat. The default timeout is 300 seconds, configurable from 1 to 1800 seconds. Timeout or Ctrl-C leaves server work running; resume using the receipt printed to stderr and included in the final JSON result. Successful completion exits 0; failed/unsupported tracking exits 1, needs-input exits 2, timeout exits 3 and interruption exits 130. A polling transport error returns status:"unavailable" with the receipt and exits 1. No wait path resends a message. Native incident coordinator replies are followed through incidents read, not SDK turn waits.

--json is a deliberate format change in 0.8; scripts consuming the previous array should use --raw-json. Progress stays on stderr. The programmatic op.call() still returns content blocks; op.result() also exposes structured content. New wait/context/skills features require the matching server release; ordinary commands retain compatibility with older servers. Every public command has focused --help output.