SuperAPI AI Directory

flow-cli

General & other

View repository

Updated 10-16 07:16

About this skill

Flow CLI

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 --server or FLOW_SERVER_URL.
  • To initialize a repo, prefer flow init --repo ., then author .flow/workflows/*.yaml directly.
  • When you are not already in the target repo, use --repo PATH instead of relying on cwd tricks.
  • After workflow edits, run flow validate. Use --schema-only only when the user explicitly wants structural validation without local readiness checks.
  • Remember the two validation layers: --schema-only validates workflow YAML structurally, while plain flow validate also checks local runtime readiness.
  • If flow validate says no workflow YAML files exist yet, steer the user to flow 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, and flow execution changes.
  • For execution run, execution resume, execution action run, and execution watch, ensure a persistent runtime exists with flow start --repo PATH unless 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, and execution action run surface missing-input requirements instead of inventing separate input-discovery commands.
  • Native chat is outside the CLI surface. Use the web /chat route or the runtime /api/v1/chat/* API for native chat threads.
  • Do not foreground start --open, status --all, adapters, or --version in 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.md plus the docs/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.md plus the docs/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.