Repository navigation
Run Artifacts
Every demoflow run writes a self-contained run directory: the raw recording, the timeline of what happened, the scenario that ran, a machine-readable result and the rendered video. This page covers where that directory lives, what is in it, and how its result maps to the command's exit code.
Runs live under the home directory, at <home>/runs/<runId>/. The run id is YYYYMMDD-HHmmss-<6 lowercase base32 chars> in UTC, for example 20261018-200548-clfwzo. Recording and rendering are separate steps (ADR-0004). The engine writes the source video and the timeline, and the renderer reads them back to produce the MP4. A run directory therefore holds everything needed to render that run again.
flowchart LR
E["Engine"] --> S["source.webm"]
E --> T["timeline.json"]
E --> C["scenario.json"]
E --> R["result.json"]
E --> P["screenshots/"]
S --> RN["Renderer"]
T --> RN
R --> RN
RN --> V["render/ffmpeg.mp4"]
RN -. "updates rendering stage" .-> R
-
Choose the home. The first match wins:
-
--out <dir>(relative to the current directory) - the
DEMOFLOW_HOMEenvironment variable (relative to the current directory) -
artifactsDirin the project'sdemoflow.config.json(relative to the project root) -
artifactsDirin the global config - the OS data directory
-
-
Create the run. The engine records
source.webmand collects one timeline event per executed step. Each step'sscreenshotgoes intoscreenshots/. -
Write the files. At the end of the run the capture observer writes
timeline.json,scenario.jsonandresult.json. -
Render. If
source.webmexists, the renderer writesrender/ffmpeg.mp4and records it inresult.jsonunderrenders[]. -
Settle. The CLI closes the stages it owns and replaces
result.jsonatomically. See Running Demos.
Default home (OS data directory):
| OS | Path |
|---|---|
| Linux |
$XDG_DATA_HOME/demoflow, else ~/.local/share/demoflow
|
| macOS | ~/Library/Application Support/demoflow |
| Windows |
%LOCALAPPDATA%\demoflow, else ~\AppData\Local\demoflow
|
Global config file (only artifactsDir is read from it):
| OS | Path |
|---|---|
| Linux |
$XDG_CONFIG_HOME/demoflow/config.json, else ~/.config/demoflow/config.json
|
| macOS | ~/Library/Application Support/demoflow/config.json |
| Windows | %APPDATA%\demoflow\config.json |
Run directory:
| File | Written by | Holds |
|---|---|---|
source.webm |
engine | The raw recording at the viewport size (1×, ADR-0010). |
timeline.json |
engine | One event per executed step, plus the clock sync mark. |
scenario.json |
engine | The scenario that ran. |
result.json |
engine, then CLI | Stage statuses, run status, renders, warnings. |
screenshots/ |
engine | Files from screenshot steps. |
render/ffmpeg.mp4 |
renderer | The finished video: H.264, yuv420p, faststart. |
To read a finished run from a script, use --json. It prints the final result.json with an extra runDir field.
timeline.json:
-
Top level:
schemaVersion: 1,viewport,deviceScaleFactor,videoFile,events[], and optionallysyncMark {colour, onMs, offMs}. -
Per event:
stepIndex,action,startMs,endMs, and where they apply:target.boxpointer {from, to}scroll {before, after, container?}-
masked,value assertion {passed, message?}-
key(onpressonly) screenshotmarker {title, kind}captionerror {message}-
maskVisibility(on a maskedfillonly)
- Units: times are milliseconds from the video's first frame. Boxes and points are CSS pixels of the viewport.
-
Masked fills: the value is written as
***.
result.json:
| Field | Meaning |
|---|---|
schemaVersion |
1 |
runId |
The run directory's name. |
scenarioId |
The scenario's path relative to the project root. |
scenarioName |
The scenario's name. |
startedAt, finishedAt
|
ISO timestamps. |
status |
completed, completed_with_warnings, failed or running. |
stages |
readiness, execution, verification, recording, rendering and storage. Each has a status and optional startedAt, finishedAt and error {message, stepIndex?}. |
renders[] |
{renderer, file, durationMs, sizeBytes, width, height, fps}. file is relative to the run directory. |
warnings[] |
Strings. |
-
Stage status is one of
pending,running,passed,failed,skipped. -
Run status is derived from the stages, never from whether a video exists:
- any failed stage makes the run
failed - any stage still pending or running makes it
running - otherwise it is
completed, orcompleted_with_warningswhen there are warnings
- any failed stage makes the run
A rendered video of a failed verification therefore belongs to a failed run.
Exit codes. The first failure in pipeline order decides:
| Code | When |
|---|---|
0 |
The run completed, with or without warnings. |
1 |
Execution or verification failed: a step failed, or an assertion did not hold. |
2 |
Invalid input or readiness failed: a bad config or scenario, a disallowed origin, a missing base URL or secret, or an app that never answered. |
3 |
Recording, rendering or storage failed, or a Chromium install or unexpected error occurred. |
130 / 143
|
Interrupted by SIGINT / SIGTERM. |
- Runs are never deleted or overwritten by DemoFlow. Every run gets a new directory, and an explicit
--run-idthat already exists is refused. - Nothing is uploaded.
storageis alwaysskipped, because cloud storage is not built yet. - A secret value is never written to
timeline.json,result.jsonor error messages; masked values appear as***. See Secrets and Masking. - The run directory has no index. To list runs, look in
<home>/runs/or use thelist_demostool of the MCP Server.
- Running Demos
- Rendering and Effects
-
Project Configuration:
artifactsDir - CLI Reference
- ADR-0004, recording is separate from rendering: docs/adr/0004-recording-is-separate-from-rendering.md
- ADR-0010, source video at viewport size: docs/adr/0010-source-video-at-viewport-size.md
- Spec 1, core contracts: docs/specs/1-core-contracts.md
- Spec 5,
demoflow run(exit codes): docs/specs/5-cli-run.md - Contracts in code: packages/core/src/run-result.ts, packages/core/src/timeline.ts
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