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

# ocean-cli — install, credentials, config, doctor

> Skill: plungeai-cli-setup. The full verb tree is in the ocean-cli skill (references/verbs.md).


<!-- sources-of-truth: apps/ocean-cli/README.md apps/ocean-cli/src/commands/account.ts apps/ocean-cli/src/runtime/session.ts -->

Skill: `plungeai-cli-setup`. The full verb tree is in the `ocean-cli` skill (`references/verbs.md`).

## Install

- `@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: `npm install -g @plungeai/ocean` (Node ≥ 20), then `ocean-cli --help`; without installing: `npx @plungeai/ocean --help`.
- Installer: `curl -fsSL https://plungeai.com/install.sh | sh` checks Node, runs the npm install and prints the login line (it fails at npm's 404 until the publish).
- From a clone of the Ocean-Platform repository: `npm run ocean-cli -- --help` (TypeScript source via tsx), or
  `npm run build:ocean-cli` and `node apps/ocean-cli/dist/index.js --help` for the bundle.
- `ocean-cli --version` prints `ocean-cli, version 2.x`. `ocean-cli update --check` compares it with the npm registry;
  `ocean-cli update` installs the latest version.

## Credentials

| Credential | Used by | Store it | Environment override |
|---|---|---|---|
| API key `ozk_YOUR_KEY` | web verbs, agents, tools, workflows, bots, executions, missions, schedules, memory, learn, templates, chat, discovery, models, mcp, traces | `ocean-cli login` | `OCEAN_API_KEY` (or `PLUNGEAI_API_KEY`) |
| Studio session (the `auth-session` cookie value) | keys, balance, usage, nodes, campaigns, connections, secrets, documents, teams, projects, `executions export` | `ocean-cli login --session` | `OCEAN_SESSION` |
| Legacy inference key `sk-ocean-…` | `models list\|chat\|embed`, only when no API key is stored | hidden option `ocean-cli login --inference` | `OCEAN_INFERENCE_KEY` |

- `ocean-cli login` opens your browser at https://dashboard.plungeai.com. Sign in there (any method) and the CLI receives
  your account key through a one-time code sent to `127.0.0.1`, verifies it and stores it. The key never appears in a
  browser URL. If no sign-in arrives within 3 minutes, the command exits 5.
- `--no-browser` asks for a pasted key at a hidden prompt instead (create one at One API → Keys) — use it over SSH.
  `--key -` reads the key from stdin and `--key FILE` from a file; neither opens a browser, and `--session` never does.
  A secret is never accepted as a command-line argument.
- In a terminal the first verb that needs the key asks for it; under `--json`, in a pipe or in CI it exits 3 instead.
- `ocean-cli logout` clears the credential fields and nothing else.
- Credentials live in `~/.ocean/config.json` (mode 0600). `OCEAN_CLI_CONFIG_DIR` points the CLI at another directory,
  which isolates CI runners. Environment credentials win for one process and are never written to disk.
- Each credential goes only to its own hosts: the API key to `https://api.plungeai.com` (`X-API-Key`) and
  `https://mcp.plungeai.com/v1` (`Authorization: Bearer`); the session cookie to `https://studio.plungeai.com` and
  `https://dashboard.plungeai.com`.

## Config

`ocean-cli config [KEY] [VALUE]` views or sets `api_url`, `mcp_url`, `studio_url`, `dashboard_url` and
`default_provider` (the search agent: `parallel`, `tavily`, `firecrawl`, `serper`, `brave` or `exa`).
Other environment variables: `OCEAN_CLI_QUIET=1` (silence status lines), `OCEAN_CLI_TIMEOUT_MS` (request limit, default 120000).

## Verify with `ocean-cli doctor`

Up to six live checks (the three hosts always; the two key checks when an API key is stored; the Studio session
check when a session is stored); it exits 4 when any fails and names the fix:

```
✓ API reachable: https://api.plungeai.com 200
✓ MCP reachable: https://mcp.plungeai.com 200
✓ Studio reachable: https://studio.plungeai.com 200
✓ API key valid: discovery search 200
✓ MCP key valid: <user id> (<tier>)
✓ Studio session valid: workflows 200
```

A ✗ on a key line: run `ocean-cli login` again. A ✗ on the Studio session line: `ocean-cli login --session` (only the
Studio verbs need it). `ocean-cli auth --json` prints `{authenticated, method, token_file, user_id, tier, session, inference_key}`
with `method` one of `env`, `api_key`, `none`. `ocean-cli whoami` shows the identity, tier and rate window; the free tier
allows 30 requests per minute.

## Exit codes

| Code | Class | When |
|---|---|---|
| 0 | ok | success, help, version |
| 2 | bad input | a bad flag or argument, invalid JSON, a missing `--yes`, a file that does not exist |
| 3 | auth | no credential for the surface, HTTP 401/403 |
| 4 | API | any other non-2xx, a tool outcome of error/needs approval, a rate limit, a refusal by the unattended fence (`approval_required`) |
| 5 | timeout | `--timeout` reached while waiting, or a request timed out |

With `--json` an error is one JSON object on stderr: `{"error":{"code":"…","message":"…","status":…}}`.