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

```bash theme={null}
wezterm record [OPTIONS] [PROG]...
```

## Description

Records a terminal session using the [asciicast v2 format](https://github.com/asciinema/asciinema/blob/develop/doc/asciicast-v2.md). 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

<ParamField path="PROG" type="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:**

  ```bash theme={null}
  wezterm record -- bash -l
  wezterm record -- python script.py
  ```
</ParamField>

## Options

<ParamField path="--cwd" type="path">
  Start in the specified directory, instead of the `default_cwd` defined by your WezTerm configuration.

  **Example:**

  ```bash theme={null}
  wezterm record --cwd /home/user/projects
  ```
</ParamField>

<ParamField path="-o, --outfile" type="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:**

  ```bash theme={null}
  wezterm record -o my-session.cast
  wezterm record -o ~/recordings/demo.cast
  ```
</ParamField>

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

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

```bash theme={null}
wezterm record -o demo.cast
```

### Record a specific program

```bash theme={null}
wezterm record -o tutorial.cast -- bash
```

### Record with specific working directory

```bash theme={null}
wezterm record --cwd ~/projects/myapp -o myapp-demo.cast
```

### Record a Python script

```bash theme={null}
wezterm record -o script-output.cast -- python demo.py
```

### Record a specific command sequence

```bash theme={null}
wezterm record -o git-demo.cast -- bash -c '
  git status
  git log --oneline -5
  git diff
'
```

### Record system diagnostics

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

```json theme={null}
{
  "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

```json theme={null}
[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:

```bash theme={null}
wezterm record -o tutorial-part1.cast -- bash
# Demonstrate the commands
# Exit when done
```

### Bug Reports

Capture terminal output for bug reports:

```bash theme={null}
wezterm record -o bug-reproduction.cast
# Reproduce the bug
# Exit
```

### Code Demos

Record demos of your CLI tools:

```bash theme={null}
wezterm record -o mycli-demo.cast -- bash -c '
  mycli --help
  mycli create project
  mycli build
'
```

### Training Materials

Create training recordings:

```bash theme={null}
wezterm record -o shell-basics.cast -- bash
# Demonstrate shell commands
# Exit when done
```

### Testing

Record test sessions for later analysis:

```bash theme={null}
wezterm record -o test-run.cast -- python -m pytest
```

## Tips

### Script your recordings

For consistent recordings, use a script:

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

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

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

### Combine with replay

Test your recording immediately:

```bash theme={null}
wezterm record -o test.cast -- bash
# Do your recording
# Exit
wezterm replay test.cast
```

## Sharing Recordings

Asciicast files can be:

1. **Replayed locally:**
   ```bash theme={null}
   wezterm replay recording.cast
   ```

2. **Uploaded to asciinema.org:**
   ```bash theme={null}
   # 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

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

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

  Always review recordings before sharing!
</Warning>

## 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](/cli/replay) - Replay asciicast recordings
* [wezterm start](/cli/start) - Start a terminal session
* [Asciicast v2 Format Specification](https://github.com/asciinema/asciinema/blob/develop/doc/asciicast-v2.md)