DemoFlow

CLI

Run demoflow through npx demoflow, or install it globally. demoflow --help lists the commands and demoflow <command> --help their flags.

CommandWhat it does
demoflow initWrite demoflow.config.json and a first scenario here.
demoflow record [name]Record a scenario by using the app.
demoflow validate <scenario>Check a scenario against the schema.
demoflow run <scenario>Run it in a browser and render the video.
demoflow render <runId>Render an existing run again with the current config.
demoflow listList recent runs of the current project, newest first.
demoflow runs …List, delete and prune the runs on this machine.
demoflow checkCheck that the project, FFmpeg and the browser are ready.
demoflow setupInstall Chromium now instead of on the first run.
demoflow mcpServe demo generation to MCP clients over stdio.
demoflow loginPair this machine with your DemoFlow account.
demoflow logoutRevoke this machine and delete its credentials.
demoflow runner …Keep this machine connected in the background.

init

npx demoflow init
npx demoflow init --base-url http://localhost:5173

Writes demoflow.config.json and demoflow/first.demo.json in the current folder. The scenario opens / and waits a second, so it runs green against any app that answers at baseUrl. It makes no network request and starts no browser. A file that already exists is never overwritten: it is kept and reported as kept. A config in a parent folder is not looked for.

FlagMeaning
--base-url <url>The app's base URL, written to the config. Defaults to http://localhost:3000.

It prints one created or kept line per file, then the next steps: demoflow check, demoflow run demoflow/first.demo.json and demoflow record for a real scenario.

Exit codes:

CodeMeaning
0Both files exist now, created or kept.
2--base-url is not a valid URL. Nothing is written.

run

npx demoflow run demoflow/first.demo.json
FlagMeaning
--base-url <url>Override baseUrl from demoflow.config.json. allowedOrigins follows it.
--port <n>Fill ${PORT} in the config and set PORT for the app. An integer from 1 to 65535. See Starting your app.
--fresh-appRefuse to run when readyUrl already answers, instead of reusing that app. Needs devCommand.
--out <dir>The artifacts home, which holds runs/.
--headedShow the browser window.
--jsonPrint the result as one JSON object on stdout.
--format <format>A file to render: mp4, gif, webm, mp4-vertical, gif-vertical, webm-vertical, mp4-square, gif-square or webm-square. Repeat it for several. Replaces render.formats.

--port with a config that uses no ${PORT} still sets PORT for the app, and prints a warning that baseUrl and readyUrl are unchanged.

Exit codes:

CodeMeaning
0The run completed, with or without warnings.
1A step failed or an assertion did not hold.
2The input was invalid: the scenario, the config, a missing secret, or a --port that is not a port. Also when the app was not ready, and with --fresh-app when another app already answers on readyUrl.
3Recording, rendering or storage failed.

With --fresh-app, a taken port is reported on stderr as app-already-running: --fresh-app: <readyUrl> already answers; another app holds this port. Stop it or pass another --port. Nothing is printed on stdout, even with --json, no run directory is created and the browser is not checked, so a caller can retry at once on another port.

render

npx demoflow render 20261023-101500-abcdef

Renders a finished run again from <home>/runs/<runId>/, without starting the app or the browser: a new background, a GIF after the fact, or a retry after a render crash. It uses the project's current render.* config, so a change to demoflow.config.json restyles the video. The run id is the run directory's name, the one run prints.

FlagMeaning
--out <dir>The artifacts home, which holds runs/.
--jsonPrint the result as one JSON object on stdout.
--format <format>A file to render, as for run. Repeat it for several. Replaces render.formats.

Only the rendered files and the rendering stage change. The verdict never does: a failed run stays failed and keeps its failure card. The new files replace the run's earlier ones in result.json. A file of a format this render does not write stays on disk but is no longer listed.

The website is not told: its runs list keeps the formats of the first render.

It exits 2 without writing anything when the run id is not a plain name, the run directory or its result.json is missing or invalid, the run has not finished, or it has no recording. A render that fails exits 3; otherwise the exit code is the run's, as for run.

list

npx demoflow list --limit 5

Prints the recent runs of the current project, newest first: status, start time, duration, scenario name and run id, and the run's page URL when it was reported to the website. It reads the runs under the artifacts home that run writes to. Nothing is started or written.

