Docs & Knowledge · daymade/claude-code-skills

cli-demo-generator

Name: cli-demo-generator
Author: daymade/claude-code-skills

Generates professional animated CLI demos as GIFs using VHS terminal recordings. Handles tape file creation, self-bootstrapping demos with hidden setup, output noise filtering, post-processing speed-up, and frame-level verification. Use when users want to create terminal demos, record CLI workflows as GIFs, generate animated documentation, build demo tapes for README files, or need to showcase any command-line tool visually. Also triggers on "record terminal", "VHS tape", "demo GIF", "animate my CLI", or any request to visually demonstrate shell commands.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The core of automated generation is translating a list of commands into a VHS tape file (Output/Set Theme/Set FontSize/Type/Enter/Sleep...), which is then passed to vhs to render into a GIF.

cli-demo-generator/scripts/auto_generate_demo.py

tape_lines = [ f'Output {output_gif}', f'Set Theme "{theme}"', f'Set FontSize {font_size}', f'Set Width {width}', f'Set Height {height}', f'Set Padding {padding}', 'Set TypingSpeed 10ms', 'Set Shell zsh', '', ]

What happens here: A VHS tape is a keystroke-by-keystroke script—each step types a command with Type, presses Enter, and uses Sleep to control pacing; Set Shell zsh determines which shell runs in the recorded terminal. The generator structures "what commands to demonstrate" into a recording script, eliminating the need to write tape files by hand.

Recording is live execution: Without --no-execute, main() directly calls vhs via subprocess, and the commands in the tape are genuinely typed and executed inside the vhs pseudo-terminal.

cli-demo-generator/scripts/auto_generate_demo.py

subprocess.run(['vhs', str(tape_file)], check=True)

This means the recording is not a "drawn fake terminal" but the actual execution process of the commands (real outputs and exit codes)—hidden commands like cleanup/install in self-bootstrapping demos are also actually executed, which is precisely why self-bootstrapping can "clean up its own state."

Workarounds for VHS parser limitations: Type strings cannot contain $, double quotes, or backticks; complex commands are base64-encoded first and decoded for execution at runtime.

cli-demo-generator/SKILL.md

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

SKILL.md provides the standard pattern of base64-encoding an entire shell segment (such as an output filter wrapper function with 2>&1 | grep -v), writing it as 'echo <b64> | base64 -d > /tmp/wrapper.sh && source /tmp/wrapper.sh', and then passing it into Type. The --filter branch in auto_generate_demo.py handles this automatically internally (wrapper = _wrap() {...grep -v -E "filter"...} → base64 → written to /tmp/cw.sh and sourced).

"Audience perspective" orchestration for bootstrapping and noise filtering: The Hide block runs setup/cleanup → clear wipes the screen → Show is called before starting to record the commands meant for the audience.

cli-demo-generator/scripts/auto_generate_demo.py

tape_lines.append('Hide') … tape_lines.append('Show')

SKILL.md emphasizes: 'The `Hide` → commands → `clear` → `Show` sequence is critical. `clear` wipes the terminal buffer so hidden commands don't leak into the GIF.' Hidden and visible segments share the same live shell, and screen clearing ensures the final output contains only what is intended to be displayed.

Smart pacing: Context-aware Sleep durations based on command semantics (install/build/test/deploy → 3s, ls/pwd/echo, etc. → 1s, others → 2s); gifsicle can be used for post-processing speed adjustments after recording.

cli-demo-generator/scripts/auto_generate_demo.py

if any(kw in cmd.lower() for kw in ['install', 'build', 'test', 'deploy', 'marketplace']): sleep_time = '3s' elif any(kw in cmd.lower() for kw in ['ls', 'pwd', 'echo', 'cat', 'grep']): sleep_time = '1s' else: sleep_time = '2s'

speed_up_gif uses gifsicle to modify frame delays: 'subprocess.run(['gifsicle', f'-d{delay}', tmp, '#0-'], stdout=out, check=True)', delay = 10 // speed. It first copies to /tmp and writes back to avoid corrupting the original recording.

Three additional modes: Batch configuration (batch_generate.py reads YAML/JSON and invokes the auto script iteratively), interactive recording (asciinema records live sessions → converted to tape → rendered by vhs), and manual/template tape editing (assets/templates + placeholder replacement).

cli-demo-generator/scripts/batch_generate.py

cmd = [sys.executable, str(script_path)] for command in commands: cmd.extend(['-c', command])

batch_generate rebuilds the argv for auto_generate_demo for each demo entry (-c commands can be repeated). YAML parsing depends on optional PyYAML (prints a prompt and exits if missing); record_interactive.sh runs 'asciinema rec "$CAST_FILE"', converts the cast file to a tape, and executes 'vhs < "$TAPE_FILE"'.

2Core Capabilities

01Full automation from command lists to finished GIFs (auto_generate_demo.py -c/-o, including title, theme, and dimension parameters)

02Self-bootstrapping demos: --bootstrap hides setup/cleanup commands, allowing the demo to restore its own initial state

03Output noise filtering (--filter regex; base64-wrapped _wrap function filters at runtime)

