Cli Demo Generator

CLI Demo Generator

Create professional animated CLI demos. Four approaches, from fully automated to pixel-precise manual control.

Quick Start

Simplest path — give commands, get GIF:

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -c "npm run build" \
  -o demo.gif

Self-bootstrapping demo — for repeatable recordings that clean their own state:

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -c "npm run build" \
  -o demo.gif \
  --bootstrap "npm uninstall my-package 2>/dev/null" \
  --speed 2

Critical: VHS Parser Limitations

VHS Type strings cannot contain $, \", or backticks. These cause parse errors:

# FAILS — VHS parser rejects special chars
Type "echo \"hello $USER\""
Type "claude() { command claude \"$@\"; }"

Workaround: base64 encode the command, decode at runtime:

# 1. Encode your complex command
echo 'claude() { command claude "$@" 2>&1 | grep -v "noise"; }' | base64
# Output: Y2xhdWRlKCkgey4uLn0K

# 2. Use in tape
Type "echo Y2xhdWRlKCkgey4uLn0K | base64 -d > /tmp/wrapper.sh && source /tmp/wrapper.sh"

This pattern is essential for output filtering, function definitions, and any command with shell special characters.

Approaches

1. Automated Generation (Recommended)

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "command1" -c "command2" \
  -o output.gif \
  --title "My Demo" \
  --theme "Catppuccin Latte" \
  --font-size 24 \
  --width 1400 --height 600

Smart timing: install/build/test/deploy → 3s, ls/pwd/echo → 1s, others → 2s.

2. Batch Generation

Create multiple demos from one config:

# demos.yaml
demos:
  - name: "Install"
    output: "install.gif"
    commands: ["npm install my-package"]
  - name: "Usage"
    output: "usage.gif"
    commands: ["my-package --help", "my-package run"]

python3 ${CLAUDE_SKILL_DIR}/scripts/batch_generate.py demos.yaml --output-dir ./gifs

3. Interactive Recording

Record a live terminal session:

bash ${CLAUDE_SKILL_DIR}/scripts/record_interactive.sh output.gif --theme "Catppuccin Latte"
# Type commands naturally, Ctrl+D when done

Requires asciinema (brew install asciinema).

4. Manual Tape File

For maximum control, write a tape directly. Templates in assets/templates/:

• basic.tape — simple command sequence
• interactive.tape — typing simulation
• self-bootstrap.tape — self-cleaning demo with hidden setup (recommended for repeatable demos)

Advanced Patterns

These patterns come from production use. See references/advanced_patterns.md for full details.

Self-Bootstrapping Demos

Demos that clean previous state, set up environment, and hide all of it from the viewer:

Hide
Type "cleanup-previous-state 2>/dev/null"
Enter
Sleep 2s
Type "clear"
Enter
Sleep 500ms
Show

Type "the-command-users-see"
Enter
Sleep 3s

The Hide → commands → clear → Show sequence is critical. clear wipes the terminal buffer so hidden commands don't leak into the GIF.

Output Noise Filtering

Filter noisy progress lines from commands that produce verbose output:

# Hidden: create a wrapper function that filters noise
Hide
Type "echo <base64-encoded-wrapper> | base64 -d > /tmp/w.sh && source /tmp/w.sh"
Enter
Sleep 500ms
Type "clear"
Enter
Sleep 500ms
Show

# Visible: clean command, filtered output
Type "my-noisy-command"
Enter
Sleep 3s

Frame Verification

After recording, verify GIF content by extracting key frames:

# Extract frames at specific positions
ffmpeg -i demo.gif -vf "select=eq(n\,100)" -frames:v 1 /tmp/frame.png -y 2>/dev/null

# View the frame (Claude can read images)
# Use Read tool on /tmp/frame.png to verify content

Post-Processing Speed-Up

Use gifsicle to speed up recordings without re-recording:

# 2x speed (halve frame delay)
gifsicle -d2 original.gif "#0-" > fast.gif

# 1.5x speed
gifsicle -d4 original.gif "#0-" > faster.gif

Template Placeholder Pattern

Keep tape files generic with placeholders, replace at build time:

# In tape file
Type "claude plugin marketplace add MARKETPLACE_REPO"

# In build script
sed "s|MARKETPLACE_REPO|$DETECTED_REPO|g" template.tape > rendered.tape
vhs rendered.tape

Timing & Sizing Reference

See references/best_practices.md for detailed guidelines.

Troubleshooting

Dependencies

Required: VHS (brew install charmbracelet/tap/vhs)

Optional: gifsicle (speed-up), asciinema (interactive recording), ffmpeg (frame verification), PyYAML (batch YAML configs)

