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

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.

Arguments

CAST_FILE · 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:

wezterm replay recording.cast
wezterm replay ~/recordings/demo.cast

Options

--explain · 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:

wezterm replay --explain demo.cast

--explain-only · 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:

wezterm replay --explain-only demo.cast

--cat · 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:

wezterm replay --cat demo.cast

Examples

Basic replay

wezterm replay recording.cast

This plays back the recording with original timing.

Replay with explanation

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

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

wezterm replay --cat session.cast > output.txt

This dumps all the escape sequences to a file instantly.

Replay and capture

wezterm replay --cat demo.cast | less

Check recording before sharing

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:

wezterm replay my-demo.cast

Debugging Terminal Output

Understand what escape sequences are being used:

wezterm replay --explain-only debug.cast

Extracting Final State

Get the final output without waiting:

wezterm replay --cat session.cast

Learning Terminal Escapes

Study how programs use terminal features:

wezterm record -o htop.cast -- htop
# Exit htop
wezterm replay --explain-only htop.cast | less

Quality Checking

Check recordings before uploading:

for cast in *.cast; do
  echo "=== $cast ==="
  wezterm replay "$cast"
  sleep 2
done

Converting to Text

Extract plain text (with escape codes):

wezterm replay --cat session.cast > session.txt

Terminal Size Requirements

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

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.

Check recording dimensions:

head -1 recording.cast | jq '.width, .height'

File Format

Asciicast files are JSON-lines format:

Header (line 1):

{"version":2,"width":80,"height":24,"timestamp":1709143200,...}

Events (subsequent lines):

[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

wezterm replay --cat recording1.cast > output1.txt
wezterm replay --cat recording2.cast > output2.txt
diff output1.txt output2.txt

Compare timing

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

# Install agg first
cargo install agg

# Convert
agg recording.cast output.gif

Upload to asciinema.org

# If you have asciinema CLI
asciinema upload recording.cast

Embed in documentation

Use asciinema-player in HTML:

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

wezterm replay --cat recording.cast | sed 's/\x1b\[[0-9;]*m//g' > plain.txt

Tips

Speed up review

Use --cat to see everything instantly:

wezterm replay --cat quick-check.cast | less

Search for content

wezterm replay --cat logs.cast | grep ERROR

Extract specific timing

Using jq:

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

Loop playback

while true; do
  wezterm replay demo.cast
  sleep 2
done

Troubleshooting

Terminal too small

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

wezterm replay --cat small-recording.cast

Recording doesn’t play

Check file format:

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:

wezterm start -- wezterm replay recording.cast

Related

• wezterm record - Record terminal sessions
• wezterm start - Start a terminal session
• Asciicast v2 Format
• asciinema.org - Share recordings online