> ## Documentation Index
> Fetch the complete documentation index at: https://tuireel.micr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete reference for Tuireel CLI commands and flags

Tuireel provides a command-line interface for initializing configs, validating them, recording sessions, previewing steps, and re-compositing recordings.

```bash theme={null}
tuireel [command] [options]
```

Global options:

| Flag            | Description                |
| --------------- | -------------------------- |
| `-V, --version` | Print the version number   |
| `-h, --help`    | Display help for a command |

## init

Create a starter `.tuireel.jsonc` config file with JSON Schema support.

```bash theme={null}
tuireel init [options]
```

| Flag                  | Description                       | Default          |
| --------------------- | --------------------------------- | ---------------- |
| `-o, --output <path>` | Output config file path           | `.tuireel.jsonc` |
| `-f, --force`         | Overwrite an existing config file | `false`          |

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:**

```bash theme={null}
# 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.

```bash theme={null}
tuireel validate [configPath]
```

| Argument     | Description             | Default          |
| ------------ | ----------------------- | ---------------- |
| `configPath` | Path to the config file | `.tuireel.jsonc` |

Exits with code `0` on success, `1` on validation failure.

**Examples:**

```bash theme={null}
# 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.

```bash theme={null}
tuireel record [configPath] [options]
```

| Argument     | Description             | Default          |
| ------------ | ----------------------- | ---------------- |
| `configPath` | Path to the config file | `.tuireel.jsonc` |

| Flag                | Description                                      |
| ------------------- | ------------------------------------------------ |
| `--format <format>` | Override output format (`mp4`, `webm`, `gif`)    |
| `-w, --watch`       | Watch config file and re-record on changes       |
| `--verbose`         | Show step-by-step progress and recording stats   |
| `--debug`           | Show 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:**

```bash theme={null}
# 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.

```bash theme={null}
tuireel preview [config] [options]
```

| Argument | Description             | Default          |
| -------- | ----------------------- | ---------------- |
| `config` | Path to the config file | `.tuireel.jsonc` |

| Flag        | Description                          |
| ----------- | ------------------------------------ |
| `--verbose` | Show step-by-step progress and stats |
| `--debug`   | Show internal timing details         |

**Examples:**

```bash theme={null}
# 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/`).

```bash theme={null}
tuireel composite [configPath] [options]
```

| Argument     | Description             | Default          |
| ------------ | ----------------------- | ---------------- |
| `configPath` | Path to the config file | `.tuireel.jsonc` |

| Flag                  | Description                                      |
| --------------------- | ------------------------------------------------ |
| `-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-cursor`         | Disable cursor overlay                           |
| `--no-hud`            | Disable keystroke HUD overlay                    |
| `--verbose`           | Show step-by-step progress and stats             |
| `--debug`             | Show 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:**

```bash theme={null}
# 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
```