| name | run |
| description | Execute a bundled or project-local flowai-workflow DAG. Use to launch a workflow run from inside the host IDE. |
| argument-hint | workflow name or path (e.g. github-inbox or .flowai-workflow/<name>) |
| effort | low |
Run flowai-workflow
Execute a flowai-workflow DAG via the flowai-workflow engine binary
(plugin precondition — FR-E78). The binary itself bundles the canonical
workflows; the operator may also adapt a project-local copy under
<project-root>/.flowai-workflow/<name>/.
Preflight
Before launching, verify the engine is on PATH:
command -v flowai-workflow >/dev/null 2>&1 || { echo "Error: flowai-workflow is required — see https://github.com/korchasa/flowai-workflow#install" >&2; exit 127; }
If the binary is missing, stop and surface the install link. Do not
silently fall back to a different runtime.
Resolve the workflow
The first positional argument names the workflow. Resolve it in this
order:
- If the argument is an existing directory containing
workflow.yaml,
use it as-is.
- If the argument matches a sibling under
<project-root>/.flowai-workflow/, use the project-local copy.
- Otherwise, treat the argument as a bundled workflow name and rely on
the engine's built-in catalogue (see
flowai-workflow init --list).
- If none of the above resolves, list available workflows and ask the
user which one to run.
Launch
flowai-workflow run "<resolved-workflow-path>" [extra args]
Forward any additional CLI flags the user provides (e.g. --prompt,
--dry-run, --cycles). Stream output back to the user in normal
verbosity unless they asked for -v / -q.
Common flags
--prompt "<text>" — extra context for the PM agent
--resume <run-id> — resume a previous run
--dry-run — print the execution plan without running
-v / -s / -q — verbose / semi-verbose / quiet
--cycles <N> — repeat the run N times sequentially
Errors
- "Missing workflow.yaml" → the resolved path is wrong; list candidates
again and re-prompt.
- "Workflow validation failed" → surface the engine's error verbatim;
point the user at
scaffold to adapt the config.
- "Permission denied: …" — the engine writes under
<workflow>/runs/<run-id>/ and the per-run worktree; if the
workflow lives in a read-only location, instruct the user to first
/flowai-workflow:init into their project so runs can write into
the project-local copy.