Use the flow CLI instead of hand-creating .flow, editing .gitignore manually, or guessing at runtime API calls.
Teach the reduced default story first: init, validate, start, workflows, execution run, execution resume, status, and stop. Treat start --open, status --all, adapters, and --version as secondary surfaces for browser launch, cross-repo runtime inspection, adapter catalog inspection, or install checks.
For the common local run-and-inspect loop, prefer this order and avoid exploratory detours when the workflow id is already known: flow validate . --json, flow start --repo ., flow execution run --repo . --workflow-id <workflow-id> --binding-id manual --json, flow execution show --repo . --execution-id <execution-id> --json, then flow stop --repo . --force when finished.
When execution run or execution resume already returned JSON, extract execution.id from that response and use it directly for follow-up inspection. Do not call flow workflows, flow execution list, or flow status just to rediscover a workflow id or execution id you already have.
For execution ... --json, extract only the fields you need with jq or an equivalent one-liner. Common paths are .execution.id from run/resume output and .execution.lifecycle_state from execution show output; stop polling when that lifecycle state becomes completed.
Treat this file as the thin agent-facing wrapper. The synced canonical docs are the source of truth for exact behavior and syntax.
If you are reading the authored repo copy under skills/flow-cli, the generated references/docs/ tree may not exist yet. In that case, use the canonical repo files under docs/. In the public install surface, that same content lives under references/docs/.
Working Rules
- Prefer the repo-local flow. Run the CLI from the target git repo unless the user intentionally wants
--serverorFLOW_SERVER_URL. - To initialize a repo, prefer
flow init --repo ., then author.flow/workflows/*.yamldirectly. - When you are not already in the target repo, use
--repo PATHinstead of relying on cwd tricks. - After workflow edits, run
flow validate. Use--schema-onlyonly when the user explicitly wants structural validation without local readiness checks. - Remember the two validation layers:
--schema-onlyvalidates workflow YAML structurally, while plainflow validatealso checks local runtime readiness. - If
flow validatesays no workflow YAML files exist yet, steer the user toflow init --repo .and then create a workflow YAML file directly. - For read-only inspection, prefer the CLI surfaces that already exist:
flow workflows,flow execution list,flow execution show,flow execution history,flow execution trace,flow execution transcript, andflow execution changes. - For
execution run,execution resume,execution action run, andexecution watch, ensure a persistent runtime exists withflow start --repo PATHunless the user intentionally passed an explicit server target. - Treat
Workflow <id> is not ready: ...as a readiness failure, not as a disabled workflow. Use the reported reason to tell the user what local dependency or secret is missing. - Let
execution run,execution resume, andexecution action runsurface missing-input requirements instead of inventing separate input-discovery commands. - Native chat is outside the CLI surface. Use the web
/chatroute or the runtime/api/v1/chat/*API for native chat threads. - Do not foreground
start --open,status --all,adapters, or--versionin answers unless the user explicitly needs browser launch, cross-repo runtime inspection, adapter catalog inspection, or install verification.
Local References
- Read references/docs/cli.md for the canonical CLI guide, exact syntax, installation notes, runtime lifecycle rules, and server-target resolution. In the authored repo tree, the same content lives under
docs/cli.mdplus thedocs/cli/leaf pages. - Read references/docs/workflow-authoring.md only when you need the workflow contract itself. In the authored repo tree, the same content lives under
docs/workflow-authoring.mdplus thedocs/workflow-authoring/leaf pages. - Use the checked-in example workflows under references/docs/examples/workflows only as reference material or when the user explicitly wants a workflow file.
- Use evals/evals.json and evals/README.md when improving the shipped Flow-only CLI and skill surface. These eval materials are intentionally product-local: they cover repo initialization, direct workflow authoring, validation, runtime lifecycle, manual execution, and execution inspection. Cross-product integration benchmarks such as Flow plus FactSet or browser scenarios live at the repo root under
tools/integration-evals/and are intentionally not part of this public skill tree. - For a continuable workflow example, see references/docs/examples/workflows/interactive-conversation.yaml. It uses
state.onRun.completed: waiting_for_input,pipeline.stages[].session: resume, and later turns continue through the same execution id.