CLI overview

The democraft CLI keeps the common workflow short and preserves direct artifact controls for CI and debugging.

Usage

Install the CLI and authoring API in your project. npm links the local democraft executable, so npx uses the installed version:

npm install --save-dev @democraft/cli@beta @democraft/core@beta
npx democraft studio demo.ts

The CLI installs @democraft/studio as an internal dependency. The command starts its production build directly through Node; pnpm and a Democraft source checkout are not required. With pnpm or Bun, use pnpm exec democraft or bunx democraft.

The demo path is optional when the project contains exactly one conventional module: demo.ts, demo.tsx, src/demo.ts, or src/demo.tsx.

npx democraft studio
npx democraft validate
npx democraft render -o demo.mp4

If more than one conventional module exists, pass the path explicitly. The CLI never chooses an ambiguous demo silently.

Commands

Command	Purpose
`studio`	Capture and open the interactive Studio.
`render`	Validate, capture, resolve the timeline, and render an MP4.
`validate`	Run static validation without opening a browser.
`inspect`	Compile a demo and print readable inspection output.
`capture`	Validate and create reusable browser artifacts.
`auth create\|list\|login\|validate\|rename\|remove`	Manage reusable local authentication profiles.
`targets`	List target contracts used by a demo.
`timeline`	Resolve a timeline from an explicit capture manifest.
`discover`	Map a live page into a semantic Page Discovery JSON (read-only).
`doctor`	Check the environment is ready to author, capture, and discover.
`preview`	(Deprecated) Write a standalone HTML preview.

Common workflows

npx democraft studio demo.ts

Studio captures when needed and provides preview, timeline editing, and rendering in one UI.

Options

Option	Effect
`-o, --output <path>`	Write the generated artifact to a chosen path.
`--json`	Print structured output for supported inspection commands.
`--headed` / `--headless`	Show or hide the browser during capture.
`--output-dir <path>`	Use an explicit capture directory.
`--fps <number>`	Override timeline frames per second.
`--scale <number>`	Set render scale (default 1).
`--crf <number>`	Set h264 quality (default 15, lower is better).
`--port <number>`	Set the Studio port (default 3000).
`--no-capture`	Studio only: require a compatible existing capture.

--output-file remains available as a backward-compatible alias for --output.

Authentication commands

Authentication commands manage local browser sessions separately from demo source. Add --json for stable, redacted results intended for automation and coding agents.

npx democraft auth create --name "Demo admin" --origin https://app.example.com \
  --validation-url /dashboard --selector '[data-testid="user-menu"]'
npx democraft auth login <profile-id>
npx democraft auth validate <profile-id> --json
npx democraft auth list --json

See authentication profiles for Studio association, expiry and renewal, security guarantees, semantic exit codes, and CI limits.

Advanced artifact mode

Use explicit artifacts when a CI job separates capture, timeline resolution, and rendering:

npx democraft capture demo.ts
npx democraft timeline demo.ts \
  --manifest .democraft/runs/example/manifest.json \
  --output timeline.json
npx democraft render demo.ts \
  --manifest .democraft/runs/example/manifest.json \
  --timeline timeline.json \
  -o demo.mp4

--manifest and --timeline must be provided together for artifact rendering. --entry remains an advanced Remotion entry override; normal visual components are loaded from demo.ts automatically.

Unknown options, missing option values, extra positional arguments, and ambiguous demo modules fail before capture or rendering starts. Use democraft render --help for command-specific guidance.