plungeai-cli-setup

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-<tool>).

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

The ocean CLI is a remote client for the PlungeAI Ocean platform. All execution happens on Cloudflare — the CLI talks HTTPS to three surfaces:

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

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

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 (opens in a new tab), 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):

Common flows

Run a saved flow and read the result:

ocean workflow list --search "market" --json   # find the id
ocean workflow run <id> -i "AI startups"       # live SSE stream + result

Async run from a script (API key path):

ocean workflow run <id> --async -i "ping"      # execution id immediately (only -i works with --async)
ocean execution status <exec-id>               # poll — bounded CI skeleton: references/agent-flows.md
ocean execution output <exec-id>               # 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):

ocean workflow run-yaml flow.yaml -i "input text"

Create → refine → run lifecycle:

ocean workflow create "My Flow" flow.yaml --kind workflow   # validated + policy-linted
ocean workflow refine <id> "add a summary step"             # AI one-shot edit
ocean workflow undo                                         # restore pre-refine snapshot

Schedule a daily agent job with Slack delivery:

ocean schedule create "Daily brief" --type agent --target <agent-id> \
  --prompt "summarize AI news" --cron "0 9 * * 1-5" --deliver slack:CHANNEL_ID
ocean schedule update <job-id> --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 <id-or-name> — one entry's card
• ocean agent contract <agent-id> — live operations, params, credential status
• ocean workflow list / --kind bot / --search <q> — your saved flows
• ocean templates list — starter templates
• In the REPL: /registry, /flows, /agent contract <id>

All ocean registry … commands need the Studio session, and category browse is TTY-only — scripts use ocean registry lookup <query> (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=<capability>&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:

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

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.

Reference pages