Advanced VHS Demo Patterns

Battle-tested patterns from production demo recording workflows.

Contents

• Self-bootstrapping tapes
• Output noise filtering with base64 wrapper
• Frame-level verification
• Post-processing with gifsicle
• Auto-detection and template rendering
• Recording script structure

Self-Bootstrapping Tapes

A self-bootstrapping tape cleans its own state before recording, so running it twice produces identical output. Three phases:

# Phase 1: HIDDEN CLEANUP — remove previous state
Hide
Type "my-tool uninstall 2>/dev/null; my-tool reset 2>/dev/null"
Enter
Sleep 3s

# Phase 2: HIDDEN SETUP — create helpers (base64 for special chars)
Type "echo <base64-wrapper> | base64 -d > /tmp/helper.sh && source /tmp/helper.sh"
Enter
Sleep 500ms

# Phase 3: CLEAR + SHOW — wipe buffer before revealing
Type "clear"
Enter
Sleep 500ms
Show

# Phase 4: VISIBLE DEMO — what the viewer sees
Type "my-tool install"
Enter
Sleep 3s

Why `clear` before `Show`: VHS's Hide stops recording frames, but the terminal buffer still accumulates text. Without clear, the hidden commands' text appears in the first visible frame.

Output Noise Filtering with Base64

Many CLI tools produce verbose progress output that clutters demos. The solution: a hidden shell wrapper that filters noise lines.

Step 1: Create the wrapper function

# The function you want (can't type directly in VHS due to $/" chars)
my_tool() { command my_tool "$@" 2>&1 | grep -v -E "cache|progress|downloading|timeout"; }

Step 2: Base64 encode it

echo 'my_tool() { command my_tool "$@" 2>&1 | grep -v -E "cache|progress|downloading|timeout"; }' | base64
# Output: bXlfdG9vbCgpIHsgY29tbWFuZC4uLn0K

Step 3: Use in tape

Hide
Type "echo bXlfdG9vbCgpIHsgY29tbWFuZC4uLn0K | base64 -d > /tmp/w.sh && source /tmp/w.sh"
Enter
Sleep 500ms
Type "clear"
Enter
Sleep 500ms
Show

# Now `my_tool` calls the wrapper — clean output
Type "my_tool deploy"
Enter
Sleep 5s

When to filter

• Git operations: filter "Cloning", "Refreshing", cache messages
• Package managers: filter download progress, cache hits
• Build tools: filter intermediate compilation steps
• Any command with SSH not configured, timeout: 120s, etc.

Frame-Level Verification

After recording, extract and inspect key frames to verify the GIF shows what you expect.

Extract specific frames

# Frame at position N (0-indexed)
ffmpeg -i demo.gif -vf "select=eq(n\,100)" -frames:v 1 /tmp/frame_100.png -y 2>/dev/null

# Multiple frames at once
for n in 50 200 400; do
  ffmpeg -i demo.gif -vf "select=eq(n\,$n)" -frames:v 1 "/tmp/frame_$n.png" -y 2>/dev/null
done

Check total frame count and duration

ffmpeg -i demo.gif 2>&1 | grep -E "Duration|fps"
# Duration: 00:00:10.50, ... 25 fps → 262 frames total

What to verify

Claude can read frames

Use the Read tool on extracted PNG files — Claude's vision can verify text content in terminal screenshots.

Post-Processing with gifsicle

Speed up or optimize GIFs after recording, avoiding re-recording.

Speed control

# 2x speed — halve frame delay (most common)
gifsicle -d2 input.gif "#0-" > output.gif

# 1.5x speed
gifsicle -d4 input.gif "#0-" > output.gif

# 3x speed
gifsicle -d1 input.gif "#0-" > output.gif

Optimize file size

# Lossless optimization
gifsicle -O3 input.gif > optimized.gif

# Reduce colors (lossy but smaller)
gifsicle --colors 128 input.gif > smaller.gif

Typical recording script pattern

# Record at normal speed
vhs demo.tape

# Speed up 2x for final output
cp demo.gif /tmp/demo_raw.gif
gifsicle -d2 /tmp/demo_raw.gif "#0-" > demo.gif
rm /tmp/demo_raw.gif

Auto-Detection and Template Rendering

For demos that need to adapt to the environment (e.g., different repo URLs, detected tools).

Template placeholders

Use sed to replace placeholders before recording:

# demo.tape (template)
Type "tool marketplace add REPO_PLACEHOLDER"
Enter

