vhs-cli-demos · git:20260605.b381c04 · 2026-06-05 · sha256 ab6aefa14d543963
vhs-cli-demos git:20260605.b381c04A
Immutable. This exact content never changes and is served at /api/v1/blob/ab6aefa14d543963.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_hwsqan3xuyezafoz/ab6aefa14d543963281db80a555573d2bb34955f437ceabf51acee0610ac5129.json
Then /plugin install vhs-cli-demos@markdownregistry-hwsqan3xuyezafoz in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: vhs-cli-demos description: >- Generate deterministic screenshots and demo GIFs of command-line and terminal (TUI) applications using Charm VHS. Use this skill whenever the user wants to capture, record, screenshot, or make a GIF/video of a CLI or terminal app — for a README, docs site, marketing page, changelog, release notes, or visual regression tests. Trigger on phrases like "record a gif of my CLI", "demo gif for the README", "screenshot my terminal app", "capture the TUI", "make a terminal recording", "VHS tape", "charm vhs", "asciinema but as a gif", or any request to show a terminal program in motion or as a still — even when the user doesn't name VHS. Also use when a captured GIF is too large and needs to be shrunk for the web, or when setting up a repeatable capture pipeline for many scenes. Covers install, authoring tapes, determinism, motion-GIF storytelling, and the lossless size-optimization that makes GIFs web-viable. --- # Capturing CLI & TUI apps with VHS [VHS](https://github.com/charmbracelet/vhs) (by Charm) drives a real PTY through a headless terminal and records exactly what a user would see — so captures are pixel-accurate, scriptable, and reproducible in CI. It's the right tool for README GIFs, docs/marketing stills, release demos, and terminal visual-regression tests. This skill is the methodology; it transfers to any CLI or TUI regardless of language (Go, Rust, Python, Node, a shell script — VHS only sees the terminal). The single most important thing to internalize: **a `.tape` is a screenplay, not a config file.** You're directing a short scene — what's typed, how long each beat holds, when the camera clicks. Two failure modes dominate, and both are covered below: captures that look *wrong* (loading spinners, drifting dates, empty state — a determinism problem) and GIFs that are *enormous* (10-20 MB — a file-size problem with a one-line lossless fix). ## The essentials (if you read nothing else) Three things separate a capture that ships from one that embarrasses you. Get these right and the rest is polish: 1. **Always optimize GIFs losslessly.** Raw VHS GIFs are 10-20 MB of redundant frames. Run `gifsicle -O3` (lossless, 20-30× smaller, zero quality loss) — via the bundled `scripts/optimize_gif.sh` — or bake it into your pipeline. Never ship a raw VHS GIF, and never reach for lossy compression as the default fix. 2. **Make it deterministic — and let VHS size the canvas.** Pin the clock, lock the theme, pick a readable `FontSize`, and settle long enough for cold-start. Do **not** hand-compute `Set Width`/`Set Height` to pixel-fit a column count — VHS's defaults render crisply, and a mismatched canvas stretches the glyphs (spaced-out, broken-looking kerning). (See Determinism.) 3. **Use the right output.** `Screenshot file.png` for a single still; `Output file.gif`/`.mp4` for motion. `Output file.png` is a trap — it records a frame *sequence*, not an image. Everything below explains the *why* and the edge cases. When in doubt, those three are the load-bearing ones. ## When to read which reference Keep this body in context for the workflow and the hard-won lessons. Load a reference only when you reach that step: - **`references/tape-reference.md`** — the full VHS tape DSL (`Set`, `Type`, `Sleep`, `Key`, `Hide`/`Show`, `Output`, `Screenshot`, `Source`, `Require`), output formats (gif/mp4/webm/png), and complete annotated example tapes for both a still and a motion demo. Read it when authoring a non-trivial tape or when you need a command you don't remember. - **`references/recipe-catalog-pattern.md`** — how to graduate from hand-written one-off tapes to a generated *recipe catalog* + driver when a project needs many captures kept in sync (the pattern behind a mature pipeline: typed recipe list, scenario fixtures, theme-palette mapping, a sync step to a docs/site folder). Read it when the user has more than a handful of captures or wants a repeatable `npm run screenshot`-style workflow. ## Setup ```bash brew install vhs # also available via Go, Nix, apt, scoop, docker # VHS needs ffmpeg (and ttyd) for video/gif encoding — brew pulls them in. brew install gifsicle # for the lossless GIF optimization step (below) ``` Verify with `vhs --version`. If `vhs new demo.tape` errors about ttyd/ffmpeg, install those explicitly (`brew install ttyd ffmpeg`). ## The core workflow 1. **Pick the output**: a still PNG (`Screenshot`) or a motion GIF (`Output foo.gif`). Stills are for docs/feature shots; GIFs for workflows in motion. 2. **Write the tape** — the scene. Start from `vhs new demo.tape` or the annotated examples in the tape reference. 3. **Make it deterministic** — pin time, lock the theme, pick a readable font size, give the app time to settle (see Determinism). This is what separates a capture you can regenerate from one you got lucky with once. 4. **Render**: `vhs demo.tape`. Inspect the output. Iterate on timing. 5. **For GIFs, optimize losslessly** — run `scripts/optimize_gif.sh out.gif` (or wire `gifsicle -O3` into your pipeline). This is not optional for the web. ## Determinism — the thing that makes captures reusable A capture is only useful if it looks identical every run. Control the sources of drift up front: - **Wall-clock / relative dates.** Anything that renders "3 days ago" or today's date will drift between runs. If the app honors an env var or flag for a fixed "now" (many do for exactly this reason), set it in the tape via `Env` or an exported variable. If it doesn't, consider adding one — it's the cleanest fix. - **Sizing — pick a `FontSize`, then leave the canvas alone.** This is the one that bites: VHS sizes the output from `Set Width`/`Set Height` in *pixels*, but the terminal renders a *character grid* whose cell size comes from the font. If you hand-pick a Width/Height that doesn't land on an exact whole number of cells for the actual font metrics, the renderer **stretches the glyphs to fill the canvas** — the result looks spaced-out, with broken kerning. Don't try to pixel-fit a cols×rows target. Instead: set a readable `FontSize` (≈18-22) and **omit `Width`/`Height` so VHS uses its known-good defaults (1200×600)**, which render crisply. Only set explicit dimensions when you need a specific canvas across a set of captures — and then use round numbers with a comfortable font, and *look at the output* to confirm the glyphs are tight, never trust a cols×multiplier formula. (Determinism is preserved either way: same FontSize + same content → same render.) - **Lock the theme.** Pass the app's theme flag and set VHS's terminal palette to match (`Set Theme`). Don't rely on ambient terminal colours. - **Disable animations during the shot.** Spinners, idle-tip rotations, blinking cursors (`Set CursorBlink false`) all introduce frame-to-frame noise. Wait for loading states to settle before the `Screenshot`. - **Settle for interpreter cold-start.** Inside VHS the app boots in a *fresh* process; interpreted runtimes (tsx/ts-node, Python, a slow node entrypoint) can take 2-3s to cold-start versus ~500ms warm, plus any async data load. If shots show "loading…" or empty state, the fix is almost always **more sleep before the first capture**, not a different command. ## VHS shell-environment gotchas VHS spawns a clean shell that does **not** inherit your parent environment. These bite everyone once: - **Unquoted `$PATH` in exports.** `Type` types literal characters. If you write `Type "export PATH='...:$PATH'"`, the single quotes make bash treat `$PATH` as a literal string and the shell loses `git`, `sleep`, and friends. Export with the value unquoted so `$PATH` expands: `export PATH=/your/bin:$PATH`. - **Forward the env you need.** API keys, tokens, or config the app reads aren't present in the VHS shell. Export them inside the tape (use `Hide`/`Show` so the export lines don't appear on camera) or pass them through your driver. - **`Screenshot` vs `Output`.** `Output "x.png"` records the *whole session* as a frame sequence (a directory) — not a single image. For one still frame use `Screenshot x.png` (bare filename). `Output "x.gif"` / `"x.mp4"` is for motion. - **cwd binding.** VHS's `cd`/`Type "cd …"` changes the shell cwd, but some apps bind their working context another way (e.g. a `--repo`/`--cwd` flag that calls `chdir` internally). Pass the explicit flag rather than trusting cwd. - **macOS temp-dir symlinks.** `/var/folders/...` is really `/private/var/...`; tools with path-safety checks (e.g. git's `safe.directory`) can trip on the symlinked form. Resolve the real path before handing it to the app. ## Stills (PNG) Keep them boring and crisp: launch, **settle generously** (a still has no second chance — a few seconds is fine, you only emit one frame), drive any keystrokes to reach the state you want, hold briefly, then `Screenshot name.png`. One scene per still. If the image looks wrong, increase the settle before reaching for anything else. ## Motion GIFs — direct a short story A GIF is a screenplay. The discipline that makes them good (and small): - **One story per demo.** Make a single point and stop. "The list changes per view" → show it on two views, done. Resist tacking on extra beats; each one costs viewer attention *and* bytes. - **Show contrast, not completeness.** Two cases proving a behavior beats six enumerating it. Full-screen takeovers (help overlays, pickers) are tempting but dilute the point and balloon the file (see File size). - **Budget read time.** Sleep long enough to *read* each beat: ballpark ~2.5s after opening something with text to read, ~1.2s for a view/screen switch, ~0.5s between quick keystrokes. Too fast is unreadable; too slow drags and grows the file. - **Shorter settle than stills.** GIFs record from boot, so early "loading" frames read as natural startup — a ~1.5s lead-in is plenty. - **Type multi-key sequences as one action** where the app expects them together (e.g. a chord); the brief intermediate state on camera often *helps* by showing the relationship between keys. - **End on the UI, not a shell prompt.** Don't film a trailing quit/`q` — let the recording end on the last meaningful frame. If your pipeline appends a quit for stills, strip it for GIFs. ## File size — the gotcha that ships 18 MB GIFs This is the lesson that bites hardest, so it gets its own section. **VHS writes full, undeduplicated frames.** A 10-second terminal demo where almost nothing changes between frames still lands at **10-20 MB raw** — far too heavy for a web page or a README. Three levers, in order of impact: 1. **Optimize losslessly — always.** Run `gifsicle -O3` on the output. This is *lossless* inter-frame transparency optimization (no `--lossy`, no colour quantization): it rewrites only the pixels that change between frames. Typically a **20-30× reduction with zero visible difference** — e.g. a real demo went 15 MB → 0.4 MB. Use the bundled `scripts/optimize_gif.sh` (best- effort: skips with a hint if gifsicle is absent), or wire `gifsicle -O3 --batch <file>` into your capture pipeline so regenerations stay small without anyone remembering a manual step. **Do this in the pipeline, not by hand** — any "regenerate all captures" command will otherwise re-bloat everything. 2. **Trim the story.** Less duration and fewer full-screen redraws mean fewer/cheaper frames *before* optimization even runs. Cutting one unnecessary full-overlay beat took that same demo 19 MB → 13 MB on its own; gifsicle then finished the job. 3. **Shrink dimensions — last resort.** Fewer pixels = smaller file, but it costs legibility and breaks visual consistency across a set of demos. Only reach for it after the first two. Rule of thumb: **author for the story and timing; let the lossless pass handle the bytes.** If a GIF is still multi-MB *after* `-O3`, the recipe is doing too much — tighten the scene rather than reaching for `--lossy` and degrading quality. (If you genuinely need lossy compression for an extreme case, make it an explicit, opt-in choice the user asked for — never the silent default.) ## Scaling up: from one-off tapes to a catalog A handful of captures can be hand-written tapes checked into `assets/` or `docs/`. Once a project needs *many* — every view, every theme, kept in sync as the UI changes — graduate to a **recipe catalog + driver**: a typed list of named scenes, a driver that spins up fixtures, generates the tape, runs VHS, and a sync step that copies web-ready assets into the docs/site. Read `references/recipe-catalog-pattern.md` for the full pattern and a reference implementation. Signs it's time: people regenerate captures by hand, shots drift out of sync with the UI, or you're copy-pasting tape boilerplate. ## Use cases - **README / docs**: a hero GIF plus per-feature stills. Keep GIFs short and optimized; stills for anything users need to read. - **Marketing site**: same captures, synced into the site's asset folder. Animate the headline workflows; use stills for grids and theme showcases. - **Visual regression**: deterministic stills are diff-able (`pixelmatch`, `odiff`) against a committed baseline. Run as a manual/release CI job, not on every push — rendering is too slow for the hot path but invaluable at release.