--- name: plungeai-cli-setup description: "Operate the Ocean CLI (`ocean`; package @plungeai/ocean-cli — not yet on npm, run from the Ocean-Platform repo) to drive PlungeAI from a terminal: install/setup, auth (Studio session cookie vs self-service ozk_ key and which commands need which), running saved workflows and ad-hoc CNL YAML, async runs and status polling, executions/results/exports, schedules, registry lookups, missions, memory, templates, the AI chat REPL and its slash commands, and troubleshooting with `ocean doctor`. Use when the user mentions the `ocean` command or wants PlungeAI operated from a shell or CI script. Triggers: \"ocean cli\", \"ocean command\", \"plungeai cli\", \"@plungeai/ocean-cli\", \"ocean doctor\", \"ocean workflow run\", \"run plungeai from terminal\", \"ocean repl\", \"ocean shell\". NOT for raw HTTP calls (`plungeai-api-setup`), plungeai_* MCP tool calls (`plungeai-mcp-setup`), authoring CNL YAML (`plungeai-workflows`), or wiring other AI tools (`plungeai-in-`)." --- # Ocean CLI (@plungeai/ocean-cli) The `ocean` CLI is a **remote client** for the PlungeAI Ocean platform. All execution happens on Cloudflare — the CLI talks HTTPS to three surfaces: | Surface | Host | Credential | |---|---|---| | Studio API (flows, runs, results, schedules, registry, AI chat) | https://studio.plungeai.com | Studio session cookie | | Gateway (ad-hoc YAML execution) | https://api.plungeai.com | API key `ozk_YOUR_KEY` | | MCP platform verbs (whoami, memory, missions, agents, async runs) | https://mcp.plungeai.com/v1 | API key `ozk_YOUR_KEY` (Bearer) | There is no local execution mode. Nothing to run locally except the CLI itself (the optional local-node daemon is separate — `ocean local status`). ## Install Current truth (per `cli/README.md`): the npm package is **not yet published** — the publish is an owner action (tag `ocean-cli-v2.3.0`). ```bash # Working today — from the Ocean-Platform repo root: npm run ocean -- --help # run any command npm link # or: put the `ocean` bin on your PATH # Once published to npm: npm install -g @plungeai/ocean-cli # or: npx @plungeai/ocean-cli ``` Requires Node >= 20. `ocean --version` prints the CLI version (plus platform version when run inside the repo). Full install/config detail: `references/auth-and-setup.md`. ## Auth quick start Two independent credentials — the CLI never mixes them (session cookie goes only to Studio; API key only to Gateway/MCP): ```bash ocean auth set-key # hidden prompt — API key (ozk_YOUR_KEY), scripting/agent verbs ocean auth set-session # hidden prompt — Studio auth-session cookie, Studio features ocean login # prints the full cloud auth guide (where to get both) ocean auth status # what's configured ocean doctor # verify every configured credential live (exit 1 on failure) ``` - **Studio session** unlocks: AI chat/REPL, saved flows, runs, results, schedules, registry. Get it: sign in at https://studio.plungeai.com, copy the `auth-session` cookie value. - **API key** (`ozk_YOUR_KEY`) unlocks: `workflow run-yaml`, `workflow run --async`, `whoami`, `memory`, `templates`, `learn`, `mission`, `agent …`. Self-service: **Dashboard → One API → Keys** (`https://dashboard.plungeai.com`) → create → copy it once. - CI/scripts: `OCEAN_API_KEY` env var overrides the config key for the process — but any command that saves CLI state (`workflow run`/`run --async`, `refine`, `chat`, `ocean run`, `observatory run`) writes the merged config back and PERSISTS the env key into `~/.ocean/config.json` (0600). On shared runners use a throwaway `HOME` (`export HOME=$(mktemp -d)`) or finish with `ocean logout`; `whoami`, `doctor`, `run-yaml`, `agent run`, `memory`, `mission` never save. Full detail: `references/auth-and-setup.md`. ## Command overview `ocean` with no arguments opens the AI chat REPL. Everything else is noun-grouped subcommands (details + all flags: `references/commands.md`): | Command | Purpose | Needs | |---|---|---| | `ocean` / `ocean chat` | AI terminal — plain-language flow builder + agentic chat | session | | `ocean setup [--dry-run]` | Install skills for Claude Code/Cursor + custom-command dir | — | | `ocean login` / `logout` / `auth …` | Credential management | — | | `ocean doctor` | Live connectivity + auth checks | — | | `ocean run ["prompt"]` | One-shot AI prompt (`--json`, `-c` continue) or interactive run | session | | `ocean menu` | Pick-a-flow list UI (non-AI) | session | | `ocean shell` | Command shell — subcommands at an `ocean›` prompt | session or key (TTY required) | | `ocean workflow …` | list · show · build · create · update · edit · delete · refine · versions · restore · undo · followup · run · run-yaml | session (`run --async`: key · run-yaml: key preferred, session fallback) | | `ocean execution …` | list · status · show · output · conversation · continue · export · versions · save-version · restore-version | session (status/output: key fallback) | | `ocean observatory run ` | Run with live event timeline | session | | `ocean schedule …` | overview · jobs · runs · create · get · update · delete | session | | `ocean registry …` | Browse/search platform registry (agents, skills, mcp, models, …) | session | | `ocean session …` | list · export — Think chat sessions | session | | `ocean whoami` | Identity, tier, rate window | key | | `ocean memory …` | recall · remember · search-runs (long-term memory) | key | | `ocean templates …` | list · show · use workflow templates | key | | `ocean learn ` | Distill URL/text into a private skill | key | | `ocean mission ""` | Bounded autonomous agent run with memory | key | | `ocean agent …` | run · contract · call — one registry agent as a tool | key | | `ocean local status` | Local node daemon health | — | ## Common flows **Run a saved flow and read the result:** ```bash ocean workflow list --search "market" --json # find the id ocean workflow run -i "AI startups" # live SSE stream + result ``` **Async run from a script (API key path):** ```bash ocean workflow run --async -i "ping" # execution id immediately (only -i works with --async) ocean execution status # poll — bounded CI skeleton: references/agent-flows.md ocean execution output # result markdown ``` Key-only sessions get exactly `workflow run --async`, `run-yaml`, `execution status`, `execution output` on the execution surface. `execution list/show/conversation/continue/ export` and `workflow followup` need the Studio cookie — there is no key-side continue or export. **Ad-hoc YAML without saving (API key):** ```bash ocean workflow run-yaml flow.yaml -i "input text" ``` **Create → refine → run lifecycle:** ```bash ocean workflow create "My Flow" flow.yaml --kind workflow # validated + policy-linted ocean workflow refine "add a summary step" # AI one-shot edit ocean workflow undo # restore pre-refine snapshot ``` **Schedule a daily agent job with Slack delivery:** ```bash ocean schedule create "Daily brief" --type agent --target \ --prompt "summarize AI news" --cron "0 9 * * 1-5" --deliver slack:CHANNEL_ID ocean schedule update --cron "0 8 * * 1-5" # delivery settings preserved ``` **Everything above also works conversationally:** run `ocean`, then ask in plain language or use slash commands (`/run`, `/results`, `/schedule jobs`, …). REPL guide: `references/agent-flows.md`. ## Discovery first — never hardcode catalogs Agent ids, models, skills, and templates change. Always discover live: - `ocean registry agents` (also: `twins experts skills plugins mcp models providers connectors`) — browse categories - `ocean registry lookup ` — one entry's card - `ocean agent contract ` — live operations, params, credential status - `ocean workflow list` / `--kind bot` / `--search ` — your saved flows - `ocean templates list` — starter templates - In the REPL: `/registry`, `/flows`, `/agent contract ` All `ocean registry …` commands need the Studio session, and category browse is TTY-only — scripts use `ocean registry lookup ` (plain list, up to 20 matches). With only an API key there is no CLI verb that lists agents: discover via the One API (`curl -sH "X-API-Key: $OCEAN_API_KEY" 'https://api.plungeai.com/v1/discovery/search?q=&limit=5'` — see `plungeai-api-setup`) or the MCP `plungeai_list_agents` tool (`plungeai-mcp-setup`), then feed the id to `ocean agent contract` / `ocean agent run`. ## Hard rules - **API keys never in files or argv.** Enter via the hidden prompt (`ocean auth set-key`) or `OCEAN_API_KEY` env in CI. Never commit or echo a key. `auth set-key`/`set-session` take no positional value (a pasted secret errors with "too many arguments") — but nothing else scans argv, and argv IS sent to the platform as `user_request` on every key-side verb, so never place a secret in any command argument. Keys live in `~/.ocean/config.json` (mode 0600) only. - **Session cookie is a secret too** — same handling. - **Relay server output verbatim.** MCP-verb output (`whoami`, `memory`, `mission`, `agent run`, …) is final platform-rendered markdown — print it as-is, don't re-summarize. - **Schedule updates preserve delivery.** `ocean schedule update` does fresh-GET → merge → PUT; passing `--deliver` REPLACES delivery targets. Never hand-PUT a schedule with partial `parameters`. - **Bot policy lint runs at save.** `memory_owner:` is refused; hardcoded emails/UUIDs warn; `--kind bot` requires exactly one `type: harness` task whose mission ends with `task_complete`. - **Workflow YAML authoring** is its own skill — use `plungeai-workflows` for writing CNL YAML; this skill covers running it from the terminal. ## Verify After install or auth changes, always: ```bash ocean doctor # exit code 0 = ready ``` Green checks (each only when the matching credential is set): Config · Auth · Studio reachable · Workflows API (session) · Gateway api.plungeai.com reachable · Gateway API key valid · MCP authenticated. Any ✗ names the fix (`ocean login`, `ocean auth set-key`). For a scripted probe: `ocean whoami --json` (key) or `ocean workflow list --limit 1 --json` (session). ## References | File | Read when | |---|---| | `references/commands.md` | Full command reference — every command, subcommand, flag, example | | `references/auth-and-setup.md` | Install, config file, credentials, doctor, setup, troubleshooting | | `references/agent-flows.md` | Running agents/workflows, executions & results, REPL, scripting/CI patterns | ## Related skills - `plungeai-api-setup` — raw HTTP calls to `api.plungeai.com` (what `run-yaml`/`--async` use under the hood). - `plungeai-mcp-setup` — the `plungeai_*` tools the key-side CLI verbs call. - `plungeai-workflows` — CNL YAML authoring (write it here, run it with `run-yaml`). - `choose-your-plungeai-door` — deciding whether the CLI is the right door at all.