GIF Recorder Skill

Create professional terminal GIF recordings using VHS (Charmbracelet's Video Hardware Store).

When to Use This Skill

Activate this skill when:

• Creating demos for CLI tools or commands
• Recording tutorials showing terminal workflows
• Building showcases for README files or documentation
• Producing shareable terminal animations
• Documenting command sequences with real output

Prerequisites

Verify VHS is installed:

which vhs && vhs --version

If not installed:

brew install vhs

VHS Fundamentals

How VHS Works

VHS executes real commands - not simulations:

1. Spawns a real TTY terminal
2. Types characters with configurable timing
3. Runs actual commands and captures real output
4. Renders frames to GIF/MP4/WebM

Tape File Structure

# Comment describing the recording
Output "filename.gif"

# Configuration
Set FontSize 18
Set Width 800
Set Height 400
Set Theme "Dracula"
Set Padding 20
Set TypingSpeed 40ms

# Commands
Type "echo 'Hello World'"
Enter
Sleep 2s

FAF Demo Style Standards

Recommended Settings

# Standard FAF Demo
Output "demo-name.gif"

Set FontSize 18
Set Width 800
Set Height 400
Set Theme "Dracula"
Set Padding 20
Set TypingSpeed 40ms

Theme Options

Dracula

Catppuccin Mocha

Catppuccin Latte

TokyoNight

Nord

Dimension Presets

Timing Guidelines

VHS Commands Reference

Output

Output "filename.gif"      # GIF output
Output "filename.mp4"      # MP4 video
Output "filename.webm"     # WebM video

Configuration

Set FontSize 18            # Font size in pixels
Set FontFamily "JetBrains Mono"
Set Width 800              # Terminal width
Set Height 400             # Terminal height
Set Theme "Dracula"        # Color theme
Set Padding 20             # Padding around terminal
Set TypingSpeed 40ms       # Delay between keystrokes
Set LineHeight 1.2         # Line height multiplier
Set LetterSpacing 0        # Letter spacing
Set Framerate 60           # GIF framerate
Set PlaybackSpeed 1.0      # Playback speed multiplier

Actions

Type "command"             # Type text
Enter                      # Press Enter
Sleep 2s                   # Wait (s, ms)
Ctrl+C                     # Key combinations
Backspace 5                # Backspace N times
Left 3                     # Arrow key N times
Hide                       # Hide subsequent commands
Show                       # Show commands again

Environment

Set Shell "zsh"            # Shell to use
Set Env "VAR" "value"      # Set environment variable
Source "~/.zshrc"          # Source a file

Demo Templates

Quick Command Demo

# Quick Demo - Single Command
Output "command-demo.gif"

Set FontSize 18
Set Width 800
Set Height 350
Set Theme "Dracula"
Set TypingSpeed 40ms

Type "faf score"
Enter
Sleep 3s

Feature Showcase

# Feature Showcase - Multiple Steps
Output "feature-showcase.gif"

Set FontSize 18
Set Width 900
Set Height 500
Set Theme "Dracula"
Set Padding 20
Set TypingSpeed 35ms

# Title
Type "# Feature Name - Description"
Enter
Sleep 1s

# Setup
Type "cd /path/to/project"
Enter
Sleep 300ms

# Main action
Type "command --with-flags"
Enter
Sleep 3s

# Explanation
Type "# Key insight about the output"
Enter
Sleep 2s

Before/After Comparison

# Before/After Demo
Output "before-after.gif"

Set FontSize 18
Set Width 900
Set Height 500
Set Theme "Dracula"
Set TypingSpeed 35ms

Type "# BEFORE"
Enter
Sleep 500ms

Type "old-command"
Enter
Sleep 2s

Type ""
Enter
Type "# AFTER (new feature)"
Enter
Sleep 500ms

Type "new-command"
Enter
Sleep 3s

Workflow

Creating a Demo

1. Plan the demo - What commands, what story?
2. Create tape file:

   vim demos/my-demo.tape
   

3. Test locally - Run commands manually first
4. Record:

   cd demos && vhs my-demo.tape
   

5. Review - Open GIF, check timing
6. Iterate - Adjust Sleep times, TypingSpeed
7. Publish (optional):

   vhs publish my-demo.gif
   

File Organization

project/
└── demos/
    ├── DEMO-STYLE.md       # Style guide
    ├── feature-intro.tape  # Source files
    ├── feature-intro.gif   # Generated GIFs
    └── ...

Naming Convention

{tool}-{feature}-{type}.tape

Examples:

• faf-go-intro.tape

• faf-score-detailed.tape

• cli-install-quick.tape

Troubleshooting

"Output path invalid"

Quote paths with special characters:

Output "my-demo.gif"  # Good
Output my-demo.gif    # Bad if has spaces/special chars

Commands not running

Ensure commands work in a fresh shell - VHS uses a clean environment.

Output too fast

Increase Sleep times after commands:

Type "command"
Enter
Sleep 3s  # Give time to read output

Colors not showing

Some tools need

FORCE_COLOR=1

Set Env "FORCE_COLOR" "1"

GIF too large

Reduce dimensions, framerate, or duration:

Set Width 700
Set Height 350
Set Framerate 30

Publishing

To vhs.charm.sh

vhs publish demo.gif
# Returns shareable URL

To GitHub README

![Demo](./demos/demo.gif)

To social media

• Twitter/X: GIF embeds directly
• LinkedIn: Upload as video (convert to MP4)
• Discord: Direct GIF upload

Quick Reference

# Minimal FAF Demo Template
Output "demo.gif"
Set FontSize 18
Set Width 800
Set Height 400
Set Theme "Dracula"
Set TypingSpeed 40ms

Type "faf command"
Enter
Sleep 3s

Built for FAF ecosystem demos VHS by Charmbracelet - https://github.com/charmbracelet/vhs