ocean-cli — install, credentials, config, doctor

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

• ocean-cli login opens your browser at https://dashboard.plungeai.com (opens in a new tab). 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

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