The flow CLI

The CLI runs pipelines locally and nothing else.

That boundary is deliberate. Teams, projects, users and tokens, remote runs and the web UI belong to the app suite — flowwright-server and flowwright-worker — and are managed there. There is no flow login, no flow deploy, and nothing here talks to a server. The same pipeline.ts runs in both places; only the CLI is covered on these pages — the other side is Self-hosting.

Commands

Command	What it does
flow run	Run the pipeline
flow explain	Print the execution plan without running it
flow validate	Load and validate the pipeline
flow doctor	Check the environment for running pipelines
flow init	Scaffold a starter pipeline.ts
flow migrate	Scan a Jenkinsfile → suggested pipeline.ts
flow export	Print a CI wrapper config
flow list	Show recent runs
flow logs	Show logs for a run
flow backup	Snapshot the local run-history database
flow clean	Purge local run history and logs

flow help prints the same list, and it's the authoritative one — if a command appears there and not here, trust flow help.

Flags

Flag	Applies to	Meaning
-f, --file <path>	run, explain, validate, doctor, init	Pipeline file (default pipeline.ts)
-j, --concurrency <N>	run	Run up to N stages in parallel over the DAG
-w, --watch	run	Re-run on file changes
--reporter <kind>	run	pretty, ci, github, gitlab or json
--junit <path>	run	Also write a JUnit XML report
--json	run, explain	Machine-readable output
--no-history	run	Don't record this run
--no-docker	run	Run container stages on the host
--stage <id|name>	logs	Filter to one stage
--all	clean	Remove all of .flowwright/
--out <path>	migrate	Write the suggested pipeline.ts
--plugins	init	Scaffold with plugin-node
--no-color	all	Disable colored output
-h, --help	all	Show help
--version	all	Show version

A flag a command doesn't read is rejected, not ignored:

$ flow list --junit report.xml
flow list: --junit is not an option for this command

The alternative — accepting it silently — means flow list --junit report.xml exits 0 having written no report, which is worse than failing.

The full per-command matrix, and the environment variables the CLI reads, are on the CLI flags reference.

-j and the real default

-j is documented as defaulting to 1, and that's true only when your pipeline doesn't say otherwise. The precedence is: -j on the command line, then the concurrency field in pipeline({ … }), then 1. A pipeline that declares concurrency: 4 runs four-wide without any flag.

Exit codes

Code	Meaning
0	Success
1	Usage error, validation failure, or a load error
n	flow run — the exit code of the command that failed
130	Cancelled by Ctrl-C or SIGTERM

flow run propagates the failing step's own exit code rather than flattening everything to 1, so a stage that exits 2 makes flow exit 2. That's what lets flow run stand in for whatever your CI job used to call.

Running flow with no command prints usage to stderr and exits 1 — it's a usage error, the same as bare git. flow help and flow --help print to stdout and exit 0.

Color

Color is on when stdout is a TTY. It turns off when you pass --no-color, when NO_COLOR is set, or when output is piped — so redirecting to a file never captures escape codes.

Node version

FlowWright requires Node.js 24 or newer, which is what engines.node, the Docker image and the generated CI wrappers all assume.

Run history uses node:sqlite. On Node versions where that module is still behind a flag, the CLI silently re-executes itself with --experimental-sqlite for the four commands that touch history (run, list, backup, logs). It's an implementation detail that keeps older runtimes limping along, not a supported configuration — target 24.