Repository navigation
CLI Reference
Every demoflow command, flag, exit code, error code and environment variable, as built on develop. For walkthroughs, see Running Demos, Recording Scenarios and MCP Server.
The CLI is the npm package demoflow. Run it with npx demoflow <command>, or install it and call demoflow directly (see Installing). It needs Node.js 20 or newer.
demoflow [--version] [--help] <command>
validate <scenario> Check a scenario against the schema
run <scenario> Run a scenario and render its video
record [name] Record a scenario by using the app in a browser
setup Install Chromium now instead of on the first run
mcp Serve demo generation to MCP clients over stdio
Note
The npm release 0.1.0 has validate, run, setup and mcp. record, the press step and starting the app from devCommand are on develop and arrive in the next npm release after 0.1.0.
flowchart TD
CLI["demoflow"] --> V["validate"]
CLI --> R["run"]
CLI --> REC["record"]
CLI --> S["setup"]
CLI --> M["mcp"]
REC -- "Run it now?" --> R
M -- "one child process per task" --> R
R -- "first use" --> CH["Chromium install"]
REC -- "first use" --> CH
S --> CH
- Commands that need a project (
run,record) finddemoflow.config.json:-
runwalks up from the scenario file -
recordwalks up from the current directory
-
- Input problems are reported as
<code>: <message>, followed by one line per issue path. They exit with2. - A command-line usage error (unknown flag, missing argument) also exits with
2. - Progress and warnings go to stderr. stdout carries only the command's result: the summary,
--json, or the MCP protocol.
Schema check only; no browser, no project config.
| Argument | Meaning |
|---|---|
<scenario> |
Path to a .demo.json file. |
-
Valid: prints
<file> is valid, prints warnings (such as acsslocator) on stderr, and exits0. -
Invalid: exits
2.
Runs the scenario in Chromium, verifies it and renders the video. See Running Demos.
| Flag | Meaning |
|---|---|
--base-url <url> |
Override baseUrl from demoflow.config.json. A baseUrl in the scenario itself still wins. |
--out <dir> |
Artifacts directory: the home of runs/. Overrides every other home setting. |
--headed |
Show the browser window. |
--json |
Print the final result.json plus runDir as one JSON object on stdout. |
--run-id and --project exist but are hidden. They are internal, used by the MCP server.
Opens your app in a headed browser with a recording panel and writes demoflow/<name>.demo.json. See Recording Scenarios.
| Argument / flag | Default | Meaning |
|---|---|---|
[name] |
recording |
The scenario name. The file is demoflow/<slug>.demo.json, where the slug is the name in lowercase with every run of other characters turned into - (My Flow → my-flow). |
--force |
off | Overwrite an existing scenario file. |
--no-run |
off | Do not offer to run the scenario after saving it. |
--viewport <WxH> |
1280x720 |
The browser viewport, written into the scenario. |
After saving, record asks Run it now? [Y/n], but only in an interactive terminal. Otherwise it prints the demoflow run … command to use.
Installs Chromium now, through Playwright's installer, with progress on stderr. run and record do the same on first use, printing Chromium is not installed: downloading it once (~250 MB). If the install fails, the command exits 3 and suggests demoflow setup.
Starts a local MCP server on stdio. Register it with Claude Code:
claude mcp add demoflow -- npx demoflow mcpThe tools it offers are listed in MCP Server.
Exit codes:
| Code | Meaning |
|---|---|
0 |
Success; a run completed, with or without warnings. |
1 |
A run's execution or verification failed. |
2 |
Invalid input: usage, config, scenario, run id, or readiness. Readiness covers a disallowed origin, a missing base URL or secret, and an app that never answered in run. |
3 |
Recording, rendering or storage failed, Chromium could not be installed, an unexpected error, or the app never answered in record. |
130 |
run was interrupted (SIGINT). |
143 |
run was terminated (SIGTERM). |
Error codes:
| Code | Command | Means |
|---|---|---|
no-project-config |
run, record | No demoflow.config.json found. |
invalid-config |
run, record |
demoflow.config.json does not match the schema. |
invalid-global-config |
run | The global config.json is invalid. |
scenario-unreadable |
validate, run | The file cannot be read or is not JSON. |
invalid-scenario |
validate, run | The scenario does not match the schema. |
invalid-run-id |
run |
--run-id is not a plain directory name, or that run already exists. |
origin-not-allowed |
run | A step navigates outside allowedOrigins (readiness). |
missing-base-url |
run | A relative navigate with no base URL (readiness). |
missing-env |
run | A valueFrom.env variable is unset or empty (readiness). |
app-not-ready |
record |
devCommand did not start the app, or readyUrl never answered. |
invalid-name |
record | The scenario name has no letters or digits. |
invalid-viewport |
record |
--viewport is not WxH such as 1280x720. |
scenario-exists |
record | The file exists and --force was not given. |
invalid-recording |
record | The recorded steps do not form a valid scenario. |
nothing-recorded |
record | The session ended with no steps. |
Environment variables:
| Variable | Read by | Effect |
|---|---|---|
DEMOFLOW_HOME |
run, MCP | Home for runs/, after --out and before artifactsDir. |
XDG_DATA_HOME, LOCALAPPDATA
|
run, MCP | Default home location on Linux / Windows. |
XDG_CONFIG_HOME, APPDATA
|
run | Global config location on Linux / Windows. |
PLAYWRIGHT_BROWSERS_PATH |
Playwright | Where Chromium is installed and looked up. |
any valueFrom.env name |
run | Secret values for masked fill steps. |
The default paths are listed in Run Artifacts.
- Commands outside those listed above are not built. That includes
login,runner,projectanddemofrom the product vision; see Status and Roadmap. - No command reads secrets from a file or a flag; they come from the environment only.
- Inside the DemoFlow monorepo itself,
npx demoflowresolves to the private workspace package (issue #105). Run it from outside the repository.
- Running Demos
- Recording Scenarios
- MCP Server
- Run Artifacts
- Installing
- Spec 5,
demoflow run: docs/specs/5-cli-run.md - Spec 75, npm release: docs/specs/75-npm-release.md
- Spec 79,
demoflow record: docs/specs/79-demoflow-record.md - Spec 90,
runstarts the app: docs/specs/90-run-starts-app.md - Source: apps/cli/src/main.ts
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference