Cli Demo Generator

---
name: cli-demo-generator
description: Create terminal recordings and animated CLI demo GIFs from command workflows or VHS tape files.
zh_description: "把命令行操作制作成终端录屏和动态演示 GIF。"
version: "1.0.1"
author: "seaworld008"
source: "in-house"
source_url: ""
tags: '["cli", "demo", "development", "generator"]'
created_at: "2026-03-04"
updated_at: "2026-09-06"
quality: 5
complexity: "intermediate"
---

# 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:**
```bash
scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -c "npm run build" \
  -o demo.gif
```

**With Options:**
```bash
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):**
```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:**
```bash
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:**
```bash
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:

```bash
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:

```bash
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

```bash
# macOS
brew install vhs

# Linux (via Go)
go install github.com/charmbracelet/vhs@latest
```

### Asciinema Not Installed

```bash
# 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"

```bash
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"

```bash
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`:
```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:
```bash
scripts/batch_generate.py features-demos.yaml --output-dir ./demos
```

### Example 4: Interactive Session

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

```bash
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:

```tape
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.