# Build script detects the correct repo
REPO=$(detect_repo)
sed "s|REPO_PLACEHOLDER|$REPO|g" demo.tape > /tmp/rendered.tape
vhs /tmp/rendered.tape

Auto-detect pattern (shell function)

detect_repo() {
  local upstream origin
  upstream=$(git remote get-url upstream 2>/dev/null | sed 's|.*github.com[:/]||; s|\.git$||') || true
  origin=$(git remote get-url origin 2>/dev/null | sed 's|.*github.com[:/]||; s|\.git$||') || true

  # Check upstream first (canonical), then origin (fork)
  if [[ -n "$upstream" ]] && gh api "repos/$upstream/contents/.target-file" &>/dev/null; then
    echo "$upstream"
  elif [[ -n "$origin" ]]; then
    echo "$origin"
  else
    echo "fallback/default"
  fi
}

Recording Script Structure

A complete recording script follows this pattern:

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"

# 1. Check prerequisites
for cmd in vhs gifsicle; do
  command -v "$cmd" &>/dev/null || { echo "Missing: $cmd"; exit 1; }
done

# 2. Auto-detect dynamic values
REPO=$(detect_repo)
echo "Using repo: $REPO"

# 3. Render tape template
sed "s|PLACEHOLDER|$REPO|g" "$SCRIPT_DIR/demo.tape" > /tmp/rendered.tape

# 4. Clean previous state
cleanup_state || true

# 5. Record
(cd "$REPO_DIR" && vhs /tmp/rendered.tape)

# 6. Speed up
cp "$REPO_DIR/demo.gif" /tmp/raw.gif
gifsicle -d2 /tmp/raw.gif "#0-" > "$REPO_DIR/demo.gif"

# 7. Clean up
cleanup_state || true
rm -f /tmp/raw.gif /tmp/rendered.tape

# 8. Report
SIZE=$(ls -lh "$REPO_DIR/demo.gif" | awk '{print $5}')
echo "Done: demo.gif ($SIZE)"

CLI Demo Best Practices

Guidelines for creating effective, professional CLI demos.

General Principles

1. Keep It Short

• Target: 15-30 seconds per demo
• Maximum: 60 seconds (unless documenting complex workflows)
• Reason: Short demos maintain viewer attention and are easier to consume

2. Show, Don't Tell

• Focus on visual demonstration over textual explanation
• Let the commands and output speak for themselves
• Add brief comment-style titles when needed

3. One Concept Per Demo

• Each demo should illustrate a single feature or workflow
• For complex topics, create a series of short demos
• Better to have multiple focused demos than one lengthy tutorial

Technical Guidelines

Timing and Pacing

Command Entry Timing:

Type "command" Sleep 500ms   # Fast enough to feel natural
Enter                        # Immediate

Post-Command Sleep (based on operation):

• Quick commands (ls, pwd, echo): 1s
• Standard commands (grep, cat, git status): 1.5-2s
• Heavy operations (install, build, test): 3s+
• Final command: 2-3s for viewers to see result

Between Sections:

• Add 1-1.5s between related commands
• Add 2s+ between different concepts

Terminal Dimensions

Standard Sizes:

# Compact (for narrow contexts)
Set Width 1200
Set Height 600

# Standard (recommended default)
Set Width 1400
Set Height 700

# Wide (for complex output)
Set Width 1600
Set Height 800

# Presentation (for slides)
Set Width 1800
Set Height 900

Choosing Dimensions:

• Consider the output width (avoid wrapping)
• Test with longest expected line
• Standard 1400x700 works for most cases

Font Sizing

Recommended Sizes:

# Documentation (small, information-dense)
Set FontSize 14

# Standard demos (readable)
Set FontSize 16

# Presentations (clear from distance)
Set FontSize 20-24

Choosing Font Size:

• Smaller fonts allow more output visibility
• Larger fonts improve readability on mobile
• Test on target display devices

Theme Selection

By Context:

Documentation/Tutorials:

• Nord - Clean, professional
• GitHub Dark - Familiar to developers
• Catppuccin - Easy on eyes for long reading

Code Demos:

• Dracula - Popular, high contrast
• Monokai - Classic, widely recognized
• Tokyo Night - Modern, vibrant

Presentations:

• High-contrast themes for visibility
• Avoid very dark themes in bright rooms
• Test on actual projection equipment

Brand Alignment:

• Match company/project color schemes
• Custom themes can be defined

Content Guidelines

Command Structure

Clear Sequencing:

# Good - Shows logical flow
Type "# Step 1: Setup"
Sleep 500ms Enter
Type "mkdir project && cd project"
Sleep 500ms Enter
Sleep 2s

