Repository navigation
Installing
DemoFlow ships as one npm package, demoflow. It contains the CLI, the MCP server, the renderer and its fonts. It needs Node.js 20 or newer, and it fetches Chromium the first time it is needed.
| Part | Where it comes from |
|---|---|
| CLI and MCP server | the demoflow npm package (one bundled file, dist/bin/main.js) |
| Browser | Chromium, installed through the pinned Playwright the first time run or record needs it, or ahead of time with demoflow setup
|
| Video encoder |
ffmpeg on your PATH if it can encode H.264 (libx264), otherwise the bundled ffmpeg-static 5.3.0 binary |
| Fonts | Inter, shipped inside the package (SIL OFL 1.1) |
Linux, macOS and Windows are supported. CI checks the packed package on all three, on Node 20.
Note
The published version is 0.1.0. It has validate, run, setup and mcp. The following are on develop and arrive in the next release:
demoflow record- the
pressstep - starting the app from
devCommand
flowchart LR
A["npx demoflow run"] --> B{"Chromium installed?"}
B -- no --> C["download once (~250 MB)"]
B -- yes --> D["run the scenario"]
C --> D
D --> E{"ffmpeg on PATH with libx264?"}
E -- yes --> F["system ffmpeg"]
E -- no --> G["bundled ffmpeg-static"]
F --> H["render MP4"]
G --> H
- Installing the package downloads no browser.
-
First browser use: when
runorrecordstarts and Chromium is missing from where Playwright expects it, the CLI printsChromium is not installed: downloading it once (~250 MB). It then runs Playwright's own installer, with the progress on stderr. -
If that install fails, the command exits with code
3and suggestsdemoflow setupto retry. -
Choosing FFmpeg for the render:
- A system
ffmpegcounts only if it lists thelibx264encoder. Fedora'sffmpeg-free, for example, does not. - Otherwise the renderer uses the binary that
ffmpeg-staticdownloaded when the package was installed.
- A system
Run it without installing:
npx demoflow --version
npx demoflow run demoflow/customers.demo.jsonOr install it globally:
npm install -g demoflow
demoflow --helpInstall Chromium ahead of time, for example in a CI image:
npx demoflow setupsetup prints Chromium is installed: <path> (already there) or Chromium installed: <path>. It exits 3 if the installer fails.
Register the MCP server with Claude Code:
claude mcp add demoflow -- npx demoflow mcpWarning
Inside the DemoFlow monorepo, npx demoflow resolves to the private workspace package apps/cli, which is also named demoflow, not to the published one. It fails with demoflow: command not found. Run the published CLI from a directory outside the repository (#105).
| Variable | Effect |
|---|---|
PLAYWRIGHT_BROWSERS_PATH |
where Chromium is looked for and installed (Playwright's own variable) |
DEMOFLOW_HOME |
where runs are written; see Project Configuration |
-
Remove the package:
npm uninstall -g demoflow
With
npx, clear the npx cache instead. -
Remove the runs. They live in the artifacts home, which by default is the OS data directory:
OS Default artifacts home Linux $XDG_DATA_HOME/demoflow, else~/.local/share/demoflowmacOS ~/Library/Application Support/demoflowWindows %LOCALAPPDATA%\demoflow, else~\AppData\Local\demoflowIf you set
--out,DEMOFLOW_HOMEorartifactsDir, the runs are there instead. -
Remove the optional global config file:
- Linux:
~/.config/demoflow/config.json - macOS:
~/Library/Application Support/demoflow/config.json - Windows:
%APPDATA%\demoflow\config.json
- Linux:
-
Chromium lives in Playwright's browser cache and is shared with other Playwright installs. Remove it only if nothing else uses it.
- No browser at install time. Installing the package never downloads Chromium (spec 75, Decision 2).
- Chromium only. It is the only browser a scenario can use today.
-
The bundled FFmpeg can go missing. If the
ffmpeg-staticinstall script was blocked, for example by--ignore-scripts, and there is no suitable systemffmpeg, rendering fails withno FFmpeg.check_projectin the MCP Server reports this asffmpeg: missing. - Node ≥ 24 is for contributors only. Developing the monorepo itself needs Node ≥ 24 and Bun; see Contributing.
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