CLI Demo Generator

Generate professional animated CLI demos with ease. This skill supports both automated generation from command descriptions and manual control for custom demos.

When to Use This Skill

Trigger this skill when users request:

• "Create a demo showing how to install my package"
• "Generate a CLI demo of these commands"
• "Make an animated GIF of my terminal workflow"
• "Record a terminal session and convert to GIF"
• "Batch generate demos from this config"
• "Create an interactive typing demo"

Core Capabilities

1. Automated Demo Generation (Recommended)

Use the auto_generate_demo.py script for quick, automated demo creation. This is the easiest and most common approach.

Basic Usage:

scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -c "npm run build" \
  -o demo.gif

With Options:

scripts/auto_generate_demo.py \
  -c "command1" \
  -c "command2" \
  -o output.gif \
  --title "Installation Demo" \
  --theme "Dracula" \
  --width 1400 \
  --height 700

Script Parameters:

• -c, --command: Command to include (can be specified multiple times)
• -o, --output: Output GIF file path (required)
• --title: Demo title (optional, shown at start)
• --theme: VHS theme (default: Dracula)
• --font-size: Font size (default: 16)
• --width: Terminal width (default: 1400)
• --height: Terminal height (default: 700)
• --no-execute: Generate tape file only, don't execute VHS

Smart Features:

• Automatic timing based on command complexity
• Optimized sleep durations (1-3s depending on operation)
• Proper spacing between commands
• Professional defaults

2. Batch Demo Generation

Use batch_generate.py for creating multiple demos from a configuration file.

Configuration File (YAML):

demos:
  - name: "Install Demo"
    output: "install.gif"
    title: "Installation"
    theme: "Dracula"
    commands:
      - "npm install my-package"
      - "npm run build"

  - name: "Usage Demo"
    output: "usage.gif"
    commands:
      - "my-package --help"
      - "my-package run"

Usage:

scripts/batch_generate.py config.yaml --output-dir ./demos

When to Use Batch Generation:

• Creating a suite of related demos
• Documenting multiple features
• Generating demos for tutorials or documentation
• Maintaining consistent demo series

3. Interactive Recording

Use record_interactive.sh for recording live terminal sessions.

Usage:

scripts/record_interactive.sh output.gif \
  --theme "Dracula" \
  --width 1400

Recording Process:

1. Script starts asciinema recording
2. Type commands naturally in your terminal
3. Press Ctrl+D when finished
4. Script auto-converts to GIF via VHS

When to Use Interactive Recording:

• Demonstrating complex workflows
• Showing real command output
• Capturing live interactions
• Recording debugging sessions

4. Manual Tape File Creation

For maximum control, create VHS tape files manually using templates.

Available Templates:

• assets/templates/basic.tape - Simple command demo
• assets/templates/interactive.tape - Typing simulation

Example Workflow:

1. Copy template: cp assets/templates/basic.tape my-demo.tape
2. Edit commands and timing
3. Generate GIF: vhs < my-demo.tape

Consult references/vhs_syntax.md for complete VHS syntax reference.

Workflow Guidance

For Simple Demos (1-3 commands)

Use automated generation for quick results:

scripts/auto_generate_demo.py \
  -c "echo 'Hello World'" \
  -c "ls -la" \
  -o hello-demo.gif \
  --title "Hello Demo"

For Multiple Related Demos

Create a batch configuration file and use batch generation:

1. Create demos-config.yaml with all demo definitions
2. Run: scripts/batch_generate.py demos-config.yaml --output-dir ./output
3. All demos generate automatically with consistent settings

For Interactive/Complex Workflows

Use interactive recording to capture real behavior:

scripts/record_interactive.sh my-workflow.gif
# Type commands naturally
# Ctrl+D when done

For Custom Timing/Layout

Create manual tape file with precise control:

1. Start with template or generate base tape with --no-execute
2. Edit timing, add comments, customize layout
3. Generate: vhs < custom-demo.tape

Best Practices

Refer to references/best_practices.md for comprehensive guidelines. Key recommendations:

Timing:

• Quick commands (ls, pwd): 1s sleep
• Standard commands (grep, cat): 2s sleep
• Heavy operations (install, build): 3s+ sleep

Sizing:

• Standard: 1400x700 (recommended)
• Compact: 1200x600
• Presentations: 1800x900

Themes:

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

Duration:

• Target: 15-30 seconds
• Maximum: 60 seconds
• Create series for complex topics

Troubleshooting

VHS Not Installed

# macOS
brew install vhs

# Linux (via Go)
go install gi

...