Repository navigation
Running Demos
demoflow run turns one scenario file into a verified demo video. It can start your app, drives Chromium through the steps, checks the assertions, and renders the recording to an MP4. demoflow validate only checks a scenario against the schema and never opens a browser.
A run is local. Everything happens on your machine, and the output goes into a run directory under the DemoFlow home (see Run Artifacts). Each run reports a status for every stage. A failed verification still renders a video, because that video is the evidence of what went wrong.
run finds the project by walking up from the scenario file to the nearest demoflow.config.json. Without that file the command stops with no-project-config.
Note
Starting the app from devCommand is on develop and is not in the npm release 0.1.0. It arrives in the next npm release after 0.1.0. With 0.1.0, start your app yourself before demoflow run.
flowchart TD
A["demoflow run file.demo.json"] --> B["Find project root<br/>(demoflow.config.json)"]
B --> C["Load config, resolve home,<br/>validate scenario"]
C --> D{"Inputs valid?"}
D -- no --> X["Exit 2"]
D -- yes --> E["Start app from devCommand<br/>+ ensure Chromium (in parallel)"]
E --> F{"App answers readyUrl?"}
F -- no --> G["result.json: readiness failed<br/>Exit 2"]
F -- yes --> H["Run steps in Chromium<br/>record source.webm"]
H --> I{"source.webm exists?"}
I -- yes --> J["Render render/ffmpeg.mp4"]
I -- no --> K["Settle result.json"]
J --> K
K --> L["Print summary or --json<br/>stop the app"]
-
Find the project.
runwalks up from the scenario file to the nearestdemoflow.config.json. That directory is the project root. -
Load the inputs. It loads and validates the project config, resolves the home directory, and loads and validates the scenario. Every
csslocator prints a warning on stderr. An invalid config or scenario stops the run here with exit code2, before a browser is downloaded or the app is started. -
Start the app. If the config has a
devCommand,runstarts it. At the same time it checks that Chromium is installed and downloads it if it is missing. IfreadyUrlalready answers, nothing is started. The app's output is kept and shown only if the start fails. -
App not ready. If the app never answers,
runwritesresult.jsonitself. Readiness isfailed, with the app's last output in the message, and every other stage isskipped. The command exits with2. -
Execute. The engine checks readiness (allowed origins, base URL, secrets). It then launches Chromium (headless unless
--headed), records the page and runs the steps in order. The first failing step stops the run. -
Render. If a source video was recorded, the renderer builds a render plan and writes
render/ffmpeg.mp4. It does this whatever the verdict was, so a failed verification still produces a video. -
Settle.
renderingandstoragechange frompendingtoskippedif nothing set them, the run status is derived again, andresult.jsonis replaced. -
Report.
runprints a short summary, or with--jsonone JSON object, and exits with a code that reflects the first failing stage. Ifrunstarted the app, it stops the app.
Check a scenario without running it:
npx demoflow validate demoflow/customers.demo.jsonIt prints <file> is valid and exits 0. Warnings, such as a css locator, go to stderr. An invalid file exits 2 and lists each issue by path.
Run a scenario:
npx demoflow run demoflow/customers.demo.jsonThe summary lists every stage with its status, the path of each rendered video, and the run directory:
Run 20261018-200548-clfwzo: completed
readiness passed
execution passed
verification passed
recording passed
rendering passed
storage skipped
Video: <home>/runs/20261018-200548-clfwzo/render/ffmpeg.mp4
Run directory: <home>/runs/20261018-200548-clfwzo
Useful flags:
# Point the run at another server for this run only
npx demoflow run demoflow/login.demo.json --base-url http://localhost:4000
# Write the run under another home directory
npx demoflow run demoflow/login.demo.json --out ./demo-artifacts
# Watch the browser while it runs
npx demoflow run demoflow/login.demo.json --headed
# Machine-readable output: the final result.json plus "runDir"
npx demoflow run demoflow/login.demo.json --jsonScenarios that fill secrets read them from the environment only:
DEMO_PASSWORD=… npx demoflow run demoflow/login.demo.jsonThe full flag list is in CLI Reference.
| Setting | Where | Effect on run
|
|---|---|---|
baseUrl |
demoflow.config.json |
Base for relative navigate paths. --base-url overrides it. |
baseUrl |
the scenario | Wins over both the config and --base-url when set. |
allowedOrigins |
demoflow.config.json |
Origins the browser may visit. Defaults to the origin of baseUrl. |
devCommand |
demoflow.config.json |
{command, args?, readyUrl, timeoutMs?}. Starts the app before the run. |
render.* |
demoflow.config.json |
Output size, fps, idle compression, frame and background. See Rendering and Effects. |
artifactsDir |
config files | Where runs go. See Run Artifacts. |
Base URL precedence. The scenario's own baseUrl is used first. Otherwise run uses --base-url if given, and then the config's baseUrl.
devCommand details:
- The command runs without a shell, with the project root as the working directory.
-
runpollsreadyUrlevery 250 ms. Any HTTP status below 500 counts as ready, including a redirect or a 404. -
timeoutMsdefaults to 60000. - When
runstarted the app, it stops the whole process tree afterwards. On Linux and macOS it sends SIGTERM to the process group, then SIGKILL after a 5 s grace period. On Windows it usestaskkill /T /F.
See Project Configuration for every key.
-
Secrets. Secrets come only from the process environment. If a
valueFrom.envvariable is missing or empty, readiness fails withmissing-env NAMEbefore any browser starts. See Secrets and Masking. -
Origins. The browser may navigate only to
allowedOrigins. Any other origin fails readiness withorigin-not-allowed. -
Stopping the app.
runnever stops an app it did not start. IfreadyUrlalready answered, your server is left running. -
Interrupts. Ctrl+C (SIGINT) and SIGTERM stop the app
runstarted and exit with130or143. -
Storage. The
storagestage is alwaysskipped. There is no cloud upload; runs stay on disk. -
Shared run directories.
--run-idis internal (the MCP server uses it). It refuses a directory that already exists, so a run never overwrites another.
-
Scenarios: what a
.demo.jsonholds -
Run Artifacts: the run directory,
result.json, exit codes - Rendering and Effects: what the video shows
- CLI Reference
- MCP Server: runs started from Claude Code
- Spec 5,
demoflow run: docs/specs/5-cli-run.md - Spec 90,
runstarts the app: docs/specs/90-run-starts-app.md - Spec 31, the process exits after a run: docs/specs/31-process-exits-after-run.md
- ADR-0003, scenario format and project config: docs/adr/0003-scenario-format-and-project-config.md
- ADR-0004, recording is separate from rendering: docs/adr/0004-recording-is-separate-from-rendering.md
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