Skip to content

CLI Reference

Archi edited this page Oct 18, 2026 · 1 revision

CLI Reference

Every demoflow command, flag, exit code, error code and environment variable, as built on develop. For walkthroughs, see Running Demos, Recording Scenarios and MCP Server.

Overview

The CLI is the npm package demoflow. Run it with npx demoflow <command>, or install it and call demoflow directly (see Installing). It needs Node.js 20 or newer.

demoflow [--version] [--help] <command>

  validate <scenario>   Check a scenario against the schema
  run <scenario>        Run a scenario and render its video
  record [name]         Record a scenario by using the app in a browser
  setup                 Install Chromium now instead of on the first run
  mcp                   Serve demo generation to MCP clients over stdio

Note

The npm release 0.1.0 has validate, run, setup and mcp. record, the press step and starting the app from devCommand are on develop and arrive in the next npm release after 0.1.0.

How it works

flowchart TD
  CLI["demoflow"] --> V["validate"]
  CLI --> R["run"]
  CLI --> REC["record"]
  CLI --> S["setup"]
  CLI --> M["mcp"]
  REC -- "Run it now?" --> R
  M -- "one child process per task" --> R
  R -- "first use" --> CH["Chromium install"]
  REC -- "first use" --> CH
  S --> CH
Loading
  1. Commands that need a project (run, record) find demoflow.config.json:
    • run walks up from the scenario file
    • record walks up from the current directory
  2. Input problems are reported as <code>: <message>, followed by one line per issue path. They exit with 2.
  3. A command-line usage error (unknown flag, missing argument) also exits with 2.
  4. Progress and warnings go to stderr. stdout carries only the command's result: the summary, --json, or the MCP protocol.

Using it

demoflow validate <scenario>

Schema check only; no browser, no project config.

Argument Meaning
<scenario> Path to a .demo.json file.
  • Valid: prints <file> is valid, prints warnings (such as a css locator) on stderr, and exits 0.
  • Invalid: exits 2.

demoflow run <scenario>

Runs the scenario in Chromium, verifies it and renders the video. See Running Demos.

Flag Meaning
--base-url <url> Override baseUrl from demoflow.config.json. A baseUrl in the scenario itself still wins.
--out <dir> Artifacts directory: the home of runs/. Overrides every other home setting.
--headed Show the browser window.
--json Print the final result.json plus runDir as one JSON object on stdout.

--run-id and --project exist but are hidden. They are internal, used by the MCP server.

demoflow record [name]

Opens your app in a headed browser with a recording panel and writes demoflow/<name>.demo.json. See Recording Scenarios.

Argument / flag Default Meaning
[name] recording The scenario name. The file is demoflow/<slug>.demo.json, where the slug is the name in lowercase with every run of other characters turned into - (My Flow → my-flow).
--force off Overwrite an existing scenario file.
--no-run off Do not offer to run the scenario after saving it.
--viewport <WxH> 1280x720 The browser viewport, written into the scenario.

After saving, record asks Run it now? [Y/n], but only in an interactive terminal. Otherwise it prints the demoflow run … command to use.

demoflow setup

Installs Chromium now, through Playwright's installer, with progress on stderr. run and record do the same on first use, printing Chromium is not installed: downloading it once (~250 MB). If the install fails, the command exits 3 and suggests demoflow setup.

demoflow mcp

Starts a local MCP server on stdio. Register it with Claude Code:

claude mcp add demoflow -- npx demoflow mcp

The tools it offers are listed in MCP Server.

Settings

Exit codes:

Code Meaning
0 Success; a run completed, with or without warnings.
1 A run's execution or verification failed.
2 Invalid input: usage, config, scenario, run id, or readiness. Readiness covers a disallowed origin, a missing base URL or secret, and an app that never answered in run.
3 Recording, rendering or storage failed, Chromium could not be installed, an unexpected error, or the app never answered in record.
130 run was interrupted (SIGINT).
143 run was terminated (SIGTERM).

Error codes:

Code Command Means
no-project-config run, record No demoflow.config.json found.
invalid-config run, record demoflow.config.json does not match the schema.
invalid-global-config run The global config.json is invalid.
scenario-unreadable validate, run The file cannot be read or is not JSON.
invalid-scenario validate, run The scenario does not match the schema.
invalid-run-id run --run-id is not a plain directory name, or that run already exists.
origin-not-allowed run A step navigates outside allowedOrigins (readiness).
missing-base-url run A relative navigate with no base URL (readiness).
missing-env run A valueFrom.env variable is unset or empty (readiness).
app-not-ready record devCommand did not start the app, or readyUrl never answered.
invalid-name record The scenario name has no letters or digits.
invalid-viewport record --viewport is not WxH such as 1280x720.
scenario-exists record The file exists and --force was not given.
invalid-recording record The recorded steps do not form a valid scenario.
nothing-recorded record The session ended with no steps.

Environment variables:

Variable Read by Effect
DEMOFLOW_HOME run, MCP Home for runs/, after --out and before artifactsDir.
XDG_DATA_HOME, LOCALAPPDATA run, MCP Default home location on Linux / Windows.
XDG_CONFIG_HOME, APPDATA run Global config location on Linux / Windows.
PLAYWRIGHT_BROWSERS_PATH Playwright Where Chromium is installed and looked up.
any valueFrom.env name run Secret values for masked fill steps.

The default paths are listed in Run Artifacts.

Limits / what it never does

  • Commands outside those listed above are not built. That includes login, runner, project and demo from the product vision; see Status and Roadmap.
  • No command reads secrets from a file or a flag; they come from the environment only.
  • Inside the DemoFlow monorepo itself, npx demoflow resolves to the private workspace package (issue #105). Run it from outside the repository.

See also

Clone this wiki locally