How to Install and Use VHS in Linux to Generate Terminal Demos and GIFs as Code

Documenting command-line tools, writing developer tutorials, or demonstrating new CLI releases frequently requires animated demonstrations. Traditional screen recording software like OBS or SimpleScreenRecorder often produces unwieldy, blurry video files and requires re-recording entire takes whenever a typographical error occurs.

VHS (developed by Charmbracelet) revolutionises terminal recordings by allowing developers to write declarative scripts—called .tape files—that automate terminal typing, pauses, key combinations, and rendering. VHS generates pixel-perfect, syntax-highlighted GIFs and MP4 videos directly from the Linux command line. In this guide, explore how to install, write tape files, and automate high-quality terminal demos using VHS on Linux.

Why Automate Terminal Recordings with VHS?

VHS treats terminal demonstrations as code. Instead of manual mouse clicks and keyboard recordings, your demonstration steps are codified in plain text:

Feature	Manual Screen Recording (OBS, Kazam)	Scripted Terminal Automation (VHS)
Reproducibility	Requires manual re-typing for every edit	Instantly re-render entire demo by editing text script
Typographical Speed	Inconsistent human typing cadences	Configurable, perfectly uniform typing simulation
Styling and Theming	Locked to host desktop terminal profile	Declarative custom fonts, padding, colours, and shadow styling
CI/CD Integration	Impossible to automate in pipelines	Runs headlessly inside GitHub Actions and Docker containers

Installing VHS on Linux Distributions

VHS relies on two lightweight underlying dependencies to render headless sessions and compress frames: ttyd (a web terminal driver) and ffmpeg (for video encoding). Ensure both packages are present or let your package manager resolve them automatically.

Method 1: Installing via Official Package Managers (Debian / Ubuntu)

Charm maintains official Debian and Ubuntu repositories:

# Install Charm GPG key and APT repository
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list

# Update indices and install VHS along with ffmpeg
sudo apt update
sudo apt install -y vhs ffmpeg

Method 2: Installing Precompiled Binaries from GitHub Releases

For standalone environments, download the precompiled binary directly:

# Download latest Linux x86_64 release archive
curl -LO https://github.com/charmbracelet/vhs/releases/latest/download/vhs_Linux_x86_64.tar.gz

# Extract binary
tar -xzf vhs_Linux_x86_64.tar.gz

# Relocate to executable directory
sudo mv vhs /usr/local/bin/
sudo chmod +x /usr/local/bin/vhs

# Verify installation
vhs --version

Method 3: Installing via Arch Linux (Pacman)

Arch Linux includes VHS directly in official extra repositories:

sudo pacman -S vhs ffmpeg ttyd

Understanding VHS Tape File Syntax

VHS recordings are configured through .tape files. A tape file contains top-level visual settings followed by sequential keyboard commands.

The core command syntax includes intuitive actions:

Command	Example Usage	Action Performed
Output	Output demo.gif	Specifies target filename (supports .gif, .mp4, .webm)
Type	Type "echo 'Hello World'"	Types the string character-by-character into the terminal
Enter	Enter or Enter 2	Simulates pressing the Return/Enter key
Sleep	Sleep 500ms or Sleep 2s	Pauses execution to allow output or animation to be viewed
Backspace	Backspace 5	Deletes previous characters to simulate realistic corrections
Ctrl+C	Ctrl+C	Interrupts active commands or exits processes cleanly

Writing Your First Demonstration Tape

Create a file named htop_demo.tape in your text editor:

# Output settings
Output htop_demo.gif
Output htop_demo.mp4

# Terminal geometry and aesthetics
Set FontSize 16
Set Width 1200
Set Height 600
Set Padding 20
Set Theme "Catppuccin Mocha"
Set CornerRadius 10
Set TypingSpeed 60ms

# Automation routine
Type "clear"
Enter
Sleep 1s

Type "echo 'Monitoring system performance with htop...'"
Enter
Sleep 2s

Type "htop"
Enter
Sleep 5s

Type "q"
Sleep 1s

Type "echo 'Done!'"
Enter
Sleep 2s

Compiling the Recording into a GIF or Video

Once your tape script is written, compile the demo by running:

vhs < htop_demo.tape

VHS launches a headless virtual terminal, executes each keystroke with hardware-timed precision, records the resulting canvas, and outputs crisp htop_demo.gif and htop_demo.mp4 files ready to embed into GitHub readmes or presentation decks.

Advanced Customisation: Styling and Environment Tuning

VHS allows full visual customisation to match your brand or project aesthetics:

Selecting Built-in Themes

VHS ships with dozens of popular terminal color themes including Dracula, Nord, Gruvbox Dark, TokyoNight, and Solarized Dark. Define your palette with a single line:

Set Theme "Dracula"

Custom Fonts and Line Spacing

Ensure that code glyphs and Powerline icons render crisply by declaring a specific monospace font installed on your system:

Set FontFamily "JetBrains Mono"
Set LineHeight 1.4
Set LetterSpacing 0.1

Adjusting Frame Rates and Quality

To reduce file size for web embedding, tune playback timing:

# Reduce GIF framerate for lightweight uploads
Set Framerate 30
# Add subtle window drop-shadow
Set WindowBar "Colorful"

Automating GIF Generation in GitHub Actions

Because VHS runs entirely headlessly without requiring an X11 display server, you can automatically re-render project documentation GIFs whenever your CLI code changes:

name: Render CLI Demo
on: [push]

jobs:
  build-demo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: charmbracelet/vhs-action@v2
        with:
          path: 'docs/demo.tape'
      - name: Commit Updated Demo GIF
        run: |
          git config --local user.email "[email protected]"
          git config --local user.name "GitHub Action"
          git commit -am "chore: update demo.gif via VHS" || exit 0
          git push

Streamlining Developer Documentation

By transforming manual screen recording into version-controlled scripts, VHS eliminates the repetitive drudgery of keeping terminal documentation up to date. Incorporate .tape files into your software repositories to ensure documentation always reflects the latest state of your command-line utilities.