Reference
CLI reference
The CLI carries every command the editors render, usable on its own.
Every view the editors render is a CLI command underneath. The oak command is the complete backend — usable on its own, scriptable, and the single source of truth both editors thin-render. Add --json to almost any command to get its payload as data.
Setup
| Command | What it does |
|---|---|
oak init | Install the capture hooks in your user settings; --project writes them into this repository's .claude/settings.json instead. |
oak install-extensions | Side-load the VS Code + JetBrains extensions. The VS Code one then self-updates; JetBrains updates once you add its plugin repository (the command prints the step). |
oak status | Confirm the hook is installed and show what's captured. |
oak doctor | Diagnose capture and configuration problems. |
oak statusline | Install or refresh the bundled status line with the usage bars (a bash script that needs jq). |
oak uninstall | Remove the capture hooks from every settings file OAK recorded writing; oak init --repair replaces duplicated hook entries instead. |
Viewing the record
| Command | What it does |
|---|---|
oak · oak tui | The full terminal dashboard. --once prints one frame. |
oak sessions | List this machine’s sessions, grouped by workspace, leaving out sessions in which nothing happened. |
oak titles | The Remote Control titles read from claude.ai, which name sessions the way the Claude app does: when they were last read and how many are cached. --refresh reads now; --off stops the automatic read and deletes the cache; --on resumes it. |
oak inbox | Every session waiting on you, most urgent first — permission prompts with their tool, questions with their options, input waits, then finished turns. --next names the one to jump to. |
oak search | Every conversation on this machine, ranked — the asks you typed and the answers you got, across sessions and workspaces. Every word must appear; a hit in the ask outranks one in the answer. |
oak notify | Desktop notifications for raised hands: --watch announces every hand this workspace raises from a plain terminal; --message pops one to check the plumbing. |
oak prompts · oak tasklog | The prompt and task groupings. |
oak changemap | The change map for a scope. |
oak observations · oak actions | The Observations and Actions surfaces. |
oak stats · oak metrics · oak usage | Vitals, derived numbers, and token usage. oak usage --breakdown splits tokens, cache reads and estimated dollars by week, bill-cycle month, model or session, for Claude and Codex; the dollars price token counts at API list prices, carry a ~, and are never a bill. |
oak integrity | Report capture gaps and unsafe history in a session’s records, without rewriting them. |
oak fleet · oak feed | The fleet board and a live feed. |
oak risk · oak egress | The two audits. |
Reviewing
| Command | What it does |
|---|---|
oak keep · oak undo | Keep or undo the review unit an edit belongs to; --ids acts on single edits, --ids … --units widens each to its unit, and --all acts on a scope. |
oak resolve | Accept every pending edit in a session and clear its records. |
oak task-keep · oak task-undo · oak task-clear | Act on a task's strict span. |
oak redo --from-prompt | Re-apply undone edits from a prompt onward. |
oak undo … --force | Restore the whole file when a surgical undo conflicts. |
oak undo --ids … --record-only · oak redo --ids … --record-only | Record what an undo or redo already did on disk, without touching the files. OAK prints this command, with the edit ids, when the store stays busy after an undo or redo has changed the files. |
Driving and housekeeping
| Command | What it does |
|---|---|
oak agent start --kind claude|codex | Start a native agent in herdr. |
oak attach [machine] | Hand this terminal to herdr, here or on a saved machine over SSH, the way tmux attach does. |
oak prompt --session <id> --text "…" | Submit text to a session’s live herdr pane. Without one, the draft stays on the clipboard and is printed. |
oak comment · oak quote | Draft review comments on an edit’s lines, or a quote of the agent’s last reply, as one prompt. Nothing is sent until you ask: oak comment send and oak quote --send submit through herdr, and a failed send keeps the draft. |
oak conversation --session <id> [--limit N] [--since <cursor>] [--machine <label>] --json | Read the native transcript as renderer-ready updates. --limit is the last N turns of an initial read, 50 by default, and truncated reports the bytes cut above them. --since continues from the byte cursor the previous read returned; reset means the transcript was replaced, so redraw rather than append. Clients without a captured-store checkpoint can request --with-source and return its opaque source as --source <token> with the next cursor to detect replacement across processes. |
oak machine add <label> <ssh-target> | Provision and register a herdr machine. |
oak machine list --json | List saved machines. |
oak sessions [--json] | List this machine’s conversations, grouped by workspace with the current workspace first. Rows include the title, edit count, tokens, duration, model and last activity. Editor windows use the CLI on their workspace host; mirrored transcripts, bridge pointers without a local conversation, and sessions in which nothing happened are excluded. |
oak <verb> … --machine <label> | Run views, review, list, sessions, conversation, feed, multitask, subagents, diff, keep, undo, redo, resolve, comment, quote or ignore on a saved machine over SSH, where the session's store and files are, with that machine's own oak, in the session's own workspace there. Program output and exit status come back unchanged; transport failures are named. The terminal Review tab, including --once, and Observatory conversations use it for a session on another machine. OAK_MACHINE_TIMEOUT_MS overrides the 120-second overall deadline. Remote conversations, unit expansion and comment mark-sent require a compatible remote CLI and fail before acting if it is too old. |
oak doctor --fix | Repair herdr (binary, integrations, plugin, missing sidebar widths and the gruvbox theme when no theme name is set), PTY helper permissions and outdated focus servers. |
oak focus --session <id> --tab observatory | Navigate an attached OAK terminal. |
oak demo --fast | Produce a demo session to explore: an isolated demo-* session and an observatory-demo/ folder in the current directory, both removed by oak demo --clean. |
oak models | List the local Ollama models and the one Codex runs; oak models use <name> switches Codex to one. |
oak ignore --check <path> | Explain a .observatoryignore decision. |
oak store · oak clean | Locate the store; reap stale session data. |
oak sessions --delete <id> · --undelete <id> | Hide a session from OAK and purge its captured edits; the transcript itself is not deleted. --undelete lists the session again, without the purged edits. Pending edits are purged only with --force. |
oak update · oak version --check | Update OAK; check for a newer release. |
💡
Every command is a data source
Add --json to nearly any command for its raw payload. This is exactly what the editor extensions consume — which is why a number in VS Code, in JetBrains, and on the CLI is always the same number.
ℹ
Run
oak help for the full list
This page covers the commands you'll reach for; oak help lists every user-facing command with its main flags, and oak <command> --help prints the same list.
oak diff <id> --json returns session, id, file and an uncoloured patch. The same contract applies with --machine.