> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# plungeai-cli-setup

> Install and log in to the PlungeAI Ocean CLI (ocean-cli, npm package @plungeai/ocean) and run your first commands.


Install and log in to the PlungeAI Ocean CLI (ocean-cli, npm package @plungeai/ocean) and run your first commands. Use when a user or agent wants PlungeAI from a terminal, CI or a shell-first coding agent and does not have ocean-cli working yet; hand over to the ocean-cli skill for the full verb reference.

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

`ocean-cli` is PlungeAI's non-interactive command-line client — the CLI door next to the MCP server
(`https://mcp.plungeai.com/v1`) and the One API (`https://api.plungeai.com/v1/openapi.json`). It runs nothing
locally: every command calls the deployed platform. Full verb reference: the `ocean-cli` skill.

## Install (Node ≥ 20)

```bash
node --version                         # v20 or newer
npm install -g @plungeai/ocean         # once published (see below); or: npx @plungeai/ocean --help
ocean-cli --version                    # ocean-cli, version 2.x
```

`@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`). After the publish, `curl -fsSL https://plungeai.com/install.sh | sh` is the alternative (checks Node, runs the npm install, prints the login
line); before it, that script ends at npm's 404. From a clone of Ocean-Platform: `npm run ocean-cli -- --help`. Update later with `ocean-cli update`.

## Log in — one key, one optional session

| Credential | Get it | Store it | Unlocks |
|---|---|---|---|
| API key `ozk_…` | `ocean-cli login` opens the browser at https://dashboard.plungeai.com (any sign-in method); or One API → Keys | `ocean-cli login` (browser) · `ocean-cli login --no-browser` (hidden prompt, for SSH) | search, research, agents, tools, workflows, bots, executions, missions, schedules, memory, discovery, chat, models, traces |
| Studio session | Studio → your `auth-session` cookie value | `ocean-cli login --session` | keys, balance, usage, nodes, campaigns, connections, secrets, documents, teams, projects, `executions export` |

Never pass a credential as an argument. In CI use `--key -` on stdin, or set `OCEAN_API_KEY` / `OCEAN_SESSION`
(environment values win for one process and are never written to disk). Credentials live in `~/.ocean/config.json`
(mode 0600).

## Verify

```bash
ocean-cli auth --json     # {"authenticated": true, "method": "api_key", "user_id": "…", "tier": "…", "session": false, …}
ocean-cli doctor          # ✓ API / MCP / Studio reachable, ✓ each stored credential valid — exit 4 lists what is missing
ocean-cli whoami          # identity, tier, rate window
```

## First three commands

```bash
ocean-cli search "Who is the current Head of Sales at Adyen?" --max-results 3
ocean-cli discovery search "web search" --kind agents --limit 5 --json    # discover agents live — never guess an id
ocean-cli agents run one-agent "Reply with exactly: hello from ocean-cli" --json
```

## Conventions you can rely on

`ocean-cli <noun> <verb> [ARGS] [--flags]`; `--json` on every verb; `--help` on every level; exit codes 0 ok ·
2 usage · 3 auth · 4 refused/not ready/rate-limited · 5 timeout; long operations take `--no-wait` and a `poll` verb;
destructive verbs need `--yes`; `--dry-run` shows a paid or creating call without sending it; `-` reads a text
argument from stdin; results of `research`, `findall`, `missions` and `enrich` are saved to files. Shell completion:
`ocean-cli completion install`. The PlungeAI skills themselves: `ocean-cli skills install`.

## Slash commands in your coding agent

The PlungeAI plugin ships `/ocean-*` commands (`/ocean-run`, `/ocean-create`, `/ocean-runs`, `/ocean-schedule`, …)
for Claude Code and OceanCode that call `ocean-cli` for you — see `plungeai-in-claude-code`. `/ocean` lists them.

## Reference pages

<CardGroup cols={2}>
<Card title="ocean-cli — flows an agent runs end to end" icon="file-text" href="/skills/plungeai-cli-setup/references/agent-flows">
Skill: plungeai-cli-setup. Replace <…> with real values; confirm any flag with ocean-cli <noun> <verb> --help.
</Card>
<Card title="ocean-cli — install, credentials, config, doctor" icon="file-text" href="/skills/plungeai-cli-setup/references/auth-and-setup">
Skill: plungeai-cli-setup. The full verb tree is in the ocean-cli skill (references/verbs.md).
</Card>
<Card title="ocean-cli — the nouns" icon="file-text" href="/skills/plungeai-cli-setup/references/commands">
Grammar: ocean-cli <noun> <verb> [ARGS] [--flags].
</Card>
</CardGroup>