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.

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

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 (opens in a new tab)) reachable · Gateway API key valid · MCP (https://mcp.plungeai.com (opens in a new tab)) 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 (opens in a new tab) (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:

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.