fernandezbaptiste/cli-demo-generator

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 github.com/charmbracelet/vhs@latest

Asciinema Not Installed

# macOS
brew install asciinema

# Linux
sudo apt install asciinema

Demo File Too Large

Solutions:

1. Reduce duration (shorter sleep times)
2. Use smaller dimensions (1200x600)
3. Consider MP4 format: Output demo.mp4
4. Split into multiple shorter demos

Output Not Readable

Solutions:

1. Increase font size: --font-size 18
2. Use wider terminal: --width 1600
3. Choose high-contrast theme: --theme "Dracula"
4. Test on target display device

Examples

Example 1: Quick Install Demo

User request: "Create a demo showing npm install"

scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -o install-demo.gif \
  --title "Package Installation"

Example 2: Multi-Step Tutorial

User request: "Create a demo showing project setup with git clone, install, and run"

scripts/auto_generate_demo.py \
  -c "git clone https://github.com/user/repo.git" \
  -c "cd repo" \
  -c "npm install" \
  -c "npm start" \
  -o setup-demo.gif \
  --title "Project Setup" \
  --theme "Nord"

Example 3: Batch Generation

User request: "Generate demos for all my CLI tool features"

1. Create features-demos.yaml:

demos:
  - name: "Help Command"
    output: "help.gif"
    commands: ["my-tool --help"]

  - name: "Init Command"
    output: "init.gif"
    commands: ["my-tool init", "ls -la"]

  - name: "Run Command"
    output: "run.gif"
    commands: ["my-tool run --verbose"]

2. Generate all:

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

Example 4: Interactive Session

User request: "Record me using my CLI tool interactively"

scripts/record_interactive.sh my-session.gif --theme "Tokyo Night"
# User types commands naturally
# Ctrl+D to finish

Bundled Resources

scripts/

• auto_generate_demo.py - Automated demo generation from command lists
• batch_generate.py - Generate multiple demos from YAML/JSON config
• record_interactive.sh - Record and convert interactive terminal sessions

references/

• vhs_syntax.md - Complete VHS tape file syntax reference
• best_practices.md - Demo creation guidelines and best practices

assets/

• templates/basic.tape - Basic command demo template
• templates/interactive.tape - Interactive typing demo template
• examples/batch-config.yaml - Example batch configuration file

Dependencies

Required:

• VHS (https://github.com/charmbracelet/vhs)

Optional:

• asciinema (for interactive recording)
• PyYAML (for batch YAML configs): pip install pyyaml

Output Formats

VHS supports multiple output formats:

Output demo.gif     # GIF (default, best for documentation)
Output demo.mp4     # MP4 (better compression for long demos)
Output demo.webm    # WebM (smaller file size)

Choose based on use case:

• GIF: Documentation, README files, easy embedding
• MP4: Longer demos, better quality, smaller size
• WebM: Web-optimized, smallest file size

Summary

This skill provides three main approaches:

1. Automated (auto_generate_demo.py) - Quick, easy, smart defaults
2. Batch (batch_generate.py) - Multiple demos, consistent settings
3. Interactive (record_interactive.sh) - Live recording, real output

Choose the approach that best fits the user's needs. For most cases, automated generation is the fastest and most convenient option.