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:

Critical: VHS Parser Limitations

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

Workaround: base64 encode the command, decode at runtime:

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

Approaches

1. Automated Generation (Recommended)

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

2. Batch Generation

Create multiple demos from one config:

3. Interactive Recording

Record a live terminal session:

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:

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:

Frame Verification

After recording, verify GIF content by extracting key frames:

Post-Processing Speed-Up

Use gifsicle to speed up recordings without re-recording:

Template Placeholder Pattern

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

Timing & Sizing Reference

See references/best_practices.md for detailed guidelines.

Troubleshooting

Tape File Syntax

references/vhs_syntax.md is the full VHS tape-file reference — every command, setting, and key name, with the argument forms each accepts. Read it when writing a tape by hand, when a tape parses but behaves unexpectedly, or when you need a command this SKILL.md does not show an example of.

Dependencies

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

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