> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OceanCode guide

> oceancode is one binary and one process. This page builds it, shows the two ways to start it, and lists where it keeps its files.


`oceancode` is one binary and one process. This page builds it, shows the two ways to start
it, and lists where it keeps its files.

## Build

```bash
cargo build --release -p ocean-cli
```

The binary is named `oceancode` and, because the workspace builds into a shared target
directory, it lands at the repository-root `target/release/oceancode` (that is
`../../target/release/oceancode` from this app directory). Put it on your `PATH` or call it by
that path.

## The three boot shapes

`oceancode` starts in one of three shapes, chosen by the subcommand.

| Shape | Command | What runs |
|---|---|---|
| Pager | `oceancode` | Ocean pager (`ocean-pager`) with the Ocean engine in the same process over ACP — the terminal UI. See [19 · Ocean pager](/oceancode/pager). |
| Editor | `oceancode acp` | The engine as an Agent Client Protocol agent on stdin/stdout — what Xcode and other ACP editors launch as a subprocess. See [20 · Xcode and other ACP editors](/oceancode/xcode). |
| Headless | `oceancode serve`, or a non-interactive subcommand (`run`, `goal`, `workflow`, `ledger`, `export`, …) | The engine only, no UI: `serve` exposes the HTTP surface, the others run one job and exit. |

```bash
# 1. Pager + engine (the usual way)
oceancode

# 2. Headless server on port 4096
oceancode serve

# 3. One headless run
oceancode run "summarise the README"
```

The default mode accepts `--db`, `--directory`, `--listen` and `--verbose` (`-v`) and passes them
to the engine. `--tui pager` is accepted for compatibility and changes nothing;
`--tui ocean` fails with "the native TUI was removed; `oceancode` starts Ocean pager". Binding beyond
loopback needs `--listen` and a server password; see
[07 · Headless and server](/oceancode/headless-and-server).

## First run

Authenticate once, then start a session.

```bash
oceancode auth        # interactive: API key or Claude Pro/Max subscription
# or, non-interactively:
oceancode login       # Claude Pro/Max subscription login
oceancode key <key>   # store an Anthropic API key
```

The credential is written to `auth.json` in the data directory (below) and reused on every
later run. Then launch `oceancode` and type at the prompt.

`oceancode key <provider> <key>` stores another provider's key in the same file — `oceancode key
typesafe <key>` stores a TypeSafe key, which turns on the Jev decision layer
([13 · Jev decisions](/oceancode/jev-decisions)); `oceancode key` alone reports what is stored.

## Starting a session

A plain `oceancode` opens the pager on a fresh session. Earlier sessions are listed and resumed
from inside the pager — see its own user guide under
`ocean-pager/crates/ocean-pager-ui/docs/user-guide/`. Headless runs pick a session with
`oceancode run --continue` / `--session <id>`; see
[07 · Headless and server](/oceancode/headless-and-server).

## Updating and removing

Keep the binary current, verify a download, or remove it:

```bash
oceancode update                 # update to the newest release for your channel (verified, atomic, rollback on failure)
oceancode verify-release oceancode-macos-aarch64.tar.gz   # check a download's signature before trusting it
oceancode uninstall              # remove the binary (add --purge to also remove config + data)
```

See [17 · Distribution and updates](/oceancode/distribution) for install one-liners, channels, and the
signature/checksum trust model.

## Where files live

Paths follow the XDG layout on every platform (macOS included — `~/.config`, not
`~/Library`). `<x>` below is the matching `$XDG_*_HOME` when set, otherwise the home-relative
default shown.

| What | Location |
|---|---|
| Global config | `$OC_CONFIG`, else `<XDG_CONFIG_HOME \| ~/.config>/oceancode/oceancode.json` |
| Credentials | `<XDG_DATA_HOME \| ~/.local/share>/oceancode/` — `auth.json` |
| Models catalog cache | `<XDG_CACHE_HOME \| ~/.cache>/oceancode/models.json` |
| Session database | `oceancode.db` in the working directory, unless `--db <path>` is given |
| Project config and assets | `<project>/.oceancode/` — `oceancode.jsonc`, `oceancode.json`, `skills/`, `plans/` |

## Next

- [02 · Configuration](/oceancode/configuration) — the config keys and environment variables.
- [19 · Ocean pager](/oceancode/pager) — the terminal UI; its slash commands and keys are in
  `ocean-pager/crates/ocean-pager-ui/docs/user-guide/`.