cli-demo-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLI Demo Generator

CLI 演示生成器

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

轻松生成专业的动画CLI演示。此技能支持从命令描述自动生成，也支持手动控制以创建自定义演示。

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"

当用户提出以下请求时触发此技能：

"创建一个展示如何安装我的包的演示"
"生成这些命令的CLI演示"
"制作我的终端工作流的动画GIF"
"录制终端会话并转换为GIF"
"从此配置批量生成演示"
"创建交互式打字演示"

Core Capabilities

核心功能

1. Automated Demo Generation (Recommended)

1. 自动演示生成（推荐）

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

使用

auto_generate_demo.py

脚本快速创建自动演示。这是最简单、最常用的方法。

基本用法：

bash

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

带选项的用法：

bash

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

脚本参数：

```
-c, --command
```
: 要包含的命令（可多次指定）
```
-o, --output
```
: 输出GIF文件路径（必填）
```
--title
```
: 演示标题（可选，在开头显示）
```
--theme
```
: VHS主题（默认：Dracula）
```
--font-size
```
: 字体大小（默认：16）
```
--width
```
: 终端宽度（默认：1400）
```
--height
```
: 终端高度（默认：700）
```
--no-execute
```
: 仅生成tape文件，不执行VHS

智能特性：

根据命令复杂度自动调整计时
优化的休眠时长（根据操作不同为1-3秒）
命令之间的适当间距
专业的默认设置

2. Batch Demo Generation

2. 批量演示生成

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

使用

batch_generate.py

从配置文件创建多个演示。

配置文件（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"

用法：

bash

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

何时使用批量生成：

创建一组相关演示
记录多个功能
为教程或文档生成演示
维护一致的演示系列

3. Interactive Recording

3. 交互式录制

Use

record_interactive.sh

for recording live terminal sessions.

Usage:

bash

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

Recording Process:

Script starts asciinema recording
Type commands naturally in your terminal
Press Ctrl+D when finished
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

使用

record_interactive.sh

录制实时终端会话。

用法：

bash

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

录制流程：

脚本启动asciinema录制
在终端中自然输入命令
完成后按Ctrl+D
脚本通过VHS自动转换为GIF

何时使用交互式录制：

演示复杂工作流
展示真实命令输出
捕获实时交互
录制调试会话

4. Manual Tape File Creation

4. 手动创建Tape文件

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:

Copy template:

cp assets/templates/basic.tape my-demo.tape

Edit commands and timing
Generate GIF:
```
vhs < my-demo.tape
```

Consult

references/vhs_syntax.md

for complete VHS syntax reference.

为了获得最大控制权，使用模板手动创建VHS tape文件。

可用模板：

```
assets/templates/basic.tape
```
- 简单命令演示
```
assets/templates/interactive.tape
```
- 打字模拟

示例工作流：

复制模板：

cp assets/templates/basic.tape my-demo.tape

编辑命令和计时
生成GIF：
```
vhs < my-demo.tape
```

查阅

references/vhs_syntax.md

获取完整的VHS语法参考。

Workflow Guidance

工作流指导

For Simple Demos (1-3 commands)

简单演示（1-3个命令）

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"

使用自动生成快速得到结果：

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:

Create
```
demos-config.yaml
```
with all demo definitions

Run:

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

All demos generate automatically with consistent settings

创建批量配置文件并使用批量生成：

创建
```
demos-config.yaml
```
，包含所有演示定义

运行：

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

所有演示将使用一致的设置自动生成

For Interactive/Complex Workflows

交互式/复杂工作流

Use interactive recording to capture real behavior:

bash

scripts/record_interactive.sh my-workflow.gif

使用交互式录制捕获真实行为：

bash

scripts/record_interactive.sh my-workflow.gif

Type commands naturally

自然输入命令

Ctrl+D when done

完成后按Ctrl+D

undefined

undefined

For Custom Timing/Layout

自定义计时/布局

Create manual tape file with precise control:

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

创建手动tape文件以实现精确控制：

