CLI
Run demoflow through npx demoflow, or install it globally. demoflow --help lists the commands and demoflow <command> --help their flags.
| Command | What it does |
|---|---|
demoflow init | Write 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 list | List recent runs of the current project, newest first. |
demoflow runs … | List, delete and prune the runs on this machine. |
demoflow check | Check that the project, FFmpeg and the browser are ready. |
demoflow setup | Install Chromium now instead of on the first run. |
demoflow mcp | Serve demo generation to MCP clients over stdio. |
demoflow login | Pair this machine with your DemoFlow account. |
demoflow logout | Revoke 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.
| Flag | Meaning |
|---|---|
--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:
| Code | Meaning |
|---|---|
0 | Both 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
| Flag | Meaning |
|---|---|
--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-app | Refuse to run when readyUrl already answers, instead of reusing that app. Needs devCommand. |
--out <dir> | The artifacts home, which holds runs/. |
--headed | Show the browser window. |
--json | Print 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:
| Code | Meaning |
|---|---|
0 | The run completed, with or without warnings. |
1 | A step failed or an assertion did not hold. |
2 | The 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. |
3 | Recording, 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.
| Flag | Meaning |
|---|---|
--out <dir> | The artifacts home, which holds runs/. |
--json | Print 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.
| Flag | Meaning |
|---|---|
--limit <n> | How many runs to list, 1 to 100. Defaults to 20. |
--json | Print 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.
| Flag | Meaning |
|---|---|
--out <dir> | The artifacts home, which holds runs/. All three commands. |
--json | list only: print { "home": …, "runs": [...] } on stdout. |
--dry-run | delete 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-only | prune: only runs that never finished. |
prune needs --older-than, --partial-only or both.
| Code | Meaning |
|---|---|
0 | Listed; every named run deleted; or the prune removed what matched (possibly nothing). |
1 | delete: a run was not found, active, or failed to delete. prune: a removal failed. |
2 | An 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.
| Flag | Meaning |
|---|---|
--json | Print the check as one JSON object on stdout, the same as the MCP's check_project. |
Exit codes:
| Code | Meaning |
|---|---|
0 | FFmpeg and the browser are both available. |
1 | FFmpeg or the browser is missing, so a demo cannot run yet. |
2 | The 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]
- Yes installs it with the package manager that installed it:
npm install -g,bun add -g,pnpm add -goryarn global add. - never skips that version until a newer one appears.
- A project install, or one whose manager it cannot tell, prints the command instead.
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.