Type "# Step 2: Install"
Sleep 500ms Enter
Type "npm install"
Sleep 500ms Enter
Sleep 3s

Avoid:

# Bad - No context, rushed
Type "mkdir project"
Enter
Type "cd project"
Enter
Type "npm install"
Enter

Adding Context

Title Slides:

Type "# Demo: Package Installation"
Sleep 500ms Enter
Sleep 1.5s

Section Headers:

Type "## Installing dependencies..."
Sleep 500ms Enter
Sleep 1s

Comments:

Type "npm install  # This may take a moment"
Sleep 500ms Enter

Output Visibility

Ensure Key Output is Visible:

• Let important output display fully before next command
• For long output, consider showing excerpts
• Use Sleep to give viewers time to read

Managing Long Output:

# Option 1: Show beginning only
Type "npm install"
Enter
Sleep 2s    # Shows first part of output
Ctrl+C      # Stop before it scrolls too much

# Option 2: Use commands that limit output
Type "git log --oneline -5"  # Show last 5 commits only
Enter

File Size Optimization

Target Sizes

• Small demos (<500KB): Ideal for documentation
• Medium demos (500KB-1MB): Acceptable for most uses
• Large demos (>1MB): Consider compression or shorter duration

Reducing File Size

1. Shorter Duration:

# Reduce unnecessary sleep time
Sleep 1s    # Instead of Sleep 3s

2. Smaller Dimensions:

# Use compact size for simple demos
Set Width 1200
Set Height 600

3. Appropriate Format:

Output demo.mp4     # Better compression for longer demos
Output demo.webm    # Smaller file size than GIF
Output demo.gif     # Good for short demos

Accessibility

Consider All Viewers

Color Choices:

• High contrast improves readability
• Avoid color-only distinctions
• Test with color-blind simulators

Font Size:

• 16pt minimum for web documentation
• 20pt minimum for presentations
• Test on mobile devices

Pacing:

• Allow time to read output
• Avoid rapid command sequences
• Provide clear visual breaks

Testing and Quality Assurance

Before Publishing

1. Watch the Entire Demo:

• Verify all commands execute as expected
• Check for timing issues
• Ensure output is visible

2. Test on Different Displays:

• Desktop monitors
• Mobile devices
• Projection screens (if for presentations)

3. Check File Size:

• Optimize if necessary
• Consider alternative formats

4. Verify Accessibility:

• Readable fonts
• Clear contrast
• Appropriate pacing

5. Get Feedback:

• Show to someone unfamiliar with the content
• Ask if the flow is clear
• Adjust based on feedback

Common Mistakes to Avoid

❌ Too Fast

Type "command1" Enter Sleep 0.5s
Type "command2" Enter Sleep 0.5s
Type "command3" Enter Sleep 0.5s
# Viewers can't process this

✅ Appropriate Pacing

Type "command1" Sleep 500ms Enter
Sleep 2s

Type "command2" Sleep 500ms Enter
Sleep 2s

❌ No Context

Type "npm install"
Enter
# What are we installing? Why?

✅ With Context

Type "# Installing dependencies"
Sleep 500ms Enter
Sleep 1s

Type "npm install"
Sleep 500ms Enter

❌ Output Scrolls Too Fast

Type "long-running-command"
Enter
Sleep 1s  # Output still scrolling!
Type "next-command"

✅ Allow Output to Complete

Type "long-running-command"
Enter
Sleep 3s  # Let it finish

Type "next-command"

Examples of Good Demos

Simple Feature Demo (15 seconds)

Output feature-demo.gif
Set FontSize 16
Set Width 1400
Set Height 700
Set Theme "Dracula"

Type "# Demo: Quick Start" Sleep 500ms Enter
Sleep 1.5s

Type "npm install my-tool" Sleep 500ms Enter
Sleep 2.5s

Type "my-tool --help" Sleep 500ms Enter
Sleep 2s

Multi-Step Workflow (30 seconds)

Output workflow-demo.gif
Set FontSize 16
Set Width 1400
Set Height 700
Set Theme "Nord"

Type "# Demo: Complete Workflow" Sleep 500ms Enter
Sleep 1.5s

Type "# 1. Create project" Sleep 500ms Enter
Type "mkdir my-project && cd my-project" Sleep 500ms Enter
Sleep 2s

Type "# 2. Initialize" Sleep 500ms Enter
Type "npm init -y" Sleep 500ms Enter
Sleep 2s

Type "# 3. Install package" Sleep 500ms Enter
Type "npm install express" Sleep 500ms Enter
Sleep 3s

Type "# 4. Ready to code!" Sleep 500ms Enter
Sleep 2s

