Ocean CLI — install, auth, and setup

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:

# 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.

Get a Studio session

1. Sign in at https://studio.plungeai.com (opens in a new tab)
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:

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:

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 (opens in a new tab) (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:

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

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