Capability
ocean-cli
Drive PlungeAI Ocean from a terminal with the ocean-cli command (package @plungeai/ocean): web search, extract and deep research, registry agents and tool agents, saved workflows and bots, executions, missions, schedules and their triggers, memory, templates, the registry, and the Studio account…
Drive PlungeAI Ocean from a terminal with the ocean-cli command (package @plungeai/ocean): web search, extract and deep research, registry agents and tool agents, saved workflows and bots, executions, missions, schedules and their triggers, memory, templates, the registry, and the Studio account surfaces. Use when an agent has shell access and the task touches PlungeAI — prefer this over the MCP server in Claude Code, Cursor, Codex, Copilot, OpenCode or OceanCode; fall back to https://mcp.plungeai.com/v1 (opens in a new tab) when there is no shell.
Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)
ocean-cli is a non-interactive remote client: every command talks to the deployed PlungeAI hosts
(https://api.plungeai.com, https://mcp.plungeai.com/v1, https://studio.plungeai.com) and nothing runs
locally. Every verb takes --json, long operations take --no-wait plus a status/poll verb, exit codes are
stable (0 ok · 2 usage · 3 auth · 4 refused/not ready/rate limited · 5 timeout), and status lines go to stderr.
1. Make sure it is installed and logged in
which ocean-cli || npm install -g @plungeai/ocean # Node ≥ 20; once published (next paragraph); or: npx @plungeai/ocean --version
ocean-cli --version # ocean-cli, version 2.x
ocean-cli auth --json # {"authenticated": true, …} — else the user runs: ocean-cli login (browser sign-in)
ocean-cli doctor # live check of every plane; exit 4 lists what is missing@plungeai/ocean is not on npm yet: until the ocean-v2.1.0 tag is published, run it from the repository (npm run build:ocean-cli + node apps/ocean-cli/dist/index.js). A missing credential exits 3 with the exact login command to run. ocean-cli login opens the browser and stores the
ozk_ key; over SSH or in a headless shell the user runs ocean-cli login --no-browser (hidden prompt) — never paste
a key on the command line. Studio verbs (keys, balance, usage, nodes, campaigns, connections, secrets,
documents, teams, projects, executions export) need ocean-cli login --session. Environment variables
OCEAN_API_KEY, OCEAN_SESSION override the stored credentials for one process and are never written to disk.
2. Discover before you guess
The flags below change between versions. Always confirm with --help before composing a call you have not run
in this session; the complete tree is in references/verbs.md.
ocean-cli --help # every noun
ocean-cli research --help # verbs of a noun
ocean-cli research run --help # flags of a verb, with examples
ocean-cli discovery search "web search" --kind agents --limit 5 --json # discover agents, tools, skills, personas live
ocean-cli agents list --limit 20 --json · ocean-cli tools get <agent_id> --json # an agent's card / a tool agent's contract3. Task → command
| The user wants | Run |
|---|---|
| a web answer with sources | ocean-cli search "<objective>" --max-results 5 --json (keyword mode: -q "<kw>" -q "<kw>"); ocean-cli answer "<question>" --effort low --json for a cited answer |
| a page as clean markdown | ocean-cli extract <url> [--objective "<focus>"] --json |
| deep research (minutes, paid) | ocean-cli research run "<question>" -p lite-fast --no-wait --json → ocean-cli research poll <run_id> --timeout 900 -o report --json (writes report.json; add --text on run for a markdown report) |
| find entities / enrich rows (paid) | ocean-cli findall run "<objective>" -g base -n 25 --json; ocean-cli enrich run --source rows.csv --intent "<what to add>" --target out.csv |
| run one platform agent | ocean-cli agents run <agent_id> "<prompt>" --json (--stream for live tokens); read later with ocean-cli agents result <workflow_id> <task_id> --json |
| call a tool agent with typed params | ocean-cli tools get <agent_id> --json for the contract, then ocean-cli tools call <agent_id> <operation> --params '{"…"}' --json |
| design a workflow from a goal | ocean-cli workflows build --goal "<what it should do>" --json → save the YAML to a file → ocean-cli workflows validate <file> → ocean-cli workflows create "<name>" <file> --json |
| change a saved workflow | ocean-cli workflows build --workflow-id <id> --instruction "<change>" --json → validate → ocean-cli workflows update <id> -f <file>; history: workflows versions <id> / workflows save-version <id> --label "<why>" / workflows restore <id> <version_id> --yes |
| run a workflow | ocean-cli workflows run <id-or-file.yaml> -i "<input>" --json (waits); --no-wait → ocean-cli executions poll <execution_id> --json |
| see runs and results | ocean-cli executions list --limit 10 --json, ocean-cli executions output <id>, ocean-cli executions conversation <id> --json, ocean-cli executions followup <id> "<question>", ocean-cli executions files <id> |
| steer or answer a live run | ocean-cli executions steer <id> "<text>" (queued for the running loop; a finished run exits 4); ocean-cli executions continue <id> --message "<answer>" or --approve for a paused run |
| a bounded autonomous run with memory | ocean-cli missions run "<goal>" --max-iterations 5 --no-wait --json → ocean-cli missions poll <id> -o mission.json --json (--sync answers on one connection) |
| schedule something | ocean-cli schedules create "<name>" --type agent --target <agent_id> --prompt "<prompt>" --cron "0 9 * * 1-5" --deliver inapp; once: --type workflow --target <id> --cron @once --at <ISO time with UTC offset>; schedules list, pause, resume, runs, wake <id> --note "<why>", delete <id> --yes |
| start a schedule from outside | ocean-cli schedules triggers webhook mint <job_id> --scheme github, triggers email mint <job_id>, triggers hooks mint <job_id> --url <https-url> (outbound signed run events); each has list and delete … --yes; a minted secret is shown once |
| remember / recall | ocean-cli memory recall, ocean-cli memory remember --add "<fact>", ocean-cli memory search-runs "<query>" --limit 5 --json |
| templates, learned skills, chat | ocean-cli templates list, templates use <id> --name "<name>"; ocean-cli learn add <url> --name <id>; ocean-cli chat send "<message>" [--conversation-id <id>] |
| account, keys, spend | ocean-cli whoami, ocean-cli keys list --json, ocean-cli balance --json, ocean-cli usage --by model --range 30d |
| local nodes, connections, secrets, documents, teams, projects | ocean-cli nodes list --json, connections list, secrets list --team-id <id>, documents list, teams list, projects list (Studio session) |
| export a result as a file | ocean-cli executions export <id> -f docx -o result.docx (pptx, xlsx, pdf, finmodel, package, google-docs) |
| install the PlungeAI skills | ocean-cli skills list, ocean-cli skills install --project --skill <name> |
4. Bots (saved workflows of kind bot)
A bot is a saved workflow with kind: bot; its policy, files, inbox and chats are verbs on workflows, and named sets
of bots are bot-groups.
| The user wants | Run |
|---|---|
| list or create bots | ocean-cli workflows list --kind bot --json; ocean-cli workflows create "<name>" <file> --kind bot |
| see or change what a bot may do | ocean-cli workflows permissions get <bot_id> --json; ocean-cli workflows permissions set <bot_id> --class pay=ask --class send=allow --budget-run 0.5 --budget-month 20 (classes send, write, pay, delete; presets allow, ask, deny, hand_off; --lock/--unlock are team admins only; add --dry-run first) |
| a bot's workspace files and inbox | ocean-cli workflows files <bot_id>, ocean-cli workflows files <bot_id> --download <path> --out <file>, ocean-cli workflows inbox <bot_id> |
| chats bound to a bot | ocean-cli workflows bindings list <bot_id>, … bind <bot_id> --channel telegram --sender <sender_id>, … unbind <bot_id> --channel telegram --sender <sender_id> --yes (the chat is paired in Studio first) |
| groups of bots | ocean-cli bot-groups list, ocean-cli bot-groups create --name <name> --members <bot_id>,<bot_id> (2 to 6 members), update <id> --name … --members …, thread <id>, delete <id> --yes |
5. Rules that keep the user safe
- Never put a key, session or secret value on a command line;
login --no-browser,connections add-keyandsecrets setread from a hidden prompt, from--key -/--value -on stdin, or from a file. - Destructive verbs (delete, revoke, restore, remove, forget, unbind) require
--yesand exit 2 without it — ask the user to confirm before adding--yes. Use--dry-runto show a paid or creating call before it runs. monitor createis refused by the unattended fence (exit 4approval_required): report it, do not retry; the user approves from Studio. Priced verbs take--max-cost <usd>.- The free tier allows 30 requests per minute (exit 4 with a
Rate limitmessage): wait the seconds it names, then retry once. - Parse
--jsonoutput; show the human output to the user.research,findall,missionsandenrichwrite result files (-osets the path; existing files are not overwritten without--force).
6. When to use the MCP server instead
No shell (claude.ai, Claude Desktop, ChatGPT), or an approval-gated operation the user wants to confirm in-chat:
connect https://mcp.plungeai.com/v1 with Authorization: Bearer ozk_YOUR_KEY — see the plungeai-mcp-setup skill.
Everything the CLI does is also a One API route (https://api.plungeai.com/v1/openapi.json) for your own code.