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

# Ocean CLI — install, auth, and setup

> The npm package @plungeai/ocean-cli (v2.3.0, bin name ocean, Node >= 20) is not yet published — publishing is an owner action (pushing the ocean-cli-v2.3.0 tag triggers the publish workflow). Current truth from cli/README.md:


<!-- sources-of-truth: cli/README.md, cli/src/lib/ocean-config.ts, cli/src/commands/auth.ts, cli/src/commands/doctor.ts, cli/src/commands/setup.ts, cli/src/lib/login.ts, cli/package.json | last-synced: 2026-09-24 (re-verified: version 2.3.0 + publish trigger against cli/README.md and package.json — matches; fixed a stale "Dashboard → API Keys" UI label to Dashboard → One API → Keys per apps/ocean-dashboard/src/nav.ts) -->

## Install

The npm package `@plungeai/ocean-cli` (v2.3.0, bin name `ocean`, Node >= 20)
is **not yet published** — publishing is an owner action (pushing the
`ocean-cli-v2.3.0` tag triggers the publish workflow). Current truth from
`cli/README.md`:

```bash
# Working today — from the Ocean-Platform repo root:
npm run ocean -- --help        # run any command through the repo
npm run build:cli              # optional: build dist for ~40ms startup
npm link                       # or: put the `ocean` bin on your PATH

# Once published to npm:
npm install -g @plungeai/ocean-cli
# or without installing:
npx @plungeai/ocean-cli --help
```

Verify: `ocean --version` (inside the repo it appends the platform version).

The linked `ocean` bin prefers `cli/dist/index.js` whenever it exists — after
updating the repo, rerun `npm run build:cli` (or delete `cli/dist`) or the bin
silently executes the stale build. `npm run ocean --` always runs current
source.

## The two credentials

The CLI keeps credentials strictly separated — the Studio cookie is only ever
sent to Studio; the API key only to the Gateway and MCP server.

| Credential | Format | Unlocks | Set with |
|---|---|---|---|
| Studio session | `auth-session` cookie value | AI chat/REPL, saved flows, runs, results, exports, schedules, registry, sessions | `ocean auth set-session` |
| API key | `ozk_YOUR_KEY` | `workflow run-yaml`, `workflow run --async`, `whoami`, `memory`, `templates`, `learn`, `mission`, `agent …` | `ocean auth set-key` |

### Get a Studio session

1. Sign in at https://studio.plungeai.com
2. Copy the `auth-session` cookie value from your browser (devtools →
   Application/Storage → Cookies).
3. `ocean auth set-session` — hidden prompt. Pasting the whole
   `auth-session=…` fragment also works; the CLI extracts the value.

### Get an API key

1. Self-service: **Ocean Dashboard → One API → Keys** (`https://dashboard.plungeai.com`) →
   create a key → name it, pick an expiry (never, or 7–365 days) → copy it once
   (`ozk_YOUR_KEY` — it is shown exactly once and stored hashed). Ask the account
   owner only for a shared/team key minted under someone else's account.
2. `ocean auth set-key` — hidden prompt. The CLI refuses values that don't
   start with `ozk_`.

`ocean login` prints this whole guide in the terminal. `ocean auth status`
shows what's configured plus a live Studio health probe. `ocean logout` clears
both credentials and cached conversation/refine/execution state.

## Key handling rules (hard)

