> ## 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 — full command reference

> Every command below exists in cli/src/index.ts (Commander registration) and is implemented under cli/src/commands/. Global flags: -h/--help on any command, -V/--version on the root. Running ocean with no arguments opens the AI chat REPL.


<!-- sources-of-truth: cli/src/index.ts, cli/src/commands/*.ts, cli/src/lib/ocean-config.ts, cli/README.md | last-synced: 2026-09-24 (re-verified: workflow run --async input-only behavior against workflow.ts, schedule deliver channel parsing (incl. Slack "C" prefix) against schedule-create.ts/schedule-params.ts, scheduler delivery.ts channel list — all match, no drift found) -->

Every command below exists in `cli/src/index.ts` (Commander registration) and
is implemented under `cli/src/commands/`. Global flags: `-h/--help` on any
command, `-V/--version` on the root. Running `ocean` with **no arguments**
opens the AI chat REPL.

Credential legend: **[session]** = Studio session cookie required ·
**[key]** = API key (`ozk_YOUR_KEY`) required · **[—]** = works unauthenticated.

## Top-level

### `ocean setup [--dry-run]` [—]
Installs the canonical `plungeai-workflows` skill live from
https://mcp.plungeai.com into `~/.claude/skills/` (and `~/.cursor/skills/` when
Cursor is present), creates `~/.ocean/commands/` for custom slash commands,
links bundled CLI skills into Cursor, prints the platform install-page
pointers, then runs `ocean doctor`.
- `--dry-run` — print what would be installed without writing.

### `ocean chat` [session]
AI chat REPL (identical to bare `ocean`). See [`references/agent-flows.md`](/skills/plungeai-cli-setup/references/agent-flows).

### `ocean login` [—]
Prints the cloud auth guide: how to get a Studio session cookie and an API key,
and which command saves each. Does not open a browser — everything runs on
Cloudflare; the CLI is a remote client only.

### `ocean logout` [—]
Clears saved session, API key, and conversation/refine/execution state from
`~/.ocean/config.json`.

### `ocean doctor` [—]
Live health checks; sets exit code 1 when any check fails. Checks (each auth
probe only when that credential is configured): Config · Auth · Studio
reachable · Workflows API (session) · Gateway (https://api.plungeai.com)
reachable · Gateway API key valid · MCP (https://mcp.plungeai.com) authenticated.

### `ocean whoami [--json]` [key]
Server-side identity over the MCP path: user id, tier (e.g. pro), rate window,
key name. `--json` prints `{"whoami":"<platform markdown>"}` — one string
field, not structured data; parse the markdown inside for user/tier.

### `ocean memory <action> [arg]` [key]
Long-term platform memory.
- `ocean memory recall [query]` — read memory (optionally filtered).
- `ocean memory remember` — bare = read; with one of:
  - `--add "<text>"` — append a memory line
  - `--replace "<old>" "<new>"` — exactly two values
  - `--remove "<text>"` — remove a line
  - `--target user|memory` — which store (default `user`)
- `ocean memory search-runs "<query>" [--limit N]` — search past run results.

### `ocean templates [action] [id]` [key]
Workflow templates.
- `ocean templates list [--category <cat>] [--limit N]`
- `ocean templates show <id>`
- `ocean templates use <id> [--name <name>] [--folder <name>]` — instantiate as
  a saved workflow.

### `ocean learn <source> [--name <id>]` [key]
Distill a URL or literal text into a private platform skill. `--name` sets the
kebab-case skill id.

### `ocean mission "<goal>"` [key]
Bounded autonomous agent run with memory (async + poll by default).
- `--mission <purpose>` — mission purpose statement
- `--tools <a,b,c>` — allowed tools, comma-separated
- `--max-iter <n>` — iteration cap
- `--criteria "<c>"` — success criteria, repeatable
- `--persona <id>` — persona card id
- `--skills <a,b>` — skill card ids, comma-separated
- `--sync` — wait inline instead of async+poll

Without `--sync`: polls every 5s up to 600s (then exit 1); the waiter treats
completed/failed/cancelled/error ANYWHERE in the status text as terminal — not
just the `**Status:**` field — so those words in a workflow name end the wait
early. Prefer `--sync` for short missions.

### `ocean agent …` [key]
Registry agents as tools.
- `ocean agent run <agentId> "<prompt>" [--model <m>] [--session <id>]` — one
  agent, one prompt (optionally in a conversation session).
- `ocean agent contract <agentId>` — invocation contract: operations, params,
  live credential status.
- `ocean agent call <agentId> [operation] [--params '{"k":"v"}'] [--prompt "<text>"]`
  — typed tool execution against a contract operation.

### `ocean local status [--json]` [—]
Local node daemon health on this machine (uses config `node_id`/`admin_port`).

### `ocean menu` [session]
Interactive pick-a-flow menu (non-AI).

### `ocean run [message...]` [session]
- No message: interactive flow run (picker).
- With message: one-shot AI prompt, streamed. Flags:
  - `-c, --continue` — continue the last AI conversation
  - `-m, --mode research|plan|build`
  - `-d, --depth quick|standard|deep|ultra`
  - `--json` — print `{content, conversationId}` JSON (for scripts)

### `ocean shell` [session or key]
Command shell: type any `ocean` subcommand at an `ocean›` prompt (parse errors
recover instead of exiting). Requires a TTY and at least one credential.

## `ocean auth`

- `ocean auth status` [—] — Studio/Gateway URLs, whether session and key are
  set, live Studio health.
- `ocean auth set-key` [—] — hidden prompt; value must start with `ozk_`;
  saved to `~/.ocean/config.json` (0600).
- `ocean auth set-session` [—] — hidden prompt; accepts the raw cookie value or
  a pasted `auth-session=…` fragment.

## `ocean workflow` — agent flows [session unless noted]

- `ocean workflow list` — interactive picker by default; **any flag switches to
  non-interactive output**:
  `--kind workflow|agent|bot` · `--limit N` · `--search <q>` (server-side name
  search) · `--folder <name>` · `--json`. Rows include a kind column.
- `ocean workflow show [query] [--yaml]` — look up by id, name, or picker;
  `--yaml` prints the flow YAML.
- `ocean workflow build [thinkId] [-n <name>]` — Agentic Build from a Think
  chat session (Studio parity).
- `ocean workflow create <name> <file.yaml> [-d <desc>] [--kind workflow|agent|bot] [--json]`
  — save from a YAML file. CNL-validated + policy-linted: `memory_owner:`
  refused, hardcoded emails/UUIDs warn, `--kind bot` requires exactly one
  `type: harness` task whose mission ends with `task_complete`.
- `ocean workflow update <id> [-f|--file <file.yaml>] [-n <name>] [--description <text>]`
- `ocean workflow edit <id>` — edit session: YAML editor, refine, run, until
  Esc. (`ocean workflow tweak <id>` is a kept alias.)
- `ocean workflow delete <id>`
- `ocean workflow refine <id> "<what to change>" [-d <depth>] [--json]` — AI
  one-shot edit in plain English.
- `ocean workflow versions <id>` — version history.
- `ocean workflow restore <id> <versionRef>` — version number or id prefix.
- `ocean workflow undo [id]` — restore the pre-refine snapshot.

  `delete`/`restore`/`undo` prompt `[y/N]` with no `--yes` flag — in scripts
  pipe `echo y | ocean workflow delete <id>`; an EOF answer cancels with
  exit 0 (the script "succeeds" without deleting).
- `ocean workflow followup <id> "<prompt>" [-e|--execution <executionId>]` — follow-up
  question on a completed execution (default: last run).
- `ocean workflow run <id>` — run with live SSE output, then result + any
  pending question/approval continuation. Flags:
  - `-i, --input "<text>"` — single input value
  - `--inputs <file.json>` — named inputs (flat JSON object, string values);
    mutually exclusive with `--input`
  - `--json` — raw SSE events as JSON lines
  - `--async` **[key]** — dispatch via the MCP surface and return the
    execution id immediately; prints a `poll: ocean execution status <id>` hint.
    Only `-i` is honored with `--async` — `--inputs` and `--json` are silently
    ignored on the async path (named inputs need a sync run or Studio).
- `ocean workflow run-yaml <file> [-i "<input>"]` **[key preferred; session
  fallback]** — execute ad-hoc YAML (nothing saved). With a key: via
  https://api.plungeai.com (`POST /v1/workflows/execute` + result redemption).
  With only a session: falls back to Studio's execute proxy and prints the raw
  engine envelope JSON, no redeemed markdown. `{input}` placeholder receives
  `-i`.

## `ocean session` — Think chat sessions [session]

- `ocean session list` — list conversations.
- `ocean session export [file]` — export the current conversation to markdown
  (requires an active conversation from `ocean chat`).

## `ocean registry` — platform discovery [session]

Registry data loads live from the platform discovery service — never a static
catalog.

- `ocean registry` — browse everything.
- `ocean registry <category> [subtype]` — categories: `agents` `twins`
  `experts` `skills` `plugins` `mcp` `models` `providers` `connectors`.
- `ocean registry lookup <query…>` / `ocean registry show <query…>` — one
  entry's card.
- `ocean registry <free text>` — direct lookup shorthand.

Non-TTY: category browse (`ocean registry`, `ocean registry agents`) prints
only "Registry browse requires an interactive terminal" and exits 0 — a no-op
for scripts. `ocean registry lookup <query>` DOES work non-interactively (exact
card, or a plain list of up to 20 matches); key-only discovery goes through the
One API discovery search instead (`plungeai-api-setup` skill).

## `ocean schedule` — scheduled jobs [session]

- `ocean schedule` / `ocean schedule overview` — jobs + today stats.
- `ocean schedule jobs` — browse jobs (picker in a TTY, plain list when piped).
- `ocean schedule runs` — run history.
- `ocean schedule create <name> --type agent|query|workflow|heartbeat --cron "<expr>"`
  — agent/query jobs are wrapped as one-task workflows. Options:
  - `--target <id>` — agent id (agent/query) or workflow id (workflow)
  - `--prompt "<text>"` — what the agent does each run (`--query` is an alias
    for `--type query`)
  - `--mission-ref <id>` — pre-built agent card id (schedules a harness wrapper)
  - heartbeat only: `--check-agent <id>` · `--condition "<prompt>"` ·
    `--trigger <workflowId>` · `--notify telegram|whatsapp|discord|slack|email`
    · `--notify-to <target>`
  - `--deliver <channel:to>` — repeatable delivery targets. Channels:
    `telegram:<chat-id>` · `whatsapp:<number>` · `discord:<chat-id>` ·
    `slack:<target>` · `email:a@b.c` · `inapp` (no target). Slack values
    starting with `C` are treated as channel ids; anything else as a member
    id/handle.
  - `--local` — mark for local-node execution
  - `--description "<text>"` · `--json`
- `ocean schedule get <id> [--json]` — one job including delivery targets.
- `ocean schedule update <id>` — **fresh-GET → merge → PUT; delivery settings
  preserved** unless `--deliver` is passed (which REPLACES them). Options:
  `--cron` · `--name` · `--description` · `--prompt` · `--deliver …` ·
  `--status active|paused` · `--json`.
- `ocean schedule delete <id>` — soft delete (history preserved). Removes only
  the job: agent/query/mission-ref jobs leave their auto-created wrapper
  workflow "Scheduled: <name>" in your flows — `ocean workflow delete <id>` it
  separately if you want it gone.

Example:
```bash
ocean schedule create "Weekday brief" --type agent --target research-agent \
  --prompt "top AI news, 5 bullets" --cron "0 9 * * 1-5" \
  --deliver slack:CHANNEL_ID --deliver email:me@example.com
```

## `ocean execution` — runs & results [session unless noted]

Only `status` and `output` have API-key fallbacks; everything else here —
including `continue` and `export` — is session-only with no key path (a
key-only script cannot continue a paused run or export).

- `ocean execution list [-w|--workflow <workflowId>] [-l N]` — recent runs (limit default
  20, must be a positive integer).
- `ocean execution status <id> [--json]` **[session or key]** — one-line
  status; when the run is paused on a question/approval, the ⏸ block is relayed
  verbatim (the printed `continue … --approve` hint is itself session-only).
  Falls back to the MCP key path for gateway-dispatched runs. `--json` shape
  differs by path: Studio = full execution JSON (`.status` field); key/MCP =
  `{"execution_id","status_text":"<markdown>"}` — parse the `**Status:**` line
  inside `status_text`.
- `ocean execution show <id>` — metadata.
- `ocean execution output <id>` **[session or key]** — result markdown (MCP key
  fallback for gateway-dispatched runs). Rendered terminal-formatted (wrapped,
  `── Output ──` header, pager for long results in a TTY); there is no
  raw-markdown flag — for byte-exact artifacts use `execution export`
  (session), or parse the wrapped text with `NO_COLOR=1`.
- `ocean execution conversation <id>` — full multi-turn thread
  (input → result → follow-ups).
- `ocean execution continue <id> [--approve]` — resume a paused conversation:
  answer the pending question (prompted) or approve the pending action.
- `ocean execution export <id> -f|--format <fmt> [-o|--out <file>] [--models <list>]` —
  formats: `docx` · `pptx` · `xlsx` · `finmodel` · `pdf` · `package` ·
  `google-docs`. `--models` selects FinModel types.
- `ocean execution versions <id>` — saved result snapshots.
- `ocean execution save-version <id> ["note"]`
- `ocean execution restore-version <id> <version>` — number or version id.

## `ocean observatory` [session]

- `ocean observatory run <workflowId> [-i "<input>"] [--inputs <file.json>]` —
  run with an Observatory-style live event timeline instead of the plain stream.

## Validation & error behavior

- Numeric flags like `-l/--limit` reject non-positive/non-integer values.
- Choice flags (`--mode`, `--depth`) reject values outside their set.
- `auth set-key`/`set-session` take no positional value — a pasted secret dies
  with Commander's "too many arguments". Nothing else scans argv, and argv is
  sent to the platform as `user_request` on every key-side verb — keep secrets
  out of all command arguments (hidden prompts / `OCEAN_API_KEY` only).
- A 401 from any surface prints a friendly hint (`ocean login` /
  `ocean auth set-key`) instead of a stack trace.
- Exit codes are 0/1 only. Failures exit 1 (`ocean doctor` included), and sync
  `workflow run` exits 1 when the run itself reports a workflow error — but
  `execution status`/`output` of a FAILED run exit 0 (they successfully report
  the failure; `output` prints a "_No stored markdown output_" notice). Async
  CI gates must parse the status value, not the exit code.