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

# wezterm replay

> Replay recorded asciicast terminal sessions

The `replay` command plays back terminal session recordings created with `wezterm record` or other asciicast-compatible tools.

## Synopsis

```bash theme={null}
wezterm replay [OPTIONS] <CAST_FILE>
```

## Description

Replays an asciicast file in your terminal with proper timing, allowing you to review recorded terminal sessions. The replay preserves all formatting, colors, and timing information from the original recording.

Supports the [asciicast v2 format](https://github.com/asciinema/asciinema/blob/develop/doc/asciicast-v2.md).

## Arguments

<ParamField path="CAST_FILE" type="path" required>
  Path to the asciicast file to replay.

  The file should be in asciicast v2 format (typically with `.cast` or `.cast.txt` extension).

  **Example:**

  ```bash theme={null}
  wezterm replay recording.cast
  wezterm replay ~/recordings/demo.cast
  ```
</ParamField>

## Options

<ParamField path="--explain" type="flag">
  Explain what is being sent/received.

  Shows a detailed breakdown of the escape sequences and control codes in the recording, alongside the normal playback. Useful for understanding terminal behavior and debugging.

  **Example:**

  ```bash theme={null}
  wezterm replay --explain demo.cast
  ```
</ParamField>

<ParamField path="--explain-only" type="flag">
  Don't replay, just show the explanation.

  Analyzes the recording and displays all escape sequences and control codes without actually playing it back in the terminal. This is useful for detailed analysis of terminal output.

  **Conflicts with:** `--explain`

  **Example:**

  ```bash theme={null}
  wezterm replay --explain-only demo.cast
  ```
</ParamField>

<ParamField path="--cat" type="flag">
  Just emit raw escape sequences all at once, with no timing information.

  Outputs all the terminal escape sequences from the recording immediately, without pausing for timing. This is useful for quickly extracting the final state or piping to other tools.

  **Conflicts with:** `--explain`

  **Example:**

  ```bash theme={null}
  wezterm replay --cat demo.cast
  ```
</ParamField>

## Examples

### Basic replay

```bash theme={null}
wezterm replay recording.cast
```

This plays back the recording with original timing.

### Replay with explanation

```bash theme={null}
wezterm replay --explain demo.cast
```

Shows escape sequences alongside playback:

```
> SENT
  Print("Hello World\\n")
  CSI(Sgr([SetForegroundColor(Green)]))
  Print("Success\\n")
  CSI(Sgr([Reset]))
< RECV
  (Any input captured during recording)
```

### Analyze without playback

```bash theme={null}
wezterm replay --explain-only tutorial.cast
```

Shows the breakdown without actually playing:

```
> SENT
  Print("$ ")
  Print("ls -la\\n")
  Print("total 48\\ndrwxr-xr-x...")
  CSI(Sgr([SetForegroundColor(Blue)]))
  ...
```

### Extract raw output

```bash theme={null}
wezterm replay --cat session.cast > output.txt
```

This dumps all the escape sequences to a file instantly.

### Replay and capture

```bash theme={null}
wezterm replay --cat demo.cast | less
```

### Check recording before sharing

```bash theme={null}
wezterm replay --explain-only recording.cast | grep -i password
```

Search for sensitive information before sharing.

## Playback Controls

During normal replay (without `--cat`), you can:

* **Watch:** The recording plays with original timing
* **Wait:** Playback completes automatically
* **Interrupt:** Press Ctrl-C to stop playback

The terminal returns to normal after playback completes or is interrupted.

## Understanding --explain Output

The `--explain` mode shows terminal actions:

### Print Actions

```
Print("Hello World\\n")
```

Regular text output

### Control Sequences

```
CSI(Sgr([SetForegroundColor(Red)]))
```

Color changes

```
CSI(Cursor(Position { line: 5, col: 10 }))
```

Cursor movements

```
Esc(Code(ClearScreen))
```

Screen clearing

### Operating System Commands

```
OperatingSystemCommand(SetWindowTitle("My Title"))
```

Window title changes

## Use Cases

### Reviewing Recordings

Before sharing a recording:

```bash theme={null}
wezterm replay my-demo.cast
```

### Debugging Terminal Output

Understand what escape sequences are being used:

```bash theme={null}
wezterm replay --explain-only debug.cast
```

### Extracting Final State

Get the final output without waiting:

```bash theme={null}
wezterm replay --cat session.cast
```

### Learning Terminal Escapes

Study how programs use terminal features:

```bash theme={null}
wezterm record -o htop.cast -- htop
# Exit htop
wezterm replay --explain-only htop.cast | less
```

### Quality Checking

Check recordings before uploading:

```bash theme={null}
for cast in *.cast; do
  echo "=== $cast ==="
  wezterm replay "$cast"
  sleep 2
done
```

### Converting to Text

Extract plain text (with escape codes):

```bash theme={null}
wezterm replay --cat session.cast > session.txt
```

## Terminal Size Requirements

When replaying, your terminal must be at least as large as the recording:

<Warning>
  If the recording was made at 120x40 and your terminal is 80x24, replay will fail with:

  ```
  recording.cast was recorded with width=120 and height=40
  but the current screen dimensions 80x24 are too small to display it
  ```

  Resize your terminal and try again.
</Warning>

Check recording dimensions:

```bash theme={null}
head -1 recording.cast | jq '.width, .height'
```

## File Format

Asciicast files are JSON-lines format:

**Header (line 1):**

```json theme={null}
{"version":2,"width":80,"height":24,"timestamp":1709143200,...}
```

**Events (subsequent lines):**

```json theme={null}
[0.123, "o", "output data"]
[1.456, "o", "more output"]
```

Each event: `[timestamp, type, data]`

* `timestamp`: Seconds since recording start
* `type`: "o" for output, "i" for input
* `data`: The actual terminal data

## Comparing Recordings

### Extract and diff outputs

```bash theme={null}
wezterm replay --cat recording1.cast > output1.txt
wezterm replay --cat recording2.cast > output2.txt
diff output1.txt output2.txt
```

### Compare timing

```bash theme={null}
tail -1 recording1.cast | jq '.[0]'  # Last timestamp
tail -1 recording2.cast | jq '.[0]'
```

## Performance

Replay performance is generally excellent:

* **With timing:** Plays at recorded speed
* **With --cat:** Instant output
* **With --explain:** Slight overhead for parsing
* **With --explain-only:** Fast, no terminal rendering

## Integration with Other Tools

### Convert to GIF

Using `agg` (asciicast to GIF):

```bash theme={null}
# Install agg first
cargo install agg

# Convert
agg recording.cast output.gif
```

### Upload to asciinema.org

```bash theme={null}
# If you have asciinema CLI
asciinema upload recording.cast
```

### Embed in documentation

Use asciinema-player in HTML:

```html theme={null}
<script src="asciinema-player.js"></script>
<link rel="stylesheet" href="asciinema-player.css">
<div id="demo"></div>
<script>
  AsciinemaPlayer.create('recording.cast', document.getElementById('demo'));
</script>
```

### Extract to text

Remove escape sequences:

```bash theme={null}
wezterm replay --cat recording.cast | sed 's/\x1b\[[0-9;]*m//g' > plain.txt
```

## Tips

### Speed up review

Use `--cat` to see everything instantly:

```bash theme={null}
wezterm replay --cat quick-check.cast | less
```

### Search for content

```bash theme={null}
wezterm replay --cat logs.cast | grep ERROR
```

### Extract specific timing

Using `jq`:

```bash theme={null}
# Get all output between 5 and 10 seconds
tail -n +2 recording.cast | jq -r 'select(.[0] >= 5 and .[0] <= 10) | .[2]'
```

### Loop playback

```bash theme={null}
while true; do
  wezterm replay demo.cast
  sleep 2
done
```

## Troubleshooting

### Terminal too small

Resize your terminal or use `--cat` to extract without replaying:

```bash theme={null}
wezterm replay --cat small-recording.cast
```

### Recording doesn't play

Check file format:

```bash theme={null}
head -1 recording.cast | jq '.version'
```

Should output `2` for asciicast v2 format.

### Colors look wrong

The recording includes color theme information, but your terminal's theme might interfere. Try:

```bash theme={null}
wezterm start -- wezterm replay recording.cast
```

## Related

* [wezterm record](/cli/record) - Record terminal sessions
* [wezterm start](/cli/start) - Start a terminal session
* [Asciicast v2 Format](https://github.com/asciinema/asciinema/blob/develop/doc/asciicast-v2.md)
* [asciinema.org](https://asciinema.org/) - Share recordings online