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

> 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 when there is no shell.

[Download zip](https://skills.plungeai.com/ocean-cli.zip) · [View raw SKILL.md](https://skills.plungeai.com/ocean-cli/SKILL.md)

`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

```bash
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`](/skills/ocean-cli/references/verbs).

```bash
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 contract
```

## 3. 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-key` and `secrets set`
  read from a hidden prompt, from `--key -`/`--value -` on stdin, or from a file.
- Destructive verbs (delete, revoke, restore, remove, forget, unbind) require `--yes` and exit 2 without it — ask the
  user to confirm before adding `--yes`. Use `--dry-run` to show a paid or creating call before it runs.
- `monitor create` is refused by the unattended fence (exit 4 `approval_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 limit` message): wait the seconds it names, then retry once.
- Parse `--json` output; show the human output to the user. `research`, `findall`, `missions` and `enrich` write result
  files (`-o` sets 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.

## Reference pages

<CardGroup cols={2}>
<Card title="ocean-cli — every command and flag (generated)" icon="file-text" href="/skills/ocean-cli/references/verbs">
ocean-cli — every command and flag (generated)
</Card>
</CardGroup>