Skip to main content
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