CLI reference
@dynamic-workflow/cli provides three commands: check (validate), compile,
run (sandbox execution).
Prerequisites
pnpm install
pnpm build # builds packages/*; CLI entry at packages/cli/dist/main.js
Below, flow stands for node packages/cli/dist/main.js.
flow check
flow check <file.flow>
Parsing + semantics + types, unified diagnostic format:
{severity} {code} {line}:{column} {message}
- No error-level diagnostics: prints
✓ <file> checks clean, exit 0 - Errors: prints the diagnostics and count, exit 1
- Info diagnostics (e.g.
external-type) don't block, but are best eliminated — declare every referenced type inside the workflow
flow compile
flow compile <file.flow> [--js] [--ir] [--out <path>]
| Flag | Output |
|---|---|
--js (default) | restricted JavaScript glue ($runtime ABI) |
--ir | Flow IR (JSON) |
--out <path> | write to file instead of stdout |
No output is produced while error-level diagnostics exist (exit 1). Artifact
shape: one async function execute_<name>($runtime, $input, $context) per
workflow plus a bottom $exports map; agent descriptors inline the full
JSON Schema, timeout in milliseconds and source spans.
flow run
flow run <file.flow> [--input '<json>' | --input-file <path>]
Executes in the sandbox (subprocess + isolate) with the FakeAgentRuntime:
output is fabricated to match the expect JSON Schema (string fields become
the constant "generated").
flow run examples/simple.flow --input '{"text": "hello"}'
FakeAgentRuntime placeholders are constants. For examples asserting
cross-item uniqueness (unique(items[*].id)), run with a single-item
input — otherwise the assertion trips over duplicated placeholders. Not a
bug: it demonstrates that contract validation really does catch bad data.
The FakeAgentRuntime ships one demo team:
engineering-team: main = lead, members = [lead, implementer, test-engineer, reviewer]
Exit codes
| Command | 0 | non-zero |
|---|---|---|
| check | no error-level diagnostics | errors present |
| compile | compiled | compile failed |
| run | success, result JSON on stdout | invalid input / runtime error (message on stderr) |
Common workflows
# validate a directory
for f in examples/*.flow; do flow check "$f"; done
# compile all examples to JS
mkdir -p examples/dist
for f in examples/*.flow; do
flow compile "$f" --out "examples/dist/$(basename "$f" .flow).js"
done
# inspect the Flow IR (debugging / learning)
flow compile examples/delivery.flow --ir | head -50