# CLI reference Every public `oak` command, grouped by what it's for. Run `oak --help` for the same information in your terminal; `oak` with no arguments prints a grouped overview. ## Global options | Option | Effect | |---|---| | `--verbose` | Print per-phase timings. Goes **before** the command: `oak --verbose push`. Same as `OAK_VERBOSE=1`. | | `-h`, `--help` | Help for any command or subcommand. | | `--version` | Print the CLI version. | Commands that talk to a server take `-r, --remote ` (default `https://oak.space`). The server used is: the flag, then `OAK_REMOTE`, then the one the checkout is linked to, then the default. Most commands take `--json` for machine-readable output. Environment variables are listed in [Files and environment variables](/docs/configuration). ## Exit codes | Code | Meaning | |---|---| | `0` | Success. | | `1` | General error. | | `2` | Usage error (bad flags or arguments, or an interactive prompt with no terminal). | | `3` | Repository locked by another `oak` process — retry. (`oak ci status`: still running.) | | `4` | The working tree has uncommitted changes that block the operation. | | `5` | Merge or sync conflicts, or a conflict is already in progress. | | `6` | Network, server, or authentication failure. | | `7` | Merge prediction couldn't be certified. | | `8` | An integrity check ran out of budget — inconclusive. | ## Setup and sign-in ### oak init ```text oak init [PATH] ``` Create a repository in `PATH` (default: the current directory) and put you on a personal branch parented onto `main`. On a terminal it offers to import an existing `.git` history, to write an `.oakignore` for a detected Godot / Unity / Unreal project, and to write an `AGENTS.md` for coding agents. Refuses to run in your home directory. ### oak clone ```text oak clone [ORG/REPO | GIT-URL] [DEST] ``` Clone a repository and put you on a personal branch. With no argument, pick from a list. A bare `REPO` means your personal organization. A Git URL is imported instead — see [Git import](/docs/git#import-with-oak-clone). | Flag | Effect | |---|---| | `--branch ` | Switch to this remote branch after cloning. | | `--expected-head ` | With `--branch`: fail unless the branch is open at exactly this commit. | | `--shallow` | Only the latest commit on `main`. | | `--path ` | [Sparse clone](/docs/sparse-clones): only these paths. Repeatable or comma-separated. | | `--detached` | Check out `main`'s head with no personal branch. | | `--from ` | Reuse content from another local checkout of the same repo. | | `--json` | Print a machine-readable receipt. | | `--allow-unverified-integrity` | Continue when the server's integrity proof is inconclusive (otherwise exit 8). | | `-r, --remote ` | Server to clone from. | ### oak login / logout / whoami ```text oak login [-r URL] oak logout [-r URL] oak whoami [-r URL] ``` `oak login` signs in through your browser (or prints a URL and asks for a one-time code when there's no browser) and saves a token in `~/.oak/credentials`. `whoami` prints the signed-in username. See [Install and sign in](/docs/install#sign-in). ### oak auth status ```text oak auth status [--json] [-r URL] ``` Show which credential the CLI would use — `OAK_API_KEY`, the checkout's key, or your login — and who the server says it belongs to. Never prints the secret. ### oak repo list ```text oak repo list [--org ORG] [--limit N] [--json] [-r URL] ``` List repositories you can see (public ones only when signed out). `--limit` defaults to 200. ### oak skill install ```text oak skill install [--global] ``` Install the bundled `oak-vcs` agent skill into `./.claude/skills/` (or `~/.claude/skills/` with `--global`). Re-run after upgrading. See [Working with agents](/docs/agents#install-the-agent-skill). ### oak upgrade ```text oak upgrade [-f] [--canary] ``` Upgrade to the latest signed release. `-f` skips the confirmation; `--canary` follows the pre-release channel. ### oak completions ```text oak completions ``` Print a shell-completion script. ## Working tree ### oak status ```text oak status [--json [--compact]] [--short | --porcelain] [--reconcile] ``` Show modified, added, and deleted files. `--short` / `--porcelain` print Git-compatible short rows; `--json --compact` is bounded output for agents; `--reconcile` applies any pending reconciliation after a remote merge first. ### oak diff ```text oak diff [REV [REV]] [PATHS...] [options] ``` Show changes. With no revision: the working tree against your last checkpoint. One branch name: what that branch contributes, no checkout needed. One commit: that commit against the working tree. Two revisions: between them. On a terminal, opens the full-screen viewer. | Flag | Effect | |---|---| | `--branch` | The whole current branch (checkpoints + uncommitted) against where it forked. | | `--against ` | Base for a branch endpoint (default: its parent). | | `--mode ` | Perspective for branch endpoints. See [Reviewing](/docs/reviewing#read-a-diff-without-switching). | | `--print` | Print a unified diff instead of opening the viewer. | | `--stat` | Per-file added/removed counts. | | `--name-only` | Only the changed paths. | | `--word-diff` | With `--print`: mark changes within lines. | | `-U, --unified ` | Lines of context. | | `--check` | Report whitespace errors and conflict markers; exit 1 if any. | | `--exit-code` | Exit 1 if there are differences, 0 if not. | | `-a, --text` | Treat large text files as text. | | `--json` | Machine-readable summary. Add `--hunks` for patch text, `--max-bytes ` to cap it, `--changed-files-limit` / `--changed-files-offset` to page. | | `--remote ` | Diff two exact commits on the server, with `--json` or `--print`. | ### oak commit ```text oak commit [PATHS...] [--push] [--no-verify] [--json] [--quiet] ``` Save a local checkpoint of every change (or only those under `PATHS`). Takes no message: `-m` is refused — describe the branch with `oak desc`. `--push` publishes afterwards; `--no-verify` skips [hooks](/docs/making-changes#hooks). ### oak restore ```text oak restore [PATHS...] [-s COMMIT] [-f] ``` Restore files (or everything) to the last checkpoint, or to `COMMIT`. Asks first unless `-f`. ### oak reset ```text oak reset [PATH] [-f] ``` Discard uncommitted changes — everything, or under `PATH`. Asks first unless `-f`. ### oak change ```text oak change capture [PATHS...] [--json] oak change export --output [--json] ``` Store uncommitted changes as an immutable capture without committing or touching the working tree; export one as a zip. See [History](/docs/history#save-uncommitted-work-without-committing). ## Branches ### oak switch ```text oak switch [NAME] [-c] [--clean] [-d] ``` Switch to a branch (fetching it if needed). With no name, pick from a list. | Flag | Effect | |---|---| | `-c, --create` | Create a branch off the latest `main` and switch to it. The name is optional. | | `--clean` | Start from the latest `main` and discard working-tree changes. | | `-d, --detach` | Treat `NAME` as a commit and detach HEAD there. | ### oak checkout ```text oak checkout ``` Detach HEAD at a commit (full hash or a unique prefix of 4+ characters). ### oak desc ```text oak desc [DESCRIPTION | --file FILE] [--append] [--json] ``` Set the current branch's description — the commit message it will merge with. `--file -` reads stdin; `--append` adds a paragraph and refuses if your copy is stale. See [Descriptions](/docs/branches#descriptions). ### oak branch ```text oak branch [--show-current] [--json] oak branch list [--remote] [--status open|closed] [--json] oak branch show [--remote] [--json] oak branch rename ``` List branches, print the current one, or show one branch's details. `--remote` reads the server. `rename` is temporarily disabled. ### oak close ```text oak close [NAME...] [--remote] [--reason TEXT] [--json] ``` Close a branch (default: the current one). `--remote --json` closes pushed branches without switching to them, several at once. ### oak split ```text oak split [--from BRANCH] [--plan FILE] [--dry-run] ``` Reorder or drop a branch's commits, or split them into separate branches (`oak histedit` is an alias). `--plan` applies a todo list non-interactively (`-` for stdin). ### oak finish ```text oak finish (--desc TEXT | --desc-file FILE) [--json] ``` Set the description, checkpoint, and push — after checking it can. Inside a mount, also unmounts once the push succeeds. See [Working with agents](/docs/agents#finishing-a-task-in-one-command). ## Merging and conflicts ### oak merge ```text oak merge [BRANCH] [--wait[=MINUTES]] [--force] [--dry-run] [--json] oak merge --continue | --abort ``` Squash-merge a branch (default: the current one) onto `main` and close it. | Flag | Effect | |---|---| | `--wait[=MINUTES]` | Wait for CI to finish (default 30 minutes), then merge if it passed. | | `--force` | Merge even though CI is red or running. | | `--dry-run` | With `--json`: predict the merge locally; changes nothing. | | `--continue` / `--abort` | Finish or cancel a merge after resolving conflicts. | ### oak conflict ```text oak conflict status [--json] oak conflict show [--json] oak conflict take (--ours | --theirs) [--json] ``` Inspect an in-progress merge, pull, or mount-pull conflict, and resolve a file by taking one side of every conflict block. See [Resolving conflicts](/docs/merging#resolving-conflicts). ### oak agent ```text oak agent state --json [--compact] [--refresh] ``` One JSON document with the repository's state and `recommended_next_commands`. `--refresh` checks the server first. ## Syncing ### oak push ```text oak push [--repo ORG/REPO] [-f] [--json] [--plan --json] [-r URL] ``` Publish the current branch. `--repo` (or `OAK_REPO`) links a new repo on its first push without a prompt — the organization must exist; the repo is created. `-f` overwrites a diverged remote branch. `--plan --json` reports what would be sent without sending it. ### oak pull ```text oak pull [--branch-only] [-f] [--json] [-r URL] oak pull --continue | --abort ``` Fetch new commits on your branch, then merge the latest `main` into it. `--branch-only` skips the merge; `-f` discards local commits the server doesn't have. ### oak fetch ```text oak fetch [-r URL] ``` Refresh your copy of `main` without touching your branch or files. ### oak sparse ```text oak sparse [--json] oak sparse set oak sparse add oak sparse disable ``` Show or change a [sparse checkout's](/docs/sparse-clones) cone. ## History and inspection ### oak log ```text oak log [PATHS...] [-n N] [--oneline] [--verbose] [-S TERM | -G REGEX] [--json] oak log --remote --json [--branch NAME] [--from HASH] [-n N] ``` Show history — full-screen on a terminal. `-S` finds commits that add or remove a string, `-G` commits with a changed line matching a regex. `--remote` reads a branch's history from the server without fetching it. ### oak hash / rev-parse ```text oak hash oak rev-parse [--short] HEAD ``` Print the current commit. `rev-parse` exists for Git-compatible scripts and supports only `HEAD`. ### oak info ```text oak info [--json] ``` Repository, branch, parent, remote, and link details. ### oak file inspect / tree inspect / refs inspect ```text oak file inspect --at [--remote] [--output FILE] [--max-bytes N] [--json] oak tree inspect --at [--max-files N] [--max-bytes N] [--json] oak refs inspect [--max-branches N] [--json] ``` Read a file or tree at a commit, or list local branch heads, without changing anything. See [History and inspection](/docs/history#inspect-files-and-trees-at-a-commit). ### oak open ```text oak open [--print | --json] ``` Open the repo on oak.space, or just print its URL. ## Reviewing ### oak branch triage ```text oak branch triage [--remote] [--only mergeable|closable|ambiguous] [--against BRANCH] [--status STATUS] [--analysis-depth DEPTH] [--limit N] [--json] ``` Score many branches at once — mergeability, contribution, CI, recommended action — without switching. ### oak branch review ```text oak branch review [--remote] [--merge-preview] [--json] ``` Evidence for one branch: what changed, and with `--merge-preview`, whether and how safely it would merge. ### oak branch diff ```text oak branch diff [PATHS...] [--remote] [--against BRANCH] [--diff-mode tree|contribution|net-merge] [--print] [--json [--hunks]] ``` A branch's diff without checking it out. Default mode is `tree`. ### oak branch train ```text oak branch train [--remote] [--against BRANCH] [--json] ``` Preview merging up to 32 branches in order, without publishing. ## CI ### oak ci status ```text oak ci status [--run ID [--commit HASH]] [--json] ``` The merge gate's verdict for the current branch head, or one run. Exit `0` passed, `1` failed or no runs, `3` still running. ### oak ci runs ```text oak ci runs [--limit N] [--json] ``` Recent runs: id, workflow, branch, commit, status, duration. ### oak ci logs ```text oak ci logs [--failed] [--summary] [--max-bytes N] [--json] ``` A run's step output. `--failed` shows only failed steps; `--summary` shows step metadata without logs. ### oak ci wait ```text oak ci wait | --current [--timeout SECONDS] [--progress] [--json [--summary]] ``` Block until runs finish. `--current` waits for the current head's runs (waiting up to `--dispatch-timeout` for them to start). Default timeout 30 minutes. ### oak ci trigger ```text oak ci trigger --expected-commit --idempotency-key [--workflow NAME] [--branch NAME] [--json] ``` Start a run by hand — only if the branch head is still `HASH`. Re-using the key returns the original run. Name the workflow, or every workflow runs. ### oak ci rerun / cancel ```text oak ci rerun [--json] oak ci cancel --commit [--json] oak ci cancel --superseded [--yes] [--json] ``` Re-run a run at the same commit (for infrastructure failures), or cancel a push or merge run. `--superseded` lists — or with `--yes`, cancels — the branch's in-flight runs for commits that are no longer its head. ## Mounts and spaces ### oak mount ```text oak mount [DEST] [-b BRANCH] [-r URL] oak mount list [--json] oak mount finish [DEST] --desc-file FILE [--json] oak mount end [DEST] [-f] oak mount forget [DEST] [-f] [--orphaned] ``` Mount a repo without cloning it (default destination `./`), optionally continuing an existing branch. `end` with no `DEST` ends every mount under `~/oaktree`; `-f` discards uncommitted changes. `forget` cleans up stale registrations. See [Lazy mounts](/docs/mounts). ### oak space ```text oak space new [DEST] oak space repos [ORG] [--json] oak space clean [DEST] [-f] oak space inventory [ROOT] [--verify-local] [--include-ci] [--max-depth N] [--json] ``` Scaffold and manage an [agent space](/docs/spaces). ## Sites ```text oak site enable [--repo ORG/REPO] [--source PATH] oak site show [--organization ORG] oak site list oak site disable [--organization ORG] ``` Publish a repo as the organization's [static site](/docs/sites). In this group `-r` means `--repo`; the server is `--remote`. ## Tools ### oak export ```text oak export [-b BRANCH] [--git-branch NAME] [-f] oak export --tree-only --at ``` Replay a branch's history into a new Git repo, or write one commit's files. See [Export back to Git](/docs/git#export-back-to-git). ### oak archive ```text oak archive [-o PATH] ``` Zip the working tree (default `.zip`). ### oak feedback ```text oak feedback [-m TEXT | --file FILE] [--title TITLE] [--email EMAIL] [--json] ``` Send a bug report or feature request; prints a tracking reference (`fb-N`). Opens your editor on a terminal when no text is given. Alias: `oak feature-request`. ### oak environment ```text oak environment [--json] ``` List every environment variable Oak reads and its effective value (secrets shown as set/unset only). Alias: `oak env`. ### oak maintenance compact Compact the local repository database and reclaim disk space. ### oak doctor ```text oak doctor --repo ORG/REPO [--verify metadata|existence|bytes] [--depth N] [--json] ``` Check a remote repository's content end to end, from commits down to stored bytes. Exit `0` verified, `6` a problem was found, `8` inconclusive. ### oak serve ```text oak serve [-d DIR] [-p PORT] [--host HOST] [--token TOKEN] ``` Run a minimal self-hosted Oak server backed by SQLite (default `./oak-data` on `127.0.0.1:8080`) that speaks the push / pull / clone protocol. No organizations or accounts; binding to anything but loopback requires `--token` (or `OAK_SERVE_TOKEN`). For local development and trusted networks.