Terminal Screenshots & Recordings with VHS

Generate terminal screenshots and animated GIFs/videos using VHS from Charmbracelet.

When to Use This Skill

• Creating terminal screenshots for documentation
• Recording animated GIFs of CLI demos
• Generating video tutorials for command-line tools
• Producing consistent, reproducible terminal visuals
• Integration testing with golden file comparisons

Prerequisites

Check Installation

# Check if vhs is installed
which vhs && vhs --version

# Check dependencies
which ttyd && which ffmpeg

Installation

Recommended: Homebrew (macOS/Linux)

brew install vhs

This installs VHS with all required dependencies (ttyd, ffmpeg).

Other methods:

# Fedora/RHEL
echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
sudo dnf install vhs ffmpeg
# Also install ttyd: https://github.com/tsl0922/ttyd/releases

# Arch Linux
pacman -S vhs

# Docker (includes all dependencies)
docker run --rm -v $PWD:/vhs ghcr.io/charmbracelet/vhs <cassette>.tape

Basic Usage

1. Create a Tape File

vhs new demo.tape

2. Edit the Tape File

Tape files are simple scripts that describe what to type and capture.

3. Run VHS

vhs demo.tape

Tape File Syntax

Output Formats

Output demo.gif          # Animated GIF
Output demo.mp4          # Video file
Output demo.webm         # WebM video
Output frames/           # PNG sequence (directory)

You can specify multiple outputs in one tape file.

Settings (Must Be at Top)

# Terminal dimensions
Set Width 1200
Set Height 600

# Font settings
Set FontSize 22
Set FontFamily "JetBrains Mono"

# Appearance
Set Theme "Catppuccin Mocha"
Set Padding 20
Set Margin 20
Set MarginFill "#1e1e2e"
Set BorderRadius 10
Set WindowBar Colorful

# Behavior
Set Shell "bash"
Set TypingSpeed 50ms
Set Framerate 30
Set CursorBlink false

Common Themes

Run vhs themes to see all available themes. Popular ones:

• Catppuccin Mocha, Catppuccin Frappe
• Dracula
• Tokyo Night
• Nord
• One Dark

Commands

Command	Description	Example
Type "text"	Type characters	Type "echo hello"
Type@500ms "text"	Type slowly	Type@500ms "important"
Enter	Press Enter	Enter
Enter 2	Press Enter twice	Enter 2
Sleep 1s	Wait duration	Sleep 500ms
Backspace	Delete character	Backspace 5
Tab	Press Tab	Tab
Space	Press Space	Space
Ctrl+C	Control sequences	Ctrl+L
Up/Down/Left/Right	Arrow keys	Up 3
Hide	Stop recording frames	Hide
Show	Resume recording	Show
Screenshot file.png	Capture current frame	Screenshot out.png
Wait /regex/	Wait for text to appear	Wait /\$\s*$/
Env KEY "value"	Set environment variable	Env PS1 "$ "
Require program	Fail if program missing	Require git
Source file.tape	Include another tape	Source setup.tape

Escaping Quotes

Use backticks to escape quotes:

Type `echo "hello world"`
Type `VAR='value'`

Examples

Static Screenshot

Output screenshot.png

Set Width 800
Set Height 400
Set FontSize 18
Set Theme "Catppuccin Mocha"
Set Padding 20

# Hide setup
Hide
Type "clear"
Enter
Show

# The actual content
Type "ls -la"
Enter
Sleep 500ms

Screenshot screenshot.png

Animated Demo GIF

Output demo.gif

Set Width 1000
Set Height 500
Set FontSize 20
Set Theme "Dracula"
Set TypingSpeed 50ms
Set Padding 20
Set WindowBar Colorful

# Clean start
Hide
Type "clear"
Enter
Show

# Demo sequence
Type "echo 'Hello from VHS!'"
Sleep 300ms
Enter
Sleep 1s

Type "date"
Enter
Sleep 1s

Type "echo 'That was easy!'"
Enter
Sleep 2s

MP4 Video with Clean Prompt

Output tutorial.mp4

Set Width 1200
Set Height 600
Set FontSize 24
Set Theme "Tokyo Night"
Set Shell "bash"
Set Framerate 30

# Set a clean, minimal prompt
Hide
Env PS1 "$ "
Type "clear"
Enter
Show

Type "# Welcome to the tutorial"
Enter
Sleep 1s

Type "git status"
Enter
Sleep 2s

Type "git log --oneline -5"
Enter
Sleep 3s

Tips for Clean Output

1. Hide Setup/Cleanup

# Setup (hidden)
Hide
Type "cd ~/project && clear"
Enter
Show

# Your demo here...

# Cleanup (hidden)
Hide
Type "cd - && rm temp-files"
Enter

2. Use a Simple Prompt

Hide
Env PS1 "$ "
Type "clear"
Enter
Show

3. Control Timing

• Use Sleep liberally for readability
• Sleep 500ms after typing, before Enter
• Sleep 1s to 2s after command output
• End with Sleep 2s or more for the final frame

4. Typing Speed

# Default speed for setup
Set TypingSpeed 10ms

# Slow down for important parts
Type@100ms "Important command here"

5. Wait for Output

Type "npm install"
Enter
Wait /added \d+ packages/  # Wait for completion message
Sleep 1s

6. Screenshot at Key Moments

Type "make build"
Enter
Wait /Build complete/
Screenshot build-success.png

Workflow for Documentation

1. Plan your demo sequence
2. Create a .tape file with settings
3. Test with vhs demo.tape (generates output)
4. Iterate - adjust timing, dimensions, theme
5. Commit both the .tape file and output to your repo

Recording Real Sessions

You can record your terminal and generate a tape file:

vhs record > session.tape

Then edit the generated tape file to clean it up.

File Reference

See example tape files in this skill directory:

• basic-screenshot.tape - Simple static screenshot
• demo-recording.tape - Animated GIF demo

Resources

• VHS GitHub
• VHS Themes
• Example Tapes