04gifsicle post-processing speed-up (--speed N, modifies frame delays without re-recording)

05Batch generation (demos.yaml/json → per-demo GIF generation, supports parallelism and optional arguments)

06Interactive human recording (asciinema rec → cast-to-tape conversion → vhs, ended with Ctrl+D)

07Frame-level verification: ffmpeg extracts keyframes as PNGs for Claude or the user to inspect and verify GIF content

08Manual tape authoring and templates (basic/interactive/self-bootstrap.tape) with placeholder replacement (sed injects detected repository names)

3External Dependencies

Kind	Dependency / Endpoint
cli	vhs（charmbracelet，必需）
cli	gifsicle（可选，变速）
cli	asciinema（可选，交互录制）
cli	ffmpeg/ffprobe（可选，抽帧验证）
package	PyYAML（可选，batch YAML 配置）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Executes local scripts or commands: cli-demo-generator/scripts/auto_generate_demo.py (internally executes vhs/gifsicle/cp)
本地工作目录: File read/write and artifact output: Writes generated GIF/tape files to user-specified -o paths

Audit Notes: Includes built-in stdlib local scripts and local CLIs (vhs/gifsicle/asciinema/ffmpeg), with zero external network requests and zero credential reads; writes local GIF/tape/temporary files with no destructive built-in operations. Key consideration: Recording involves real execution of user-supplied commands—this is intrinsic to the skill's functionality (demo commands must run in a real terminal to produce authentic output). The execution attack surface matches the host's own bash environment, presenting no hidden risks. However, users must manage quote boundaries for filter regexes and command strings, while VHS parser limitations are avoided via base64 encoding.

5Second-Pass Verification

[ok] 自带脚本零网络外发 — scripts/ 三文件 token 扫描（URL/curl/wget/requests/urllib/socket/API_KEY/token/secret/os.system）零命中；子进程仅 vhs/gifsicle/cp/asciinema/sed。
[ok] 执行面：tape 命令真实执行 — auto_generate_demo.py 主流程 subprocess.run(['vhs', str(tape_file)])；tape 中 Type+Enter 在 vhs 终端内被 shell 执行（VHS 工具行为）。
[ok] --filter 的 base64 包装实现 — wrapper f-string + base64.b64encode + 'echo <b64> | base64 -d > /tmp/cw.sh && source /tmp/cw.sh' 在 create_tape_file 中逐字存在。
[ok] 变速后处理（gifsicle delay = 10//speed） — speed_up_gif 内 gifsicle -d{delay} tmp '#0-' 且先 cp 到 /tmp 再写回，与 SKILL.md 手写 gifsicle 命令一致。
[ok] 自举/隐藏命令防泄漏（Hide→clear→Show） — create_tape_file 在有 bootstrap/filter 时依次 append Hide/Type/Enter/Sleep/Type "clear"/Show；SKILL.md 有同序说明。
[ok] 批处理与交互模式调用链成立 — batch_generate 重建 auto_generate_demo argv（-c 循环）；record_interactive.sh 走 asciinema rec → 写 tape → vhs < tape。
[ok] 功能声明 vs 夸大检查 — description 八项能力全部有代码/SKILL.md 支撑；无越界承诺。依赖标注（VHS 必需、gifsicle/asciinema/ffmpeg/PyYAML 可选）与脚本内降级提示一致。
[ok] 元数据（license/stars/commit） — 仓库级 MIT、stars=1385、pushed_at=2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678cb5d4fd6acc9c922690df035dbd33d247。

6Verdict & Scenarios

A single command transitions from "a list of commands to demo" to a finished GIF, with real execution during recording—ensuring credible output suitable for READMEs.

Systematically documents and automates workarounds for VHS ecosystem quirks (parser special characters, timing, hidden command leakage via base64, semantic pacing, and clear).

Self-bootstrapping demos and noise filtering address real-world needs: reproducible recordings and clean outputs for long-output commands, ideal for plugin and CLI promotional assets.

Graceful degradation for optional dependencies: prints hints to continue or explicitly reports failures when gifsicle/asciinema/PyYAML are missing, without masking errors.

Multi-tier flexibility combined with frame-level quality inspection, balancing automation efficiency with pixel-perfect requirements.

Best for: Suitable for: Developers needing README GIFs or demo assets for CLI tools, plugins, or scripts; creating reproducible, self-cleaning installation/usage demos (self-bootstrapping); automated documentation pipelines that batch-generate images from command lists; and production scenarios requiring frame-level precision (keyframe extraction inspection, post-recording speed adjustment).

Not for: Not suitable for: Scenarios where demo commands contain sensitive output or untrusted third-party command strings (recording equals live execution); simulated typing needs where typing aesthetics take precedence over authentic execution (pure script-typing simulators should be used instead); environments lacking vhs (Linux requires installing the charmbracelet tap) or users unwilling to install third-party recording CLIs; and scenarios where the demo must not produce real side effects (such as actual npm install executions).

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload cli-demo-generator.tar.gz

sha256: 9991cfcecc32bad8…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.