Summary Checklist

Before publishing a demo, verify:

• [ ] Duration is appropriate (15-30s ideal)
• [ ] Timing allows reading output
• [ ] Commands are clear and purposeful
• [ ] Context is provided where needed
• [ ] Output is fully visible
• [ ] File size is reasonable
• [ ] Theme and fonts are readable
• [ ] Tested on target devices
• [ ] Accessible to all viewers
• [ ] Demonstrates one clear concept

VHS Tape File Syntax Reference

VHS (Video Home System) is a tool for creating terminal recordings as code. This reference covers the complete tape file syntax.

Basic Structure

Output demo.gif

Set FontSize 16
Set Width 1400
Set Height 700
Set Theme "Dracula"

Type "echo Hello"
Enter
Sleep 1s

Configuration Commands

Output

Specify the output file path and format:

Output demo.gif       # GIF format (default)
Output demo.mp4       # MP4 video
Output demo.webm      # WebM video

Set Commands

Configure the terminal appearance:

Set FontSize 16               # Font size (10-72)
Set Width 1400                # Terminal width in pixels
Set Height 700                # Terminal height in pixels
Set Theme "Dracula"           # Color theme
Set Padding 20                # Padding around terminal (pixels)
Set TypingSpeed 50ms          # Speed of typing animation
Set Shell bash                # Shell to use (bash, zsh, fish)
Set FontFamily "MonoLisa"     # Font family name

Interaction Commands

Type

Simulate typing text:

Type "ls -la"           # Type the command
Type "Hello World"      # Type any text

Enter

Press the Enter key:

Enter

Backspace

Delete characters:

Backspace              # Delete one character
Backspace 5            # Delete 5 characters

Sleep

Pause execution:

Sleep 1s               # Sleep for 1 second
Sleep 500ms            # Sleep for 500 milliseconds
Sleep 2.5s             # Sleep for 2.5 seconds

Ctrl+C

Send interrupt signal:

Ctrl+C

Key combinations

Ctrl+D                 # End of transmission
Ctrl+L                 # Clear screen
Tab                    # Tab completion

Advanced Features

Play (asciinema integration)

Play back an asciinema recording:

Play recording.cast

Hide/Show

Control terminal visibility:

Hide
Type "secret command"
Show

Screenshot

Take a screenshot at specific point:

Screenshot demo-screenshot.png

Available Themes

Popular built-in themes:

• Dracula - Dark purple theme
• Monokai - Classic dark theme
• Nord - Arctic-inspired cool theme
• Catppuccin - Soothing pastel theme
• GitHub Dark - GitHub's dark theme
• Tokyo Night - Vibrant dark theme
• Gruvbox - Retro groove colors

Example Templates

Basic Command Demo

Output demo.gif

Set FontSize 16
Set Width 1400
Set Height 700
Set Theme "Dracula"

Type "# Demo Title" Sleep 500ms Enter
Sleep 1s

Type "command1" Sleep 500ms Enter
Sleep 2s

Type "command2" Sleep 500ms Enter
Sleep 2s

Interactive Typing Demo

Output demo.gif

Set FontSize 16
Set Width 1400
Set Height 700
Set Theme "Dracula"
Set TypingSpeed 100ms

Type "npm install my-package"
Enter
Sleep 3s

Type "npm start"
Enter
Sleep 2s

Multi-Step Tutorial

Output tutorial.gif

Set FontSize 16
Set Width 1400
Set Height 700
Set Theme "Tokyo Night"

Type "# Step 1: Clone the repository" Enter
Sleep 1s
Type "git clone https://github.com/user/repo.git" Enter
Sleep 3s

Type "# Step 2: Install dependencies" Enter
Sleep 1s
Type "cd repo && npm install" Enter
Sleep 3s

Type "# Step 3: Run the app" Enter
Sleep 1s
Type "npm start" Enter
Sleep 2s

Best Practices

1. Timing: Use appropriate sleep durations

• Quick commands: 1s
• Medium commands: 2s
• Long commands (install, build): 3s+

2. Width/Height: Standard sizes

• Compact: 1200x600
• Standard: 1400x700
• Wide: 1600x800

3. Font Size: Readability

• Small terminals: 14-16
• Standard: 16-18
• Presentations: 20-24

4. Theme Selection: Consider context

• Code demos: Dracula, Monokai
• Documentation: Nord, GitHub Dark
• Presentations: High-contrast themes

5. Title Slides: Add context

   Type "# Demo: Project Setup" Enter
   Sleep 1s

6. Cleanup: Show clear ending

   Sleep 2s
   Type "# Demo complete!" Enter