Every public oak command, grouped by what it's for. Run oak <command> --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 <URL> (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.
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#
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#
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.
| Flag | Effect |
|---|---|
--branch <NAME> | Switch to this remote branch after cloning. |
--expected-head <HASH> | With --branch: fail unless the branch is open at exactly this commit. |
--shallow | Only the latest commit on main. |
--path <PREFIX> | Sparse clone: only these paths. Repeatable or comma-separated. |
--detached | Check out main's head with no personal branch. |
--from <CHECKOUT> | 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 <URL> | Server to clone from. |
oak login / logout / whoami#
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.
oak auth status#
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#
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#
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.
oak upgrade#
oak upgrade [-f] [--canary]
Upgrade to the latest signed release. -f skips the confirmation; --canary follows the pre-release channel.
oak completions#
oak completions <bash | zsh | fish | elvish | powershell>
Print a shell-completion script.
Working tree#
oak status#
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#
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 <BRANCH> | Base for a branch endpoint (default: its parent). |
--mode <contribution | tree | net-merge> | Perspective for branch endpoints. See Reviewing. |
--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 <N> | 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 <N> to cap it, --changed-files-limit / --changed-files-offset to page. |
--remote <OLD> <NEW> | Diff two exact commits on the server, with --json or --print. |
oak commit#
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.
oak restore#
oak restore [PATHS...] [-s COMMIT] [-f]
Restore files (or everything) to the last checkpoint, or to COMMIT. Asks first unless -f.
oak reset#
oak reset [PATH] [-f]
Discard uncommitted changes — everything, or under PATH. Asks first unless -f.
oak change#
oak change capture [PATHS...] [--json]
oak change export <CAPTURE_ID> --output <FILE> [--json]
Store uncommitted changes as an immutable capture without committing or touching the working tree; export one as a zip. See History.
Branches#
oak switch#
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#
oak checkout <COMMIT>
Detach HEAD at a commit (full hash or a unique prefix of 4+ characters).
oak desc#
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.
oak branch#
oak branch [--show-current] [--json]
oak branch list [--remote] [--status open|closed] [--json]
oak branch show <NAME> [--remote] [--json]
oak branch rename <OLD> <NEW>
List branches, print the current one, or show one branch's details. --remote reads the server. rename is temporarily disabled.
oak close#
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#
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#
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.
Merging and conflicts#
oak merge#
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#
oak conflict status [--json]
oak conflict show [--json]
oak conflict take <PATH> (--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.
oak agent#
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#
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#
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#
oak fetch [-r URL]
Refresh your copy of main without touching your branch or files.
oak sparse#
oak sparse [--json]
oak sparse set <PREFIX...>
oak sparse add <PREFIX...>
oak sparse disable
Show or change a sparse checkout's cone.
History and inspection#
oak log#
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#
oak hash
oak rev-parse [--short] HEAD
Print the current commit. rev-parse exists for Git-compatible scripts and supports only HEAD.
oak info#
oak info [--json]
Repository, branch, parent, remote, and link details.
oak file inspect / tree inspect / refs inspect#
oak file inspect <PATH> --at <HEAD|HASH> [--remote] [--output FILE] [--max-bytes N] [--json]
oak tree inspect --at <HEAD|HASH> [--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.
oak open#
oak open [--print | --json]
Open the repo on oak.space, or just print its URL.
Reviewing#
oak branch triage#
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#
oak branch review <NAME> [--remote] [--merge-preview] [--json]
Evidence for one branch: what changed, and with --merge-preview, whether and how safely it would merge.
oak branch diff#
oak branch diff <NAME> [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#
oak branch train <NAME...> [--remote] [--against BRANCH] [--json]
Preview merging up to 32 branches in order, without publishing.
CI#
oak ci status#
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#
oak ci runs [--limit N] [--json]
Recent runs: id, workflow, branch, commit, status, duration.
oak ci logs#
oak ci logs <RUN_ID> [--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#
oak ci wait <RUN_ID...> | --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#
oak ci trigger --expected-commit <HASH> --idempotency-key <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#
oak ci rerun <RUN_ID> [--json]
oak ci cancel <RUN_ID> --commit <HASH> [--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#
oak mount <ORG/REPO> [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 ./<repo>), 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.
oak space#
oak space new <ORG> [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.
Sites#
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. In this group -r means --repo; the server is --remote.
Tools#
oak export#
oak export <DEST> [-b BRANCH] [--git-branch NAME] [-f]
oak export <DEST> --tree-only --at <HEAD|HASH>
Replay a branch's history into a new Git repo, or write one commit's files. See Export back to Git.
oak archive#
oak archive [-o PATH]
Zip the working tree (default <directory>.zip).
oak feedback#
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#
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#
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#
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.