Reference
CLI reference
oceancode is one binary: oceancode [subcommand] [flags] [args]. With no subcommand it starts Ocean
TUI. acp runs it as an editor agent, and serve, run, goal and workflow run it headless.
01 · Getting started explains the three boot shapes. This page lists every
subcommand, its flags and its exit codes.
Flag syntax
Most engine commands parse flags with a port of Go's flag package: the default shape, serve, acp,
migrate, run, workflow, goal, ledger, export, login, logout, key, auth and
slack connect. Go's rules apply:
-nameand--nameare the same flag. A value is written--name valueor--name=value. Single-letter flags cannot be bundled:-vcis one flag namedvc.- Parsing stops at the first argument that is not a flag, or at a bare
--, which is dropped. Everything after that point is positional, even if it looks like a flag. - A boolean flag never takes the next argument; turn one off with
--name=false. Integer flags accept Go's base prefixes (0x1000,0o10000,0b…) and_separators. -h/--helpprintsUsage of <name>:and the flag list to stderr, then exits 0. An unknown flag, a missing value or a bad value prints the error and the usage to stderr, then exits 2.
The capability and maintenance commands (plugin, mcp, skill, trust, hooks, jev, inspect,
doctor, update, verify-release, uninstall, claude) parse their arguments by hand. Write their
flags with two dashes, exactly as shown. Most of them reject --help with a usage error (exit 1).
update ignores --help and runs a real update, so never try oceancode update --help.
Global flags
--version must be the first argument. --data-dir and --fake-llm-sse are removed from the whole
command line before the subcommand is chosen, so a run prompt that contains the words --data-dir x
loses them.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--version | — | — | Print oceancode <version> (<build stamp>) and exit 0. Needs no database, config or terminal. -v is not an alias: it means --verbose. |
--data-dir <dir> | string | the app data dir | Where auth.json and the other per-install state live, for commands that boot the engine. Also --data-dir=<dir>. |
--fake-llm-sse <file> | string, repeatable | none | Test hook: replay a recorded provider SSE body for each turn, in order, repeating the last one. Also --fake-llm-sse=<file>. |
OC_DETERMINISTIC=1 is read at the same point: it pins the clock and seed that ids are minted from, so
two runs produce identical id sequences. Every invocation except --version checks for orphaned sessions
left by a crashed run. When it finds any, it prints one line to stderr: note: <n> orphaned session(s) from a previous run — run `oceancode doctor` for details.
Common engine flags
--db, --directory and --verbose are not global; each command declares them. They mean the same
thing everywhere, so the per-command tables below omit them.
| Flag | Type | Default | Meaning | Taken by |
|---|---|---|---|---|
--db | string | oceancode.db | Path to the session database. | the default shape, run, serve, acp, workflow run/pause/resume/stop, goal, ledger, export, migrate |
--directory | string | current directory | Working directory. For workflow runs it is the project to filter by. | the same, minus migrate, plus workflow runs |
--verbose, -v | bool | off | Trace every outbound LLM provider request/response to stderr, with credentials masked. | the default shape, run, serve, acp, workflow run and its control verbs, goal |
Exit codes
| Code | Meaning | Where |
|---|---|---|
| 0 | Success, or -h/--help on a Go-flag command. | all |
| 1 | The command failed. The message is printed to stderr as error: <message>. | all |
| 2 | Flag parse error (unknown flag, missing or bad value). | Go-flag commands |
oceancode run exits with a typed code once its turn has started. A failure before that (boot, flag
validation, an empty message) is exit 1. A turn that ends while background sub-agents or a workflow it started
still work does not end the run: run waits for them and for the turns their results start, and exits on the
last. A workflow that pauses is not waited for; resume it later.
| Code | Meaning | Stop reason(s) |
|---|---|---|
| 0 | finished | finished, waiting |
| 2 | permission rejected | permission_rejected |
| 3 | budget | budget |
| 4 | time | time |
| 5 | no progress | no_progress, max_steps, doom_loop |
| 6 | error | error, hook_blocked; also a --json-schema that cannot be satisfied |
| 130 | interrupt | user_interrupt |
oceancode workflow run and oceancode goal exit by the run's final status:
| Code | Status |
|---|---|
| 0 | complete (and a --validate-only check) |
| 2 | failed, cancelled, interrupted, budget_limited, or any unrecognised status |
| 3 | a pause: user_paused, back_off_paused, no_progress_paused, infra_paused, blocked |
Exit 2 from run can be a permission rejection or a flag error; the stderr text tells them apart.
oceancode (no subcommand)
oceancode [--db <path>] [--directory <dir>] [--listen <host:port>] [--tui tui] [-v]Execs Ocean TUI, which runs the engine inside its own process. stdout must be a terminal; otherwise it
fails with stdout is not a terminal — use `oceancode serve` for headless serving. The TUI binary is
looked up in this order: OC_TUI_BIN, then next to oceancode (also next to its target if oceancode
is a symlink), then PATH. Here --verbose becomes the TUI's --debug.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--listen | string | 127.0.0.1:4096 | HTTP bind address handed to the TUI. A non-loopback address needs OC_SERVER_PASSWORD. |
--tui | string | empty | Kept for old scripts: empty or tui is accepted; ocean is refused (the native TUI was removed on 2026-10-05), and any other value is an error (only `tui` exists). Falls back to OC_TUI. |
See 19 · Ocean TUI.
oceancode run
oceancode run [flags] <message…>Runs one non-interactive turn and exits with the typed code above. Flags must come before the
message, because a flag after it is sent to the model as text; a bound flag placed after the message
also prints a warning that the run is not bounded by it. When stdin is not a terminal, run reads it to
EOF and appends it to the message, so close stdin (</dev/null) when the prompt is only an argument. An
empty message fails with you must provide a message.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--agent | string | empty | Agent to use. |
--model, -m | string | empty | Model to use, provider/model. |
--variant | string | empty | Model variant (provider-specific reasoning effort, e.g. high, max). |
--title | string | truncated prompt | Session title. |
--continue, -c | bool | off | Continue the last session. |
--session, -s | string | empty | Session id to continue. |
--resume-title, -r | string | empty | Resume the most recent session whose title matches this text. |
--fork | bool | off | Fork the session before continuing. An error unless --continue or --session is also given. |
--auto | bool | off | Auto-approve permissions that are not explicitly denied (dangerous!). |
--output-format | string | text | stream-json (NDJSON per event), json (one buffered result object), or text. Takes precedence over --format. |
--format | string | default | Deprecated. default = text; json = the stream-json framing. |
--tools | string | all | Restrict the advertised tools to these comma-separated ids. An unknown id is an error. |
--disallowed-tools | string | empty | Remove these comma-separated tool ids from the advertised set. |
--allow | string | empty | Append allow permission rules, e.g. "Bash(git *),Edit(src/**)". |
--deny | string | empty | Append deny permission rules (last match wins, so a --deny beats an overlapping --allow). |
--append-system-prompt | string | empty | Append this text to the run's system context. |
--json-schema | string | empty | Validate the model's final JSON against this JSON Schema (a file path or inline JSON). On a mismatch the model is re-prompted with the validation errors, up to a retry limit. Prints the validated object; exits 6 if the schema cannot be satisfied. |
--max-usd | string | unset | USD bound for this session: a number, off, or subscription (no bound; spend shows the list-price estimate). |
--max-minutes | string | unset | Wall-clock bound: minutes, 90m, 8h, 2d, or off. |
--max-steps | string | unset | Step bound per turn, 1..=1000, or default to clear a stored override. |
--tideline, --shelve | string | unset | The Session Ledger tideline: <pct>% (a share of the model's context), <limit>, or default. --shelve is the older spelling. |
--window | string | — | Removed. Any value fails with --window was renamed: use --tideline. |
--subagent | string | unset | The model this session's sub-agents run, provider/model. |
--atif | string | empty | When the turn ends, write the session's ATIF-v1.8 trajectory (JSON) to this path. |
See 07 · Headless and server and 08 · Bounding a long run.
oceancode serve
oceancode serve [--port <n>] [--host <ip>] [--db <path>] [--directory <dir>] [-v]Starts the engine with its HTTP surface only and no UI. The banner goes to stdout and diagnostics to
stderr. A non-loopback --host without OC_SERVER_PASSWORD is refused before anything boots.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--port | int | 4096 | TCP port to listen on. |
--host | string | 127.0.0.1 | Interface to bind. A non-loopback host requires OC_SERVER_PASSWORD. |
oceancode acp
oceancode acp [--db <path>] [--directory <dir>] [-v]Serves the engine as an Agent Client Protocol agent over stdin/stdout, which is how Xcode and other ACP editors launch it. stdout carries only newline-delimited JSON-RPC; the banner, diagnostics and tracing go to stderr. There is no HTTP surface, and the command returns when the editor closes stdin. It takes only the common engine flags. See 20 · Xcode and other ACP editors.
oceancode workflow
oceancode workflow run <name|path> [--args <json>] [--budget <n>] [--validate-only] [-m <provider/model>]
oceancode workflow runs [--all] [--directory <dir>]
oceancode workflow pause|resume|stop <run_id> [--budget <n>]run starts a host-run Rhai workflow and prints each workflow_updated body to stdout as one JSON line.
The last line is the terminating body, and the command exits with the workflow/goal code above. Put the
name or path first, then the flags. runs lists the persisted runs for the current project, newest
first; it takes no --db or --verbose. pause and stop (run id first) act on a run that is live in
the engine that same command boots. resume also resumes a run on disk (paused, budget-limited, or
interrupted by a killed process), streams it like run and exits with the same codes
(25 · Workflows).
| Flag | Sub-subcommands | Type | Default | Meaning |
|---|---|---|---|---|
--args | run | string | {} | JSON object bound to the workflow's args global. |
--budget | run, control verbs | string | from config | run: absolute bound on cumulative child-agent calls, 1..=1024. resume: a higher call bound that lifts a budget-limited run. |
--validate-only | run | bool | off | Metadata and compile check only; launches no agent. |
--model, -m | run | string | empty | provider/model for steps that name no model. There is no default provider. |
--all | runs | bool | off | List runs from every project. |
oceancode goal
oceancode goal "<objective>" [--budget <n>] [-m <provider/model>] [--db <path>] [--directory <dir>] [-v]Launches the built-in goal workflow (Plan → Work → Verify) and prints each goal_updated body to stdout
as one JSON line. It exits with the workflow/goal code above. The objective must be the first
argument, with the flags after it. A missing objective, or a flag in first place, fails with
missing objective: usage: oceancode goal "<objective>" [--budget <n>] [--model <provider/model>].
| Flag | Type | Default | Meaning |
|---|---|---|---|
--budget | string | from config | Absolute bound on cumulative child-agent calls for the goal, 1..=1024. |
--model, -m | string | empty | Default model for every goal agent that names none. There is no default provider. |
oceancode ledger
oceancode ledger path [--db <path>] [--directory <dir>] <session-id>
oceancode ledger rebuild [--merge] [--yes] [--db <path>] [--directory <dir>] <session-id>path prints the absolute ledger directory of the session. rebuild rebuilds the ledger mechanically and
prints rebuilt <n> turn(s) in <dir>. --merge then prints the number of merge chunks and asks
fold forward with model calls? [y/N] on stderr before folding them forward, which costs model calls.
The session id is read after the flags, so write the flags first; a flag placed after the id is not
applied. With the ledger disabled (ledger.enabled = false), rebuild fails.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--merge | bool | off | rebuild only: fold the merge backlog forward after the rebuild (model calls). |
--yes | bool | off | rebuild only: skip the y/N confirmation for --merge. |
See 06 · Session ledger and export.
oceancode export
oceancode export (--md | --atif) [--out <path>|-] [--db <path>] [--directory <dir>] <session-id>Writes a whole session as one Markdown document or as an ATIF-v1.8 trajectory (JSON). Pass exactly one of
--md or --atif. As with ledger, the session id is read after the flags, so write the flags first.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--md | bool | off | Write the session as one Markdown document. |
--atif | bool | off | Write the session as an ATIF-v1.8 trajectory (JSON). |
--out | string | - | Output path; - writes to stdout. |
See 06 · Session ledger and export.
oceancode login
oceancode login [--provider claude|copilot|codex] [--no-browser]Logs in to a provider and stores the credential in the data dir's auth.json. claude (the default;
also anthropic, claude-pro, claude-max) runs the Claude Pro/Max OAuth flow: it prints the authorize
URL and reads the pasted code from stdin. copilot (github-copilot) and codex (openai) run the
OAuth 2.0 device-code flow and store the credential under github-copilot or openai.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--provider | string | claude | Provider to log in to: claude, copilot or codex. |
--no-browser | bool | off | Print the authorize URL only; do not try to open a browser. |
A --features platform build adds --provider ocean (alias plungeai: the PlungeAI account sign-in, OAuth 2.1
with PKCE at signin.plungeai.com, refresh token in the keychain item plungeai / oceancode), --key (with
--provider ocean: the older dashboard sign-in that stores an ozk_ account key instead) and
--sso-token <token> (stores a gateway SSO session token). See 15 · Platform mode.
oceancode slack
oceancode slack connect [--channel] [<C…|G…>]
oceancode slack status
oceancode slack on
oceancode slack off
oceancode slack disconnectPairs the engine's Slack bridge with one Slack app and one channel. connect reads SLACK_BOT_TOKEN
(xoxb-…) and SLACK_APP_TOKEN (xapp-…) from the environment, else two lines piped on stdin (the bot
token first), else asks for both in the terminal with echo off, so what you paste never shows. Every
value is cleaned first: the terminal's paste markers and every character that is not a letter, digit or
dash (spaces, quotes, a zero-width space) are removed. Only one of the two variables, or a single piped
line, is refused with exit 2. A malformed token or channel id is refused before any network call, with a
line that names the wrong one and what was given instead by its prefix and length (the first token is the app-level token (xapp-), the app-level token must start with xapp-; the second token given (21 characters) does not), never its text. It then calls auth.test (the bot token), conversations.info (a public channel
is refused with exit 2: anyone in the workspace could run prompts on this Mac) and apps.connections.open
(the app-level token and Socket Mode) and posts Ocean Code connected from <hostname> in the channel; only
when all of them succeed does it store the tokens and the channel in auth.json and print
SLACK_CONNECT_OK team=<team> channel=<id>. status prints
team <team> · bot <user id> · channel <id> · slack <on|off> · OC_SLACK <on|off> from an auth.test with the
stored token; it asks no engine. off turns Slack off for every window on this Mac, the open ones within two
seconds, and prints slack: off (the tokens are kept; …); on turns it back on and prints slack: on; both write
the file slack-off beside auth.json (or remove it) and keep the tokens. disconnect removes the stored entry and prints slack: disconnected, also when
nothing was stored. No subcommand prints a token.
| Flag | Sub-subcommands | Type | Default | Meaning |
|---|---|---|---|---|
--channel | connect | string | the stored channel | The channel's id, C… or G…; the id alone after connect means the same. Required on the first connect. |
| Code | Meaning |
|---|---|
| 0 | Connected, the status printed, switched on or off, or disconnected. |
| 1 | status, on or off found nothing stored: slack: not connected (oceancode slack connect --channel <id>). |
| 2 | A usage error, missing or malformed tokens, no channel, a public channel, or Slack or auth.json refused; the message is on stderr. |
See 24 · Slack.
oceancode logout
oceancode logout [anthropic|zai-coding-plan|ocean]Removes one provider's stored credential from auth.json; the default is anthropic. Accepted names:
anthropic/claude, zai-coding-plan/zai/glm/zai-coding/glmcoding, and ocean/plungeai. For
ocean after an account sign-in it first revokes the sign-in at signin.plungeai.com, then deletes the
keychain item and the auth.json entry (a failed revoke removes nothing). If nothing is stored, it prints
No stored <provider> credential. and exits 0. Takes no flags.
oceancode key
oceancode key [<provider>] [<api-key>]Stores an API key in auth.json (type api). The provider defaults to anthropic and takes the same
names as logout. With no key on the command line, the key is read from stdin when stdin or stdout is
not a terminal; in a terminal, a non-Anthropic provider prompts for it. With no key at all, the command
prints the credential status for anthropic and zai-coding-plan. A key without the expected sk-ant-
prefix triggers a warning but is still stored. Takes no flags.
oceancode auth
oceancode authAn interactive picker: 1 Anthropic API key, 2 Claude subscription (runs login), 3 GLM coding plan
(runs key zai-coding-plan). Needs both stdin and stdout to be a terminal and fails otherwise. Takes no
flags.
oceancode claude
oceancode claudeChecks the claude-code provider before you use it. It reports the claude binary's path (or claude.bin
from config), its --version, and whether a Claude Code login is present. Advisory only: it exits 0
whatever it finds. Any argument fails with usage: oceancode claude.
oceancode inspect
oceancode inspect [--json]Prints where every config key, skill, agent, command, MCP server and instruction file comes from, for the
current directory (there are no --dir/--home flags). Each human row is
kind id winning-layer source, and the last line is INSPECT_OK sources=<n>. With --json the JSON
array goes to stdout and the sentinel to stderr. Boots nothing. See
09 · Capabilities and plugins.
oceancode plugin
oceancode plugin [--root <home>] <subcommand>--root (also --root=<home>) overrides the home that the stores live under
(<home>/.oceancode/plugins and <home>/.oceancode/marketplaces).
| Sub-subcommand | Prints |
|---|---|
marketplace add <spec> / update <n> / remove <n> | PLUGIN marketplace-added|marketplace-updated|marketplace-removed <name> |
marketplace list | <name> plugins=<n> per marketplace |
install <name-or-path> [--trust] [--marketplace <m>] | PLUGIN installed <name> <version>, plus PLUGIN trusted <name> with --trust |
list | <name> <version> enabled=<bool> trusted=<bool> per plugin |
uninstall <n> / update <n> | PLUGIN uninstalled <n> / PLUGIN updated <n> <version> |
enable <n> / disable <n> | PLUGIN enabled|disabled <n> |
enable-all / disable-all | PLUGIN enabled-all|disabled-all count=<n> |
trust <n> [--off] | PLUGIN trusted|untrusted <n> |
validate <n> | PLUGIN validated <n> ok=<bool>, then one - <problem> line per problem |
import --from claude-code [--trust] [--no-repo-trust] [--dry-run] [--home <h>] [--dir <d>] | Ends with IMPORT_OK plugins=<n> marketplaces=<m> repo_trust=<bool> (IMPORT_DRY_RUN_OK … under --dry-run). import takes --home/--dir, not --root. |
See 09 · Capabilities and plugins.
oceancode mcp
oceancode mcp [--root <dir> | --dir <dir>] [--home <h>] <subcommand>--root (or its alias --dir) selects the project directory where .mcp.json lives; the default is the
current directory. --home selects the home tier.
| Sub-subcommand | Behaviour |
|---|---|
add <name> --command <cmd> [--arg <a>]… [--env K=V]… | Writes a stdio server to <dir>/.mcp.json under mcpServers.<name>. Prints MCP added <name> stdio. |
add <name> --url <url> [--header K=V]… | Writes a remote (type: http) server. Prints MCP added <name> remote. Pass exactly one of --command or --url. |
remove <name> | Deletes the entry from .mcp.json. Prints MCP removed <name>. |
enable <name> / disable <name> | Clears or sets the server's held-disabled bit in the trust store. Prints MCP_ENABLED/MCP_DISABLED <name>. |
list | One row per discovered server: name stdio|remote tier trusted|untrusted enabled|disabled|shadowed source. |
login <name> / logout <name> | login prints the OAuth callback URL and contacts no network. logout clears the stored OAuth entry. |
doctor | Connects to each server with a 2-second budget and prints one status row per server (connected, needs-auth, failed, disabled, untrusted). |
See 11 · MCP servers.
oceancode skill
oceancode skill [--root <dir>] [--dir <d>] [--home <h>] <subcommand>| Sub-subcommand | Behaviour |
|---|---|
create <name> [--description <text>] | Writes <root>/.oceancode/skills/<name>/SKILL.md (--root defaults to the current directory) and prints SKILL created <path>. Refuses to overwrite an existing skill. |
list [--json] | One row per discovered skill: id tier trusted|untrusted state description. state is enabled or the reason the skill is disabled. |
enable <id> / disable <id> | Flips one skill's user-tier enable bit. <id> is a stable id, or a bare name that matches exactly one skill. Prints SKILL enabled|disabled <id>. |
enable-all / disable-all | Prints SKILL enabled-all / SKILL disabled-all count=<n>. |
See 09 · Capabilities and plugins.
oceancode trust
oceancode trust show | repo on|off | mcp <name> on|off|clear [--dir <d>] [--home <h>]Reads and sets the per-project trust record in <home>/.oceancode/trust.json. show prints
repo=<bool>, then one mcp <name>=<bool> line per override and one disabled <name> line per held
server. Every subcommand ends with TRUST_OK. repo grants or revokes repo-tier execution (repo hooks
and .mcp.json servers). mcp sets a per-server override that takes precedence over repo, or clears
it. See 11 · MCP servers.
oceancode hooks
oceancode hooks [--dir <d>] [--home <h>] list [--json]
oceancode hooks add <Event> --command <cmd> [--matcher <re>] [--timeout <s>] [--scope user|project|local]
oceancode hooks remove <Event> --command <cmd> [--matcher <re>] [--scope user|project|local]list prints every hook source file the boot loader reads: one line per source with its tier, its trust,
whether it is loaded (or held, and why) and its path, followed by its handlers. The output ends with
HOOKS_OK sources=<n> handlers=<m> loaded=<k>. --json prints {"repo_trusted", "sources"} and no
sentinel. add and remove edit Claude Code's settings.json for the chosen scope (default project)
and print HOOK_ADDED <path> or HOOK_REMOVED <path>. Removing a handler that does not exist fails with
hooks remove: no such handler. See 10 · Hooks.
oceancode jev
oceancode jev status [--json]
oceancode jev probe [--record --point <p> --case <id> --request <req.json> --out <fixture.json> [--expect <json>]]
oceancode jev labels [--implicit | --unlabelled [--point <p>]] [--root <ledger dir>] [--out <file>]
oceancode jev questions --json
oceancode jev verdicts --in <cases.jsonl>Inspects the Jev decision layer, read from the current directory and the environment (no --dir/--home
flags). status prints one point mode endpoint-host line for each of the nine decision points —
permission, output_view, supervisor, triage, visibility, check, guidance, snippets,
effort — then JEV_STATUS_OK points=9; --json prints {points, endpoint, thresholds} instead, with
JEV_STATUS_EMITTED points=9 on stderr. On a project with no jev section every point is off:
permission off -
output_view off -
…
effort off -
JEV_STATUS_OK points=9probe makes one live call to Jev and prints JEV_PROBE_OK
or JEV_PROBE_FAIL <why>; probe --record records a fixture. labels exports labelled decisions
(JEV_LABELS_OK added=<n> total=<m>), each row's source telling a person's answer (shadow-user) from
the labels the effort and snippets points write themselves (implicit-effort, implicit-snippets);
--unlabelled requires --out. The tool_tiers and relevance points were retired on 2026-10-21
and no verb lists them. questions --json and
verdicts --in print the decision points' question sets and policy verdicts for the bench. Only probe
calls Jev. See 13 · Jev decisions.
oceancode doctor
oceancode doctor [--storage]Reports orphaned sessions (registry entries whose process died without a clean exit) and captured panic
reports found under the data dir. --storage adds the storage report: the sizes of oceancode.db and its
WAL, the session count, and the ledger directory's size and oldest session age. Read-only; any other
argument is ignored. See 18 · Operations.
oceancode peers
oceancode peers [log [--since <n>m|<n>h|<n>d]] [--data-dir <d>]
oceancode peers card [--since <n>m|<n>h|<n>d] [--data-dir <d>]Lists the Ocean Code sessions running on this machine, read from the session line every engine joins (its record
is <data dir>/line/messaging.db): each session's state (idle, working, blocked), title, directory and pid,
what it is doing, and the files (or name:<label> work) it is writing. peers log prints the history,
oldest first — who claimed, released, was blocked, overrode a claim, expired or changed_under
another session, whose approved plan met another's (overlap), and every write with the lines it changed
(wrote, the lines in parentheses); slots add deployed, deploy_refused, live_ok, live_failed,
overwrote, check_failed, unprotected and slot_lost; lands add landed, land_refused and hold — for the last two hours, or --since (30m, 2h, 7d; the log keeps seven days). Each row starts with its date and time in UTC
(2026-10-29T16:21:03Z).
peers card (0.8.8.107) counts that log on one screen, for the last seven days or --since: sessions, claims,
refusals and how long a refused session waited until it got the file, writes that passed unprotected, deploys,
live checks and holds; then lands, lands applied on top of a branch that had moved, refused lands by reason, and
the time from a refused land to the land that repaired it.
--data-dir reads another data dir's line. The command changes nothing of its own: it joins the line while it
runs, and hosts it when no other engine runs. See 12 · Session peers.
oceancode status
oceancode status [all | <code | words>] [--watch] [--data-dir <d>]Prints the board of every Ocean Code session on this machine, read from the session line, sessions that wait for you first:
Ocean Code sessions · 2 · 1 working, 1 empty
#2oca working AI consulting v3 3/9 4m
now: Task 16: round-2 re-review running
next: Task 16 fix round 2 · 1 helper · holds 2 files · est. ~40m–1.5h (rough) · pid 45683
#f2k1 empty New session 12m
pid 51022Each session has a code, the last four characters of its id (#2oca), and one state: waiting for you (a
permission or a question is open), blocked (another session holds a file it needs), stuck? (working, but its
plan has not moved for 30 minutes), working, idle, empty (a window nobody has typed into yet), done (idle
with every plan row done), crashed or closed. The second line is the plan row in progress (or the running
tool), the third the next row, the sub-agents it runs, the files it holds, a rough estimate (once three rows are
done and the plan has not grown for 15 minutes: the pace so far, ×0.7–×1.5) and the window's pid. An at: line
names the file and the lines the session last read or wrote (at: src/a.rs lines 120-134, relative to its folder). The board lists
every open session, plus closed or crashed ones with open plan rows from the last three days (resume: oceancode resume <code>). all lists every session it knows (cards are kept 14 days); a code (2oca or #2oca, any case)
or words from a title, a plan row or a folder list the matches. --watch reprints the board when the line reports
a change, and every two seconds for its ages.
A session opened by a build before 0.8.8.51 shows without its plan until that window is relaunched. The TUI's
/status and the agent's sessions tool print the same board.
oceancode resume
oceancode resume [<code | words>] [--listen <addr>]Opens any Ocean Code session on this machine, wherever it ran: the board knows each session's store and folder,
so the TUI starts in that folder, on that store, with the session open and its resume card printed
(19 · Ocean TUI). The query is a code (2oca, any case; quote '#2oca', since
bash reads an unquoted # as a comment) or words from a title, a plan row or a folder. The global --data-dir
reads another data dir's board and opens the TUI on it.
- No query prints the board and
Resume one with: oceancode resume <code>. - A session another Ocean Code window has open is not opened twice: the command names that window's pid and exits
- Switch to that window, or close it there first.
- Several matches (two sessions whose ids end in the same four characters, or words that fit several) open nothing: the command prints them and exits 1.
- No match on the board (a session opened by a build without cards) looks in this folder's store, as
ocean-tui --resume <id or title>does.
oceancode workspace
oceancode workspace init ocean-git://<repo>@<ref> [dir] --handle <handle> [--sync]
oceancode workspace status
oceancode workspace land -m <message> [--branch <branch>]
oceancode workspace syncAn Ocean Git workspace is a plain folder that holds only the files the agent fetches from Ocean Git — no
clone, no .git. workspace init resolves <ref> (a branch, tag or commit id; main when there is no
@) to a full commit id and writes <dir>/.oceancode/ocean-git.json ({url, repo, ref, base, handle});
dir defaults to a new folder named after the repo in the current directory, and a folder that is not
empty is refused. It prints WORKSPACE_INIT_OK dir=<dir> repo=<repo> ref=<ref> base=<sha>. The handle is
--handle, else OC_OCEAN_GIT_HANDLE; the token is the macOS keychain item ocean-git/<handle>, else
OC_OCEAN_GIT_TOKEN; the URL is OC_OCEAN_GIT_URL (default https://git.plungeai.com).
oceancode started in that folder (or below it; the TUI, acp and serve alike) reads the base commit
through Ocean Git: read of a file not yet in the folder fetches it first, read of a folder and glob
merge the commit's file list with the folder's own files, grep uses Ocean Git's search and re-searches
the files changed in the folder (until the server has a search route it searches the folder only and
says so), and the extra tool materialize {prefix?, glob?} fetches up to 2,000 files at once so bash
can work on them. Files are kept in ~/.cache/oceancode/og/ ($XDG_CACHE_HOME/oceancode/og), checked
against their blob id. A second extra tool, land {message, branch?}, commits the folder's changes
(below). The system prompt gains one paragraph after the <env> block saying the folder is an Ocean Git
workspace at <repo>@<ref> and its base commit, that read/glob/grep reach the whole repository,
to run materialize before bash needs files, to commit with land, and never to git clone or
git init there. Without the marker no tool and no prompt byte changes.
workspace status (inside a workspace) prints the base commit, then
fetched=<n> modified=<n> new=<n> deleted=<n> and one line per changed path (M, A, D): a fetched
file whose size and modification time are as fetched is unchanged, otherwise it is re-hashed; new is a
file not in the base commit (.oceancode/, target/, node_modules/ and what the folder's
.gitignore ignores are skipped); deleted is a fetched file that is gone.
workspace land -m <message> [--branch <branch>] (inside a workspace) commits those changes as one
Ocean Git commit, built on the server (POST /api/commits): no git, no clone, no push. It is the
land tool's code path without a model. A modified or new file is sent whole (UTF-8 as text, anything
else base64; mode 100755 when executable, 120000 for a symlink, sent as its target), a deleted file
as a delete; a move is a delete plus a new file. --branch defaults to the workspace's ref; it must
be main or a branch of your own, <handle>/<name> (created when missing), and a workspace made from
a branch other than main lands only onto that branch. Refused before anything is sent: no changes,
more than 1,000 changes, a file over 8 MiB, a request over 32 MiB, another handle's branch.
When the branch moved since the base and touched other files, Ocean Git applies the changes on top of it
(rebased=true); when it touched the same files, nothing lands, the conflicting paths and the branch's
head are reported, and nothing in the folder changes (the folder still holds the base's versions of
those files). After a land the marker's base is the new commit and its ref the branch, the landed
files are recorded at their new blob ids, so workspace status shows modified=0 new=0 deleted=0; a
fetched file you had not changed but the branch did between the old base and the new parent is removed
from the folder (and read fetches the new version), while a file you had changed is never removed. It
prints WORKSPACE_LAND_OK commit=<sha> branch=<b> rebased=<bool> files=<n> (and a summary on stderr),
or WORKSPACE_LAND_FAIL <reason> and exits 1. In a repository whose .oceancode/ocean-hub.json says
"guard": true the command sends nothing (0.8.8.108): the folder's copy, or since 0.8.8.110 the repository's
own at the base commit, which a workspace does not fetch; a marker that cannot be read refuses too. Only a
session can show what the guard asks
(12). The land tool asks permission under the key land
with the branch as the pattern (12 · Permissions).
workspace sync (0.8.8.107, inside a workspace) is the way on after such a refused land: it moves the
base to the head of the workspace's branch and looks only at the files the branch changed since the old
base. A fetched file you did not change is fetched again at the head. A file changed on the branch and
in the folder keeps your version, and the report shows what the branch changed in it (up to 10 files, 20
lines each); land refuses until that file has been changed (writing the same bytes again does not count),
so the branch's change is taken in
by hand and never overwritten unseen. A fetched file you deleted that the branch changed is not deleted
unseen either: land refuses until it has been read (which fetches the branch's version) and, if it
should still go, deleted again. Everything else in the folder is untouched. The workspace's state and its
marker are saved before any file is removed; if either cannot be saved, nothing changes and the workspace
stays at its old base (0.8.8.108; in 0.8.8.107 a state that could not be saved was only a warning). A
fetched copy that cannot be removed keeps the old base's version, and land refuses it until it is
removed or fetched again; writing it again does not end the refusal (0.8.8.109). The land that follows names the
files that were changed on both sides, in its question (merged) and in its result.
The agent gets this as a third tool, sync, only in a workspace made with --sync (the marker then
holds "sync": true; add the key by hand to switch it on later). There the refused land says Run \sync`` and the workspace paragraph names it. Without the key the tools, the paragraph and the
refusal are those of 0.8.8.106, and the command above still works for a person.
Since 0.8.8.109 an engine left open in the folder notices when another process moved the workspace's
base: this command, oceancode workspace land, or another engine's land or sync. Before any fetch,
land or sync it compares the marker on disk with the base it holds, and when the base moved, it
refuses with the workspace's base moved to <commit> on disk and saves nothing. Start the engine again in
that folder. (In 0.8.8.108 such an engine wrote its old state back over the command's.)
oceancode base
oceancode base list
oceancode base apply <file.yaml> [--db <id>] [--dry-run] [--allow-destructive]
oceancode base schema <db> | query <db> "<sql>" [--param <json>]… [--read] | usage <db> | events <db>
oceancode base tokens mint <db> --role read|write|admin | list <db> | revoke <db> <token_id>
oceancode base delete <db> --yesOcean Base databases from the terminal, one database per kind: database YAML. <db> is a 32-hex id
or a name from list. Every command takes --json, and --format markdown|yaml|json asks the server
for that shape (?format= on every call) and prints the answer as it came. Service OCEAN_BASE_URL
(default https://base.plungeai.com); key OCEAN_API_KEY, else the ocean entry an ozk_ sign-in
stores in auth.json — with only the browser sign-in stored it answers "no Ocean API key"
(15 · Platform mode).
oceancode migrate
oceancode migrate [--db <path>]Opens the database named by --db (default oceancode.db), migrates it to the current schema, prints
opened and migrated <path>, and exits.
oceancode update
oceancode update [--self-test]Updates itself to the newest release on the configured channel; OC_UPDATE_CHANNEL (stable/beta)
overrides update.channel. Both oceancode and ocean-tui are verified first, swapped atomically, and
rolled back together if a health check fails. Prints UPDATE_APPLIED from=<old> to=<new>, or
oceancode <v> is already the newest <channel> release. --self-test exercises the swap and rollback
offline on stub binaries and prints UPDATE_OK from=<old> to=<new> rollback_tested=1, then
UPDATE_SELF_TEST_OK binaries=2. No other argument is recognised. See
17 · Distribution and updates.
oceancode verify-release
oceancode verify-release <artifact> [--pubkey <base64>] [--sha256sums <path>]Verifies the artifact's minisign <artifact>.minisig signature without any external tool. --pubkey
replaces the embedded release key; --sha256sums also checks the artifact's entry in that SHA256SUMS
file. Prints VERIFY_RELEASE_OK file=<name>. See 17 · Distribution and updates.
oceancode uninstall
oceancode uninstall [--purge] [--yes] [--dry-run]Removes the installed oceancode binary from OC_INSTALL_DIR (default ~/.local/bin). --purge also
removes the app's config and data dirs, but never a project's .oceancode/oceancode.db. Unless --yes is
given, it lists every path and asks you to type oceancode to confirm. --dry-run prints
would remove: <path> lines and removes nothing. The last line is UNINSTALL_OK removed=<n>. See
17 · Distribution and updates.
See also
- 01 · Getting started — the three boot shapes.
- 02 · Configuration — every
OC_*variable these commands read. - 07 · Headless and server —
run,serve,workflow,goalin depth. - 09 · Capabilities and plugins, 10 · Hooks, 11 · MCP servers — the capability commands.
- 17 · Distribution and updates —
update,verify-release,uninstall.