> ## 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 — flows an agent runs end to end

> Skill: plungeai-cli-setup. Replace <…> with real values; confirm any flag with ocean-cli <noun> <verb> --help.


<!-- sources-of-truth: apps/ocean-cli/src/commands/workflows.ts apps/ocean-cli/src/commands/executions.ts apps/ocean-cli/src/commands/missions.ts -->

Skill: `plungeai-cli-setup`. Replace `<…>` with real values; confirm any flag with `ocean-cli <noun> <verb> --help`.

## Create, validate, save, run

```bash
ocean-cli workflows build --goal "watch AI funding news and email me daily" --json   # the platform drafts the YAML
# save the returned YAML to flow.yaml, then:
ocean-cli workflows validate flow.yaml                  # CNL schema + save-time policy lint, runs locally
ocean-cli workflows create "AI funding watch" flow.yaml --json    # prints the workflow id
ocean-cli workflows run <workflow_id> -i "AI startups" --json     # waits for the result
```

Change a saved workflow: `ocean-cli workflows build --workflow-id <id> --instruction "add a summary step" --json`, validate
the new YAML, then `ocean-cli workflows update <id> -f flow.yaml`. History: `workflows versions <id>`,
`workflows save-version <id> --label "<why>"`, `workflows restore <id> <version_id> --yes`.

## Run without waiting, then poll

```bash
ocean-cli workflows run <workflow_id> -i "<input>" --no-wait --json       # prints execution_id
ocean-cli executions poll <execution_id> --timeout 900 --json            # waits, then prints the result
ocean-cli executions output <execution_id>                               # the platform markdown
ocean-cli executions conversation <execution_id> --json                  # the full thread
```

`workflows run <file.yaml>` runs a YAML file inline, without saving it. A paused run (a question or an approval) shows up in
`ocean-cli executions status <id>`; answer with `executions continue <id> --message "…"` or `--approve`. A running run takes
`executions steer <id> "<text>"` at its next turn.

## Bounded mission (`type: harness`)

```bash
ocean-cli missions run "<goal>" --tools web_search,web_fetch,task_complete --max-iterations 5 --no-wait --json
ocean-cli missions poll <id> --timeout 600 -o mission.json --json       # saves the result file
ocean-cli executions output <id>
```

`missions run … --sync` answers on one connection instead of start + poll. Results are saved under `./ocean-missions/<id>.json`
unless `-o` says otherwise; an existing file is never overwritten without `--force`.

## CI

Set `OCEAN_API_KEY` from a repository secret (never echo it), run the verb with `--json`, and let the exit code decide the job:
0 ok, 2 bad input, 3 auth, 4 API/refused/not ready, 5 timeout.