Skip to main content
Tuireel provides a command-line interface for initializing configs, validating them, recording sessions, previewing steps, and re-compositing recordings. 
tuireel [command] [options]
Global options:
FlagDescription
-V, --versionPrint the version number
-h, --helpDisplay help for a command

​
init

Create a starter .tuireel.jsonc config file with JSON Schema support. 
tuireel init [options]
FlagDescriptionDefault
-o, --output <path>Output config file path.tuireel.jsonc
-f, --forceOverwrite an existing config filefalse
In TTY mode, init prompts you to select a preset: 
Choose a preset (optional):
  1. polished  - catppuccin + sound + cursor + HUD
  2. minimal   - tokyo-night + cursor only
  3. demo      - dracula + sound + cursor + HUD
  4. silent    - no overlays, no sound
  5. none      - start from scratch
In non-interactive mode (piped input), the preset prompt is skipped. Examples: 
# Create default config
tuireel init

# Create config at a custom path
tuireel init -o my-demo.jsonc

# Overwrite existing config
tuireel init --force

​
validate

Validate a config file against the Tuireel schema. Reports errors with line and column numbers. 
tuireel validate [configPath]
ArgumentDescriptionDefault
configPathPath to the config file.tuireel.jsonc
Exits with code 0 on success, 1 on validation failure. Examples: 
# Validate default config
tuireel validate

# Validate a specific config
tuireel validate my-demo.jsonc
Output on success: 
✓ Config is valid: .tuireel.jsonc
Output on failure: 
✗ steps.0.type: Invalid discriminator value. Expected 'launch' | 'type' | ...

​
record

Record a TUI session to video. Spawns a PTY, executes all steps, captures frames, and encodes the output. 
tuireel record [configPath] [options]
ArgumentDescriptionDefault
configPathPath to the config file.tuireel.jsonc
FlagDescription
--format <format>Override output format (mp4, webm, gif)
-w, --watchWatch config file and re-record on changes
--verboseShow step-by-step progress and recording stats
--debugShow ffmpeg commands and internal timing details
When a format is selected (via --format or config format), Tuireel normalizes the output filename extension to match the selected format:
  • If the output path has no extension, it appends .<format>.
  • If the output path already has an extension, it replaces the last extension with .<format>.
Example: if your config sets output: smoke-output.mp4, then tuireel record --format webm writes smoke-output.webm. When using a multi-video config, all videos are recorded sequentially with progress indicators. Examples: 
# Record with default config
tuireel record

# Record a specific config
tuireel record my-demo.jsonc

# Record as GIF instead of MP4
tuireel record --format gif

# Watch mode — re-records on config changes
tuireel record -w

# Verbose output for troubleshooting
tuireel record --verbose

# Debug output showing ffmpeg internals
tuireel record --debug

​
preview

Run the scripted steps in a visible terminal without recording video. Useful for testing and debugging your step sequence before committing to a full recording. 
tuireel preview [config] [options]
ArgumentDescriptionDefault
configPath to the config file.tuireel.jsonc
FlagDescription
--verboseShow step-by-step progress and stats
--debugShow internal timing details
Examples: 
# Preview default config
tuireel preview

# Preview a specific config
tuireel preview my-demo.jsonc

# Preview with verbose output
tuireel preview --verbose

​
composite

Re-composite overlays (cursor, HUD, sound) onto an existing raw recording without re-recording the terminal session. Requires a prior tuireel record run (uses raw video and timeline data from .tuireel/). 
tuireel composite [configPath] [options]
ArgumentDescriptionDefault
configPathPath to the config file.tuireel.jsonc
FlagDescription
-c, --config <path>Config file path (overrides positional argument)
--format <format>Override output format (mp4, webm, gif)
--cursor-size <n>Cursor size in pixels
--no-cursorDisable cursor overlay
--no-hudDisable keystroke HUD overlay
--verboseShow step-by-step progress and stats
--debugShow ffmpeg commands and internal timing
Like record, selecting a format (via --format or config format) normalizes the composited output filename extension to match the selected format. Examples: 
# Re-composite with current config settings
tuireel composite

# Change format without re-recording
tuireel composite --format gif

# Re-composite without cursor or HUD
tuireel composite --no-cursor --no-hud

# Adjust cursor size
tuireel composite --cursor-size 24