Skip to content
Archi edited this page Oct 18, 2026 · 1 revision

FAQ

Short answers to the questions people ask first, each linking the page with the details.

Overview

flowchart TD
  Q{"Something wrong?"} -->|"no video"| A1["Check the exit code<br/>and result.json"]
  Q -->|"command not found"| A2["Outside the monorepo?<br/>Node ≥ 20?"]
  Q -->|"secret in video?"| A3["Use valueFrom.env"]
  A1 --> CLI["CLI Reference"]
  A2 --> INS["Installing"]
  A3 --> SEC["Secrets and Masking"]
Loading

Using DemoFlow

What does DemoFlow need from my app? A URL it can reach (baseUrl in demoflow.config.json) and elements a scenario can find, preferably by role and accessible name. No SDK is needed. See Getting Started.

Do I have to write JSON by hand? No: demoflow record writes the scenario while you click through the app. It is on develop and ships in the next npm release. See Recording Scenarios.

Does it start my app? On develop, yes, when devCommand is set in the project config; if the app already answers at readyUrl, it is left alone. 0.1.0 expects the app to be running. See Project Configuration.

Where is my video? render/ffmpeg.mp4 in the run directory the summary prints — by default under the OS data directory, e.g. ~/.local/share/demoflow/runs/<runId>/ on Linux. See Run Artifacts.

Why is there a video when the run failed? On purpose: a failed run is rendered too, with a "FAILED" watermark and an end card saying which stage and step failed. See Rendering and Effects.

Can I get GIF, WebM or a vertical video? Not yet. Output is MP4 (H.264) only; the other formats are planned in Phase 4. See Status and Roadmap.

Can I turn off the window frame? Yes: "render": { "frame": { "enabled": false } } renders the page full-bleed. See Project Configuration.

Secrets and safety

How do I type a password without putting it in the file? Use "valueFrom": { "env": "DEMO_PASSWORD" } on the fill step and set the variable when you run. The value is never written to disk or logs, and the field is blurred in the video. See Secrets and Masking.

Does anything leave my machine? No. There is no account or upload today; the MCP server talks over stdio only. See Security and Access.

Can a scenario visit any site? Only the origins in allowedOrigins, which default to the origin of baseUrl. See Security and Access.

AI agents

How do I connect Claude Code? claude mcp add demoflow -- npx demoflow mcp, then ask for a demo. See MCP Server.

Can two demos run at once through MCP? No; tasks run one at a time and later ones wait in a queue. See MCP Server.

Troubleshooting

npx demoflow says "command not found" inside the DemoFlow repo. Inside the monorepo the name resolves to the private workspace package (#105). Run it from your own project. See Installing.

The first run is slow. It downloads Chromium once (about 250 MB). Run demoflow setup ahead of time to do it separately. See Installing.

The text in the video looks soft. The source is recorded at the viewport size (1×), and the frame scales the page down slightly; a larger scenario viewport gives the page more pixels. See ADR-0010.

What do the exit codes mean? 0 completed, 1 a step or assertion failed, 2 invalid input or the app was not ready, 3 recording, rendering or setup failed. See CLI Reference.

See also

Clone this wiki locally