- Keys and cookies are entered ONLY via hidden prompts or the `OCEAN_API_KEY`
  env var. Never on argv: `auth set-key`/`set-session` take no positional value
  (a pasted secret errors with Commander's "too many arguments"), but nothing
  else scans argv — and argv IS sent to the platform as `user_request` on every
  key-side verb — so keep secrets out of all command arguments, shell history,
  repos, and committed `.env` files.
- Storage: `~/.ocean/config.json`, written with mode `0600`.
- CI / ephemeral use: `export OCEAN_API_KEY=ozk_YOUR_KEY` — the env override
  wins over the config file for the process, **but it is persisted on the next
  state save**: any command that saves CLI state (`workflow run`/`run --async`,
  `refine`, `chat`, `ocean run`, `observatory run`) writes the merged config —
  env key included — back to `~/.ocean/config.json` (0600). On shared or
  persistent runners use a throwaway `HOME` (`export HOME=$(mktemp -d)`) or
  finish with `ocean logout`. Verbs that never save: `whoami`, `doctor`,
  `run-yaml`, `agent run`, `memory`, `mission`.

## Config file — `~/.ocean/config.json`

Created on first save; JSON, mode 0600. Fields you may care about:

| Field | Meaning | Default |
|---|---|---|
| `studio_url` | Studio origin | `https://studio.plungeai.com` |
| `api_gateway_url` | Gateway origin | `https://api.plungeai.com` |
| `mcp_url` | MCP server for key-side verbs | `https://mcp.plungeai.com` |
| `shared_memory_url` | SharedMemory host for stream pointer polling (rarely overridden) | platform default |
| `access_token` | Studio session cookie value | — |
| `api_key` | `ozk_YOUR_KEY` | — |
| `chat_mode` / `chat_depth` | REPL defaults (`research|plan|build`, `quick|standard|deep|ultra`) | build / deep |
| `conversation_id`, `last_execution_id`, `refine_workflow_id`, `refine_undo` | Session state the CLI maintains | — |
| `voice_replies` | `/voice on|off` persisted | off |
| `node_id`, `admin_port` | Local node daemon (for `ocean local status`) | — |

Requests to a stale decommissioned gateway host are transparently redirected to
`https://api.plungeai.com` at request time only — the file itself (and the
`ocean auth status` display) keeps the old value until the next save. Don't
hand-edit around it.

## `ocean setup`

One command prepares coding-agent integration:

```bash
ocean setup            # install; then runs doctor
ocean setup --dry-run  # list what would be installed, write nothing
```

What it does:
1. Installs the canonical **plungeai-workflows** skill live from
   https://mcp.plungeai.com (fetches the file list from `/llms.txt`) into
   `~/.claude/skills/` — and `~/.cursor/skills/` when a `~/.cursor` dir exists.
2. Creates `~/.ocean/commands/` for custom REPL slash commands.
3. Links bundled CLI skills into `~/.cursor/skills/`.
4. Prints the one-click install pointers from the platform install page.
5. Runs `ocean doctor`.

Note: the bundled trio is `ocean-cli-lifecycle`, `ocean-cli-workflow`,
`ocean-observatory` (from `cli/skills/`) — `ocean setup` does NOT install or
update this `plungeai-cli-setup` skill.

## `ocean doctor` — the verification command

Run after every install or credential change; it exercises each configured
credential against the live platform and sets exit code 1 on any failure:

| Check | Probe | Runs when |
|---|---|---|
| Config | `~/.ocean/config.json` + Studio URL | always |
| Auth | session or key present | always |
| Studio | health endpoint reachable | any credential set |
| Workflows API | authenticated list call | session set |
| Gateway | https://api.plungeai.com health | key set |
| Gateway API key | key accepted | key set |
| MCP | `plungeai_whoami` over https://mcp.plungeai.com/v1 (Bearer key) | key set |

All-green ends with "Ready to run workflows". Each ✗ names its fix.
Caveat: the session probe runs first in the same chain — if it throws (expired
cookie), doctor records "Studio API ✗" and SKIPS the Gateway/MCP checks even
when a valid key is set.
Doctor also tips: if `$EDITOR` is a GUI app, `/edit` uses the inline terminal
editor; set `OCEAN_EDITOR=nano` (or another terminal editor) for Ctrl+E
external editing.

## Troubleshooting

| Symptom | Fix |
|---|---|
| `Not authenticated` | `ocean login`, then set a credential |
| `A Studio session is required for this command` | `ocean auth set-session` — API keys only cover the key-side verbs |
| 401 / "key rejected" on Gateway or MCP | Key revoked or mistyped — mint a new one at Dashboard → One API → Keys, `ocean auth set-key` |
| Studio calls fail after working earlier | Session cookie expired — sign in again, `ocean auth set-session` |
| `API key must start with ozk_` | You pasted something else (cookie? bearer header?) — copy the raw key |
| Doctor Gateway ✗ but Studio ✓ | Key-side config issue; re-run `ocean auth set-key`, check `api_gateway_url` is `https://api.plungeai.com` |
| Voice recording does nothing | Recording needs `sox` (`brew install sox`); spoken replies work without it |
| Doctor shows only "Studio API ✗" and no Gateway/MCP rows | The expired session aborted the check chain — re-set the session (or `ocean logout` + set only the key) and rerun |
| Scripts hang at a prompt | You hit an interactive picker — pass flags (`--json`, `--limit`, ids) to force non-interactive output. Exception: `ocean registry` browse has no flags and is a no-op when piped — use `ocean registry lookup <query>` |
| CI output full of escape codes / greps miss | `$CI` force-enables ANSI color even without a TTY — export `NO_COLOR=1` or use `--json` |

Escalation path: `ocean doctor` → `ocean auth status` → re-set the failing
credential → `ocean doctor` again (exit 0 = done).