FlagMeaning
--limit <n>How many runs to list, 1 to 100. Defaults to 20.
--jsonPrint the runs as one { "demos": [...] } object on stdout, the same as the MCP's list_demos.

It exits 0 when it listed runs, or found none. It exits 2 when --limit is not an integer from 1 to 100, or when the folder is not in a project (no demoflow.config.json in it or above).

runs

npx demoflow runs list
npx demoflow runs delete 20261017-123456-abcdef --dry-run
npx demoflow runs prune --older-than 30d --dry-run

Every run leaves a directory under <home>/runs/, and runs that were cancelled, timed out or crashed leave partial ones. runs reclaims the space. It works outside a project too: the home comes from --out, DEMOFLOW_HOME, the project's or the global artifactsDir, or the OS data directory, and every output starts with the <home>/runs it read.

runs list prints every run, newest first: status, date, size, scenario name and run id, the page URL of a run reported to the website, and a total. A run that never finished is partial. A run with anything in it modified in the last 5 minutes is active: it may still be running, or being rendered.

runs delete <id…> deletes the runs you name, one line per id: deleted, not found, refused (active) or failed. One id's failure does not stop the others. runs prune deletes the runs that match every filter given, oldest first, and prints how much it freed.

Nothing asks for confirmation. Preview with --dry-run first. An active run is never deleted, and nothing outside <home>/runs/ is ever removed. A run the website knows stays in the project's library; its video answers as not found.

FlagMeaning
--out <dir>The artifacts home, which holds runs/. All three commands.
--jsonlist only: print { "home": …, "runs": [...] } on stdout.
--dry-rundelete and prune: print what would be deleted, delete nothing.
--older-than <duration>prune: runs started longer ago than this. A positive integer and m, h, d or w: 90m, 12h, 30d, 2w.
--partial-onlyprune: only runs that never finished.

prune needs --older-than, --partial-only or both.

CodeMeaning
0Listed; every named run deleted; or the prune removed what matched (possibly nothing).
1delete: a run was not found, active, or failed to delete. prune: a removal failed.
2An invalid run id or duration, prune without a filter, or an invalid config. Nothing is deleted.

check

npx demoflow check

Checks that a demo can run here: the project root, whether the config is valid, the scenario files (listed, not validated; use validate), FFmpeg (system, bundled or missing) and the browser (installed or missing, with a hint to run demoflow setup). It starts no browser and writes nothing.

FlagMeaning
--jsonPrint the check as one JSON object on stdout, the same as the MCP's check_project.

Exit codes:

CodeMeaning
0FFmpeg and the browser are both available.
1FFmpeg or the browser is missing, so a demo cannot run yet.
2The folder is not in a project (no demoflow.config.json in it or above).

A CI step can run demoflow check to gate on the machine being ready.

validate

demoflow validate <scenario> checks a file without running it. Nothing is started or written. It exits 0 when the file is valid and 2 when it is not, and reports each problem by its path.

record

demoflow record [name] writes demoflow/<name>.demo.json. See Recording for the flags and the panel.

setup

demoflow setup downloads Chromium ahead of time. Otherwise the first run does it.

login and logout

demoflow login prints a code and opens the website, where you approve it. It stores a revocable device token. --server <url> (or DEMOFLOW_SERVER) picks the server, --force pairs again, and --start or --no-start answer in advance whether to start the runner. demoflow logout revokes the token and deletes the file. Every other command works without an account. See Runner.

runner

demoflow runner start | stop | status | logs | install | uninstall manage the background process. Three more subcommands set which folders the website may name when you add a project from it:

npx demoflow runner roots [--json]
npx demoflow runner allow <dir>
npx demoflow runner disallow <dir>

By default only your home directory is allowed, without hidden folders. See Allowed folders.

Updates

A globally installed demoflow asks npm for the latest version while a command runs, and after the command finishes asks on stderr:

demoflow 0.3.0 is available (you have 0.2.0). Update now? [Y/n/never]

The check gives up after 1.5 seconds and never changes a command's output or exit code. It stays silent without a terminal, under CI, for mcp and the runner's long-lived modes, and under npx, bunx and pnpm dlx.

To turn it off, set the environment variable DEMOFLOW_NO_UPDATE_CHECK=1.