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.
This page follows CLI version 0.113.0. Check oak --version, and oak <command> --help for the build you have. Commands for Oak staff and for recovery (oak doctor blob, oak feedback list|show|transition, oak agent publication) are listed under Staff and recovery commands.
Global options#
| Option | Effect |
|---|---|
--timings | Print per-phase timings to stderr. Goes before the command: oak --timings push. Same as OAK_TIMINGS=1. |
-h, --help | Help for any command or subcommand. |
--version | Print the CLI version. |
Commands that talk to a server take --server <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. |
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] [--json] [--import-git | --no-import-git]
Create a repository in PATH (default: the current directory) and put you on a personal branch parented onto main. --json prints one receipt and never prompts. On a terminal it offers to import an existing .git history and to write an AGENTS.md for coding agents. Without a terminal, a directory with a .git needs --import-git (bring the history over, see Git import) or --no-import-git (start empty beside it). 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 newest commit on the selected branch (main by default). |
--path <PREFIX> | Only these directories. Repeatable or comma-separated. The other directories aren't in the tree at all. Without it, a repo of 100,000 files or more gets only its top-level files; --path / takes everything. See Sparse clones. |
--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). |
--allow-legacy-scope | Permit a scoped clone on an older server that lacks the bounded integrity proof. Pull may honor the requested scope and still verifies hashes; this waives only the proof before download. |
--server <URL> | Server to clone from. |
oak login / logout / whoami#
oak login [-r URL]
oak logout [-r URL]
oak whoami [-r URL] [--json]
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 ~/.config/oak/credentials. whoami prints the signed-in username; with OAK_API_KEY set it asks the server whose key it is. 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#
oak skill install [--global] [--json]
oak skill status [--json]
oak skill show [FILE]
oak skill install writes the bundled oak-vcs agent skill into ./.claude/skills/ (or ~/.claude/skills/ with --global). oak skill status reports each installed copy as current, stale or missing against this CLI and names the install command that refreshes a stale one. oak skill show prints SKILL.md, or a reference file such as commands.md, to stdout. See Working with agents.
oak upgrade#
oak upgrade [-f|-y]
Upgrade to the latest signed release. There is one release line, released daily. -f (or -y, --yes) skips the confirmation.
oak completions#
oak completions <bash | zsh | fish | elvish | powershell>
oak completions --install [bash | zsh | fish]
Print a shell-completion script. --install writes it to the shell's completions directory instead (the shell comes from $SHELL if not named) and prints any startup-file line the shell still needs. See Shell completion.
Working tree#
oak status#
oak status [--json [--compact] [--fingerprint]] [--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. --json --fingerprint adds the same read-only working-tree fingerprint that oak diff --fingerprint reports.
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. |
--line-numbers | With --json --hunks, each file's hunks carry old_line / new_line per line. With --print, hunk lines are prefixed with their line numbers; that output is for reading, not for apply. Also on oak branch diff. |
--fingerprint | With the working-tree --json document, add a fingerprint object (change_id, base_commit, base_tree, result_tree, changed_file_count). The change_id is the id oak change capture would record for the same tree and paths. Computing it writes nothing and needs no linked remote. |
--verify-fingerprint <ID> | Recompute the fingerprint (optionally for just the paths given) and exit 1 unless its change_id equals ID. Writes nothing. Use it to confirm the tree you are about to commit is the tree you reviewed. |
--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 (or -y, --yes).
oak reset#
oak reset [PATH] [-f]
Discard uncommitted changes — everything, or under PATH. Asks first unless -f (or -y, --yes).
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 start#
oak start SUMMARY [--name NAME] [--no-push] [--clean] [--worktree [DIR]] [--json]
Begin a task: create a branch from main's head, named after SUMMARY (with oak switch -c semantics, so uncommitted files are carried over), set its description to SUMMARY, and push it. A push failure keeps the branch, and the receipt says what to retry. See Working with agents.
| Flag | Effect |
|---|---|
--name <NAME> | Branch name to use instead of the slugified summary. |
--no-push | Don't push the new branch. Also skipped when the checkout isn't linked to a remote yet. |
--clean | Start from the latest main and discard working-tree changes. |
--worktree [DIR] | Start the task in a new worktree at DIR (default: beside this checkout, named after the branch) and leave this checkout alone. The receipt's worktree names the folder. |
--json | Print a machine-readable receipt. |
oak worktree#
oak worktree add DIR [--branch NAME] [--json]
oak worktree list [--json]
oak worktree remove DIR [--force] [--json]
oak worktree prune [--json]
A worktree is a second checkout of the repository, on its own branch, made from the one you're in. Use one per parallel task. add copies this checkout's local store (copy-on-write on APFS, btrfs and XFS) and creates a branch named after DIR's folder from the latest main; --branch names the branch instead, and checks it out if it exists. After that the worktree is an ordinary checkout: commit, push and oak finish there as anywhere.
A branch can be checked out in only one worktree: add --branch and oak switch refuse one another worktree has, and say where. list shows this repository's checkouts and their branches. remove deletes a worktree folder, refusing while it has uncommitted changes or commits the server doesn't have unless you pass --force. prune forgets worktrees whose folder you deleted yourself. Worktrees are recorded in ~/.config/oak/worktrees.json.
oak switch#
oak switch [NAME] [-c] [--clean] [-d] [--json]
Switch to a branch (fetching it if needed). With no name, pick from a list; that picker can't run unattended, so pass a name (or -c) in scripts and with --json.
| 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 (full hash or a unique prefix of 4+ characters) and detach HEAD there. |
--json | One receipt: the branch and head now checked out, and the ones before. |
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|all] [--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 and prints JSON; oak branch list --remote lists open branches unless you pass --status closed or --status all. rename is temporarily disabled. To close a branch, use oak close. Other oak branch subcommands: triage, review and diff.
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. --reason records why in the audit log.
To close a fleet of remote branches only if they haven't moved, pin each one to the head you reviewed:
oak close --remote --json --reason superseded \
feature-a@FULL_64_CHAR_HEAD feature-b@FULL_64_CHAR_HEAD
The pin is a check, not a lock. The CLI reads each branch's remote head and refuses to close one that differs from its pin, but the server's close has no expected-head condition. A push that lands between that read and the close is not prevented; the CLI re-checks afterwards and reports closed_after_head_moved (exit 5), or fence_verified: "unchecked" (exit 6) if it couldn't re-check. Exit 0 means every branch was confirmed closed at its pin. Branches are closed independently, so some may succeed while others fail. Each branch's row says closed, already_closed, refused_head_moved (nothing was sent), closed_after_head_moved, unknown_outcome and so on. After any non-zero exit, read the final open-branch list (oak branch list --remote --json) before doing anything else, and don't retry an unknown_outcome blindly.
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]
Check that the branch can publish, then set the description, checkpoint, and push. If the check (the preflight) refuses, finish changes nothing.
The JSON names the phase that completed. A step that was clearly rejected may name a next command. A publication whose outcome is unconfirmed (the request may have landed but the reply was lost) names no retry command: it points at read-only checks instead. Run those, don't push again until you know. See Working with agents and Unconfirmed publications.
Merging and conflicts#
oak merge#
oak merge [BRANCH] [--force] [--dry-run [--offline]] [--json]
oak merge --continue | --abort
Squash-merge a branch (default: the current one) onto main and close it. The branch description becomes the commit message. See Merging and conflicts.
| Flag | Effect |
|---|---|
--dry-run | With --json: predict the merge and change nothing. The prediction is certified against the server's current main; exit 7 means it couldn't be certified. |
--offline | With --dry-run: make no network request. The prediction uses your local main and is reported uncertified (exit 7). |
--force | Sends the merge API's ?force=1 override: merge past a required approval, where the repository's approval policy allows it (org admins only). |
--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 or 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] [--publication-after OPERATION_ID]
One JSON document with the repository's state and recommended_next_commands. --refresh checks the server first, and also re-observes any interrupted publications it lists. --publication-after OPERATION_ID continues the bounded page of interrupted-publication records after that operation.
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; before a first push, add --repo ORG/REPO to name the destination (nothing is linked or created).
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 list [--json]
oak sparse [--json]
oak sparse set <PREFIX...>
oak sparse add <PREFIX...>
oak sparse disable
oak sparse remove <PREFIX...>
Show or change a sparse checkout's cone, or the directories a --path view holds.
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#
oak hash
Print the full hash of the current commit, bare, for scripts. Repository, branch, parent and remote details are in oak status --json.
oak open#
oak open [--page NAME] [--print | --json]
Open the repo on oak.space, or just print its URL. --page NAME opens that Oak Pages site (https://NAME.oak.page/) instead.
Reviewing#
oak owners / oak access / oak approve#
oak owners PATH [--json]
oak owners --branch [--json]
oak access [--json]
oak approve [BRANCH] [--path DIR] [--head HASH] [--json]
oak owners PATH shows the boundary that owns a path: its owner group, approval setting, readers and writers. oak owners --branch shows what the current branch touches and which approvals it still needs. oak access lists the repo's boundaries you can see. oak approve approves every touched boundary you may approve, or one with --path; --head HASH is the head you reviewed, and a branch that has moved since is refused. It needs an API key with the Review scope.
oak retention#
oak retention list [--repo OWNER/NAME] [-r URL] [--json]
oak retention [--repo OWNER/NAME] [--json]
oak retention set DIR --keep N [--json]
oak retention remove DIR [--json]
Lists or changes the repo's retention rules: keep only the newest N versions of each file under a directory. Changing a rule needs an organization owner or admin.
oak groups / oak group#
oak groups [--org ORG] [--json]
oak group list [--org ORG] [--json]
oak group show GROUP
oak group create GROUP [--parent GROUP] [--description TEXT]
oak group add GROUP USER [--maintainer]
oak group remove GROUP USER
oak group invite GROUP USER [--maintainer]
oak group grant GROUP REPO [--role read|write]
oak group revoke GROUP REPO
oak group agent list
oak group agent add GROUP AGENT
oak group agent remove GROUP AGENT
oak group switch [GROUP] [--clear]
oak groups lists the groups you're in, across your organizations, and marks the one this checkout works as. oak group manages your organization's groups: sub-groups, members and maintainers. invite also adds the person to the organization when they aren't in it yet. grant and revoke give a group access to a repo or take it away; oak group grant public REPO makes a repo public. switch makes this checkout work as a group, seeing and changing exactly what it can, until switch --clear. oak team is the old name and still works.
oak group agent puts an organization's agents on groups. An agent reaches what its groups reach, never its creator's access. list (organization owners and admins) shows each agent and its groups; add takes a maintainer of the group or an owner or admin, and the built-in groups (public, members) don't take agents; remove takes an agent off a group. Every oak group subcommand takes --org ORG (default: this checkout's), --server URL and --json. oak group add members USER adds someone to the organization itself, and oak group remove members USER removes them from it and every group.
oak repo visibility#
oak repo visibility [public | private] [--repo OWNER/NAME] [--json] [-r URL]
With no argument, print whether the repository is public or private (this checkout's, unless --repo). With public or private, change it; only owners and admins of the repository's organization can. oak group grant public REPO and oak group revoke public REPO do the same through the group commands.
oak repo move / adopt#
oak repo move ORG/SOURCE --into ORG/TARGET:PATH --owner-group GROUP [--dry-run] [--no-wait]
oak repo adopt
Move a repo into a directory of another repo, with its history. With the default force policy the move has to be started from the web; --dry-run shows the plan, and --no-wait starts the move and returns without following it. oak repo adopt, run in a checkout of a moved repo, carries its work to a new checkout of the target.
oak branch triage#
oak branch triage [--remote] [--only mergeable|closable|ambiguous] [--against BRANCH]
[--status STATUS] [--analysis-depth DEPTH] [--limit N] [--json]
Score the open branches at once — mergeability, contribution, recommended action — without switching. Output is JSON. --status closed or --status all covers other branches.
oak branch review#
oak branch review <NAME> [--merge-preview] [--changed-files-limit N] [--changed-files-offset N] [--json]
Evidence for one branch: what changed, and with --merge-preview, whether and how safely it would merge.
oak branch wait#
oak branch wait [NAME] [--timeout SECONDS] [--on-main-move] [--json]
Wait on a pushed branch (default: the current one) until it is merged or closed, or until main moves and the branch no longer merges cleanly. Then it prints one result: merged, closed, conflicts (exit 5, with the conflicting files and the commands that fix it), or unpublished when the checkout has commits the server doesn't. A clean move of main needs nothing, so it keeps waiting; --on-main-move returns then too (main_moved), and --timeout gives up after a while (timeout). See Keeping a branch mergeable.
oak branch diff#
oak branch diff <NAME> [PATHS...] [--against BRANCH]
[--diff-mode tree|contribution|net-merge] [--json [--hunks]]
[--line-numbers] [--max-bytes N] [-U N] [-a] [--changed-files-limit N] [--changed-files-offset N]
A branch's diff without checking it out. Default mode is tree. --max-bytes is a byte budget across all --hunks patches, -U/--unified N sets context lines, -a/--text treats oversized text files as text, and --changed-files-limit / --changed-files-offset page the changed-file summaries. --line-numbers works as in oak diff.
Roots#
oak root#
oak root list [--archived] [--json]
oak root show ROOT [--json]
oak root create NAME [--from main|HASH] [--owner-group GROUP] [--sync] [--json]
oak root archive ROOT --yes [--json]
oak root pull [ROOT] [--dir PATH] [--force] [--json]
oak root push [ROOT] [--dir PATH] [--json]
Separate timelines inside one repository, such as a release line that takes patches apart from main. Every subcommand takes --repo OWNER/NAME and --server URL. See Roots for the workflow, permissions and exit codes (pull and push exit 5 when the root and your copy disagree).
Marks#
oak mark#
oak mark list [--changed] [--json]
oak mark show MARK [--json]
oak mark create NAME [--commit main|HASH] [--owner-group GROUP] [--root ROOT] [--allow-group-rollback] [--follower AGENT] [--path PATH,...] [--description TEXT] [--json]
oak mark paths MARK PATH... | --clear [--json]
oak mark move MARK COMMIT [--note TEXT] [--json]
oak mark rollback MARK COMMIT [--note TEXT] [--json]
oak mark pause MARK [--note TEXT] [--json]
oak mark resume MARK [--json]
oak mark log MARK [-n N] [--json]
oak mark delete MARK --yes [--json]
oak mark follow MARK [--check SCRIPT] [--run SCRIPT] [--dir DIR] [--state-file FILE] [--once] [--no-checkout] [--no-grant] [--report-name NAME] [--json] [-- ARGS...]
oak mark follow --match PATTERN [--check SCRIPT] [--run SCRIPT] [--jobs N] [--dir DIR] [--state-file FILE] [--once] [--no-checkout] [--no-grant] [--json] [-- ARGS...]
Named pointers to commits on main, one per thing you deploy or release. A mark names the folders it is about (--path, or oak mark paths later). follow --check runs the check whenever main changes those folders and moves the mark when it passes; follow --run deploys each move. pause stops change events and resume starts them again; list --changed shows the marks whose folders hold something new at main's head. Every subcommand takes --repo OWNER/NAME and --server URL. See Marks for the rules (forward only, rollbacks) and the variables follow gives its scripts.
oak report#
oak report COMMIT --name NAME (--body TEXT | --body-file FILE) [--url URL] [--move-id ID] [--json]
oak report COMMIT [--name NAME] [--json]
File a report on a commit, or, without a body, list the commit's reports (with --name, show that one in full). A report is free text under a name; its first line is the headline History shows, and the next one under the same name replaces it. --body-file - reads stdin. Takes --repo OWNER/NAME and --server URL. oak mark report is an older name for filing one. See Reports.
Reading a remote repository#
oak ls / cat#
oak ls --remote [PATH] [--rev BRANCH_OR_HASH] [--max-entries N] [--json]
oak cat --remote PATH [--rev BRANCH_OR_HASH] [--max-bytes N] [--json]
List a directory or print a file on the server without cloning or changing your checkout. --remote is required. Results are limited to what you can read. cat is hash-verified; ls is not. See Reading a repository without a clone.
Pages#
oak page#
oak page list [--org ORG]
oak page create NAME [--dir PATH] [--spa]
oak page show NAME
oak page rename NAME NEW
oak page set NAME [--dir PATH] [--spa|--no-spa] [--password-user USER --password-file FILE | --no-password]
oak page rm NAME [--yes]
oak page deploys NAME
oak page redeploy NAME
oak page rollback NAME [--to ID]
oak page check NAME
oak page domain list SITE
oak page domain add SITE DOMAIN
oak page domain verify SITE DOMAIN
oak page domain primary SITE DOMAIN [--off]
oak page domain rm SITE DOMAIN [--yes]
oak open --page NAME
Publish folders of the current repo as static websites at https://NAME.oak.page/. oak page domain serves a site on your own domain: add prints the DNS records to create, verify checks the TXT record and starts serving there (exit 1 if the record isn't found yet), primary makes a verified domain the main address so the others redirect to it (--off stops that), and rm removes it. See Pages. Every subcommand takes --repo OWNER/NAME, --server URL and --json.
Tools#
oak export#
oak export <DEST> [-b BRANCH] [--git-branch NAME] [-f]
oak export <DEST> --tree-only --at <HEAD|HASH> [--max-files N] [--max-bytes N]
Replay a branch's history into a new Git repo, or write one commit's files. See Export back to Git.
oak import#
oak import <PATH> --repo ORG/REPO [-r REMOTE] [--scratch DIR] [--window-commits N] [--window-mb N] [--dry-run] [--json]
Publish a Git repository's history to a new repository on the server, one window at a time, with no local Oak copy. Run it again to resume. --dry-run converts everything and reports what would be sent, and how long each phase took, without contacting the server. See Import a large repository.
oak feedback#
oak feedback [-m TEXT | --file FILE] [--title TITLE] [--name NAME] [--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 doctor#
oak doctor --repo ORG/REPO [--verify metadata|existence|bytes] [--depth N] [--max-chunks N] [--max-bytes N] [--json]
oak doctor file <PATH> --at <HEAD|HASH> [--remote] [--output FILE] [--max-bytes N] [--json]
oak doctor tree --at <HEAD|HASH> [--max-files N] [--max-bytes N] [--json]
oak doctor refs [--max-branches N] [--json]
oak doctor compact
With --repo, check a remote repository's content end to end, from commits down to stored bytes. --max-chunks and --max-bytes bound how many chunk objects and object bytes one request verifies. Exit 0 verified, 6 a problem was found, 8 inconclusive.
The subcommands check one thing each, without changing anything except compact:
oak doctor fileverifies one file's bytes at a commit.--remotereads it from the server without a clone;--outputalso writes the verified bytes to a new file.oak doctor treelists a commit's paths, sizes and hashes, bounded by--max-filesand--max-bytes.oak doctor refsreads every local branch head from one snapshot and flags disagreements;--max-branchesbounds the list.oak doctor compactrewrites a local database made by an older CLI in the current storage format and reclaims disk space.
See History and inspection. oak doctor blob is under Staff and recovery commands.
Staff and recovery commands#
These are listed so that the reference is complete; most people never need them.
oak doctor blob#
oak doctor blob HASH --repo ORG/REPO [--depth N [--branch NAME]] [--json]
Privileged: prove one blob's metadata, chunk mapping, stored objects and affected paths. It needs administrator access to the server; --depth bounds how many of a branch's newest commits it inspects.
oak feedback list / show / transition / link / unlink#
oak feedback list [--status STATUS] [--limit N] [--cursor CURSOR] [--json]
oak feedback show ITEM [--json]
oak feedback transition ITEM --expected-revision TOKEN [--status STATUS] [--notes TEXT | --clear-notes] [--json]
oak feedback link ITEM [--branch NAME | --commit HASH] [--repo ORG/REPO] [--json]
oak feedback unlink ITEM [--link-id ID | --branch NAME | --commit HASH] [--repo ORG/REPO] [--json]
list, show and transition are platform-admin views of the feedback queue (list is bounded and omits reporter details). transition edits one ticket only if it is still at the revision you observed (--expected-revision, taken from a fresh show or list), needs server support (feedback_transition_v1), and never retries: a conflict or an unconfirmed outcome means re-read and reconcile. link and unlink (also admin-only) connect a feedback item to the branch (default: the current one) or commit that addresses it; unlink never guesses between several matches and prints the --link-id that resolves it.
oak agent publication forget#
oak agent publication forget OPERATION_ID --acknowledge-unknown --json
Delete one local record of an interrupted publication, without contacting the server, after you accept that its outcome stays unknown. Both --acknowledge-unknown and --json are required. The record stays until you do this; a read-only check of the server never removes it. It refuses a record owned by a running process. Reconcile first: see Unconfirmed publications.