wezterm record

Record a terminal session as an asciicast file

The record command records a terminal session as an asciicast file, which can be replayed later or shared with others.

Synopsis

wezterm record [OPTIONS] [PROG]...

Description

Records a terminal session using the asciicast v2 format. This creates a recording of all terminal output with precise timing information, which can be replayed with the wezterm replay command or other asciicast-compatible players.

The recording captures:

• All terminal output (escape sequences, colors, formatting)
• Timing information for accurate playback
• Terminal dimensions
• Environment information
• Color palette

Arguments

PROG · string[]

Start PROG instead of the default_prog defined by your WezTerm configuration.

If omitted, the default shell configured in your wezterm.lua will be used.

Example:

wezterm record -- bash -l
wezterm record -- python script.py

Options

--cwd · path

Start in the specified directory, instead of the default_cwd defined by your WezTerm configuration.

Example:

wezterm record --cwd /home/user/projects

-o, --outfile · path

Save asciicast to the specified file.

If omitted, a random file name will be created in the temp directory with the pattern wezterm-recording-*.cast.txt.

Example:

wezterm record -o my-session.cast
wezterm record -o ~/recordings/demo.cast

How It Works

1. When you run wezterm record, it starts recording immediately
2. You interact with the terminal normally
3. All output is captured with timing information
4. When you exit the shell (Ctrl-D or exit), recording stops
5. The asciicast file is saved to the specified location

Examples

Basic recording

wezterm record

This creates a recording in a temp file. The path will be displayed when you exit:

Child status: ExitStatus(unix_wait_status(0))
*** Finished recording to /tmp/wezterm-recording-a1b2c3d4.cast.txt

Record to specific file

wezterm record -o demo.cast

Record a specific program

wezterm record -o tutorial.cast -- bash

Record with specific working directory

wezterm record --cwd ~/projects/myapp -o myapp-demo.cast

Record a Python script

wezterm record -o script-output.cast -- python demo.py

Record a specific command sequence

wezterm record -o git-demo.cast -- bash -c '
  git status
  git log --oneline -5
  git diff
'

Record system diagnostics

wezterm record -o diagnostics.cast -- bash -c '
  echo "=== System Info ==="
  uname -a
  echo "=== Disk Usage ==="
  df -h
  echo "=== Memory ==="
  free -h
'

Asciicast Format

The recording is saved in asciicast v2 format, which is a JSON-lines file:

Header (first line)

{
  "version": 2,
  "width": 80,
  "height": 24,
  "timestamp": 1709143200,
  "env": {
    "TERM": "xterm-256color",
    "SHELL": "/bin/bash"
  },
  "theme": {
    "fg": "#ffffff",
    "bg": "#000000",
    "palette": "#000000:#cd0000:..."
  }
}

Event lines

[0.123, "o", "Hello World\n"]
[1.456, "o", "\u001b[32mSuccess\u001b[0m\n"]

Each event line contains:

1. Timestamp (seconds since start)
2. Event type (“o” for output)
3. Data (the actual output)

Use Cases

Creating Tutorials

Record terminal sessions for documentation:

wezterm record -o tutorial-part1.cast -- bash
# Demonstrate the commands
# Exit when done

Bug Reports

Capture terminal output for bug reports:

wezterm record -o bug-reproduction.cast
# Reproduce the bug
# Exit

Code Demos

Record demos of your CLI tools:

wezterm record -o mycli-demo.cast -- bash -c '
  mycli --help
  mycli create project
  mycli build
'

Training Materials

Create training recordings:

wezterm record -o shell-basics.cast -- bash
# Demonstrate shell commands
# Exit when done

Testing

Record test sessions for later analysis:

wezterm record -o test-run.cast -- python -m pytest

Tips

Script your recordings

For consistent recordings, use a script:

cat > recording-script.sh << 'EOF'
#!/bin/bash
set -e

# Configure prompt for clean output
export PS1='$ '

# Your commands here
echo "Step 1: Check status"
git status

echo "Step 2: Show logs"
git log --oneline -5

echo "Done!"
EOF

wezterm record -o demo.cast -- bash recording-script.sh

Control timing

Add pauses for better viewing:

wezterm record -o paced-demo.cast -- bash -c '
  echo "Starting..."
  sleep 2
  echo "Running command..."
  ls -la
  sleep 1
  echo "Done!"
'

Clean output

Set a simple prompt for cleaner recordings:

wezterm record -o clean-demo.cast -- bash --noprofile --norc -c '
  export PS1="$ "
  ls
  pwd
'

Combine with replay

Test your recording immediately:

wezterm record -o test.cast -- bash
# Do your recording
# Exit
wezterm replay test.cast

Sharing Recordings

Asciicast files can be:

1. Replayed locally:

   wezterm replay recording.cast
   

2. Uploaded to asciinema.org:

   # If you have asciinema installed
   asciinema upload recording.cast
   

3. Embedded in documentation: Use asciinema-player to embed in web pages

4. Converted to GIF: Use tools like agg or asciicast2gif

5. Shared as files: The .cast files are plain text and can be committed to git

File Size Considerations

Asciicast files are text-based and usually quite small:

• Short sessions: 1-10 KB
• Medium sessions: 10-100 KB
• Long sessions: 100 KB - 1 MB

The file size depends on:

• Duration of recording
• Amount of output
• Complexity of output (colors, formatting)

Privacy Note

Recordings capture all terminal output. Be careful not to record:

• Passwords or API keys
• Sensitive file contents
• Private information

Always review recordings before sharing!

Stopping a Recording

To stop recording:

• Type exit in the shell
• Press Ctrl-D
• The program you’re recording exits naturally

The recording will be saved and the location will be printed:

Child status: ExitStatus(unix_wait_status(0))
*** Finished recording to /path/to/recording.cast

Related

• wezterm replay - Replay asciicast recordings
• wezterm start - Start a terminal session
• Asciicast v2 Format Specification