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

$

\"

# 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

-c

-o

--title

--theme

--font-size

--width

--height

--bootstrap

--filter

--speed

--no-execute

Smart timing:

install

build

test

deploy

ls

pwd

echo

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

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

clear

Show

clear

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

Troubleshooting

brew install charmbracelet/tap/vhs

brew install gifsicle

--speed 2

--width

--font-size

$

\"

clear

Sleep 500ms

Show

Sleep

Dependencies

Required: VHS (

brew install charmbracelet/tap/vhs

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