CLI reference

Every reelforge command and option, generated from the command definition in packages/cli/src/index.ts. On Windows run reelforge.cmd, on macOS and Linux ./reelforge, or pnpm reelforge from a source checkout. Exit codes: 0 success, 1 failure (or validation errors), 2 usage error. The command line guide explains environment variables and common workflows.

Global options

These options go before or after any command.

Option	Description	Default	Required
-V, --version	output the version number
--verbose	more output (info messages, logs)
--json	machine-readable JSON output
--root <dir>	project root (default: $REELFORGE_ROOT or the current directory)

Commands

Command	Description
reelforge studio	open the project dashboard: create episodes, upload voice, open the editor, validate and render
reelforge new	create episodes/<id>/episode.yaml from a commented template
reelforge packs	list industry packs and their templates with slots
reelforge cue	open the editor in Cues mode: mark when each line starts (writes cues.json)
reelforge align	mark cues automatically from the voice recording (lines and words; writes cues.json)
reelforge edit	open the visual editor: canvas, layers, inspector and timeline (writes episode.yaml)
reelforge dev	open the editor in Review mode: checks, safe zones, element outlines
reelforge validate	check schema, cues, timing, layout, safe zones and text overflow
reelforge render	render master + share MP4, SRT, contact sheet and publish.md
reelforge snap	write PNG frames at times (seconds or time expressions) and a contact sheet
reelforge doctor	check Node, ffmpeg, Chromium and fonts; print install steps
reelforge theme new	generate a complete themes/<name>.theme.yaml (WCAG AA contrast) from one accent color
reelforge mcp	run the Model Context Protocol server on stdio (for AI assistants and agents)
reelforge schema	write the episode JSON Schema (editor autocompletion)

reelforge studio

open the project dashboard: create episodes, upload voice, open the editor, validate and render

reelforge studio [options]

Option	Description	Default	Required
--port <port>	port (default 4310 or $REELFORGE_PORT)
--host <address>	bind address (default 127.0.0.1 or $REELFORGE_HOST); other addresses require the bearer token
--no-open	do not open the browser

reelforge new

create episodes/<id>/episode.yaml from a commented template

reelforge new [options] <id>

Argument	Description	Required
id	episode id (slug)	yes

Option	Description	Default	Required
--series <name>	series name shown in the header
--episode <n>	episode number
--lang <en|ar>	language of the template script (default en)
--pack <id>	start from an industry pack template (see reelforge packs)
--template <id>	template of the pack (default: the pack's first template)
--slot <key=value>	template slot value (repeatable); missing slots keep their defaults

reelforge packs

list industry packs and their templates with slots

reelforge packs [options]

Option	Description	Default	Required
--lang <en|ar>	language of names and slot defaults (default en)

reelforge cue

open the editor in Cues mode: mark when each line starts (writes cues.json)

reelforge cue [options] <id>

Argument	Description	Required
id	episode id or path	yes

Option	Description	Default	Required
--draft	write estimated cues instead (preview before recording)
--port <port>	port (default 4317 or $REELFORGE_PORT)
--preset <name>	override meta.preset
--no-open	do not open the browser

reelforge align

mark cues automatically from the voice recording (lines and words; writes cues.json)

reelforge align [options] [id]

Argument	Description	Required
id	episode id or path

Option	Description	Default	Required
--engine <name>	auto: whisper when installed, else dsp (one of auto, dsp, whisper)
--model <size>	whisper model size (default base) (one of tiny, base, small)
--no-vad	detect speech by energy only (skip Silero VAD)
--no-words	only line cues
--force	replace cues you marked by hand
--dry-run	print the result without writing cues.json
--setup	install the optional speech models (one time, ~180 MB in the user cache)
--status	show which speech models are installed

reelforge edit

open the visual editor: canvas, layers, inspector and timeline (writes episode.yaml)

reelforge edit [options] <id>

Argument	Description	Required
id	episode id or path	yes

Option	Description	Default	Required
--port <port>	port (default 4317 or $REELFORGE_PORT)
--preset <name>	override meta.preset
--no-open	do not open the browser

reelforge dev

open the editor in Review mode: checks, safe zones, element outlines

reelforge dev [options] <id>

Argument	Description	Required
id	episode id or path	yes

Option	Description	Default	Required
--port <port>	port (default 4317 or $REELFORGE_PORT)
--preset <name>	override meta.preset
--no-open	do not open the browser

reelforge validate

check schema, cues, timing, layout, safe zones and text overflow

reelforge validate [options] <id>

Argument	Description	Required
id	episode id or path	yes

Option	Description	Default	Required
--strict	fail on warnings too
--preset <name>	override meta.preset
--no-measure	skip the headless V-9/V-10 checks

reelforge render

render master + share MP4, SRT, contact sheet and publish.md

reelforge render [options] [id]

Argument	Description	Required
id	episode id or path (or a folder of episodes with --all)

Option	Description	Default	Required
--all	render every episode in episodes/ (or in the given folder)
--preset <name>	tiktok | reels | shorts (default: meta.preset, $REELFORGE_PRESET)
--workers <n>	parallel Chromium workers (default: CPU cores − 1, $REELFORGE_WORKERS)
--from <t>	partial render start (seconds) → <id>.part.mp4
--to <t>	partial render end (seconds)
--share-size <MB>	share file size cap (default 28, $REELFORGE_SHARE_SIZE)
--no-sfx	render without sound effects
--no-share	skip the share file
--lossless	capture PNG frames instead of JPEG
--fast	faster master/share encoding (preset medium)
--silent	allow rendering without a voice recording
--keep-tmp	keep out/.tmp/<run-id>/ on failure
--no-measure	skip the headless V-9/V-10 checks
--denoise	remove background noise from the voice (default: audio.denoise)
--no-denoise	keep the voice as recorded, even when audio.denoise is true

reelforge snap

write PNG frames at times (seconds or time expressions) and a contact sheet

reelforge snap [options] <id> [times...]

Argument	Description	Required
id	episode id or path	yes
times...	times: 12.5, 12.5s, l7, "l7:'word'", l7.end+0.2

Option	Description	Default	Required
--every <seconds>	one frame every N seconds
--out <dir>	output folder (default out/snaps)
--preset <name>	override meta.preset
--cover	write a single 1080×1920 cover image to out/<id>.cover.png

reelforge doctor

check Node, ffmpeg, Chromium and fonts; print install steps

reelforge doctor [options]

Option	Description	Default	Required
--fix	install the pinned Chromium if missing

reelforge theme new

generate a complete themes/<name>.theme.yaml (WCAG AA contrast) from one accent color

reelforge theme new [options] <name>

Argument	Description	Required
name	theme name (slug)	yes

Option	Description	Default	Required
--accent <hex>	accent color, e.g. #b8ff3c (adjusted only if it would be hard to read)		yes
--mode <mode>	light or dark background (default dark)
--font <family>	bundled font for its slot (display, mono or arabic): Space Grotesk, JetBrains Mono, Cairo, Inter, Manrope, Playfair Display, Noto Kufi Arabic, Noto Naskh Arabic, Readex Pro
--out <file>	output file

reelforge mcp

run the Model Context Protocol server on stdio (for AI assistants and agents)

reelforge mcp [options]

Option	Description	Default	Required
--toolsets <list>	only these toolsets: basic, design, render or all (default all)

reelforge schema

write the episode JSON Schema (editor autocompletion)

reelforge schema [options]

Option	Description	Default	Required
--out <file>	output file (default schema/episode.schema.json)