从模板开始，或使用
```
--no-execute
```
生成基础tape文件
编辑计时、添加注释、自定义布局
生成：
```
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

查阅

references/best_practices.md

获取全面指南。主要建议：

计时：

快速命令（ls, pwd）：1秒休眠
标准命令（grep, cat）：2秒休眠
重型操作（install, build）：3秒以上休眠

尺寸：

标准：1400x700（推荐）
紧凑：1200x600
演示：1800x900

主题：

文档：Nord, GitHub Dark
代码演示：Dracula, Monokai
演示文稿：高对比度主题

时长：

目标：15-30秒
最大值：60秒
复杂主题可拆分为多个系列演示

Troubleshooting

故障排除

VHS Not Installed

未安装VHS

bash

undefined

bash

undefined

macOS

brew install vhs

Linux (via Go)

Linux（通过Go）

go install github.com/charmbracelet/vhs@latest

undefined

go install github.com/charmbracelet/vhs@latest

undefined

Asciinema Not Installed

未安装Asciinema

bash

undefined

bash

undefined

macOS

brew install asciinema

Linux

sudo apt install asciinema

undefined

sudo apt install asciinema

undefined

Demo File Too Large

演示文件过大

Solutions:

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

解决方案：

缩短时长（减少休眠时间）
使用更小的尺寸（1200x600）
考虑MP4格式：
```
Output demo.mp4
```
拆分为多个较短的演示

Output Not Readable

输出内容不可读

Solutions:

Increase font size:
```
--font-size 18
```
Use wider terminal:
```
--width 1600
```
Choose high-contrast theme:
```
--theme "Dracula"
```
Test on target display device

解决方案：

增大字体大小：
```
--font-size 18
```
使用更宽的终端：
```
--width 1600
```
选择高对比度主题：
```
--theme "Dracula"
```
在目标显示设备上测试

Examples

示例

Example 1: Quick Install Demo

示例1：快速安装演示

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"

用户请求："创建一个展示npm安装的演示"

bash

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

Example 2: Multi-Step Tutorial

示例2：多步骤教程

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"

用户请求："创建一个展示使用git clone、安装和运行的项目设置演示"

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

示例3：批量生成

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

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"]

Generate all:

bash

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

用户请求："为我的CLI工具的所有功能生成演示"

创建
```
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"]

生成所有演示：

bash

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

Example 4: Interactive Session

示例4：交互式会话

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

bash

scripts/record_interactive.sh my-session.gif --theme "Tokyo Night"

用户请求："录制我交互式使用我的CLI工具的过程"

bash

scripts/record_interactive.sh my-session.gif --theme "Tokyo Night"

User types commands naturally

用户自然输入命令

Ctrl+D to finish

按Ctrl+D完成

undefined

undefined

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

auto_generate_demo.py
- 从命令列表自动生成演示
batch_generate.py
- 从YAML/JSON配置生成多个演示
record_interactive.sh
- 录制并转换交互式终端会话

references/

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

vhs_syntax.md
- 完整的VHS tape文件语法参考
best_practices.md
- 演示创建指南和最佳实践

assets/

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

templates/basic.tape
- 基本命令演示模板
templates/interactive.tape
- 交互式打字演示模板
examples/batch-config.yaml
- 示例批量配置文件

Dependencies

依赖项

Required:

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

Optional:

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

必需：

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

可选：

asciinema（用于交互式录制）
PyYAML（用于批量YAML配置）：
```
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

VHS支持多种输出格式：

tape

Output demo.gif     # GIF（默认，最适合文档）
Output demo.mp4     # MP4（长演示的压缩效果更好）
Output demo.webm    # WebM（文件体积更小）

根据使用场景选择：

GIF：文档、README文件、易于嵌入
MP4：较长演示、质量更好、体积更小
WebM：网页优化、文件体积最小

Summary

总结

This skill provides three main approaches:

Automated (
```
auto_generate_demo.py
```
) - Quick, easy, smart defaults
Batch (
```
batch_generate.py
```
) - Multiple demos, consistent settings
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.

此技能提供三种主要方法：

自动生成 (
```
auto_generate_demo.py
```
) - 快速、简单、智能默认设置
批量生成 (
```
batch_generate.py
```
) - 多个演示、一致的设置
交互式录制 (
```
record_interactive.sh
```
) - 实时录制、真实输出

选择最适合用户需求的方法。对于大多数情况，自动生成是最快、最便捷的选项。