record-tui

Record TUI — VHS Terminal Recording

Overview

Charmbracelet VHS renders a .tape script to GIF / MP4 / WebM / ASCII. Write the demo as code rather than capturing a screen, because a .tape re-renders unattended when the app changes and runs the same way in CI. For a throwaway recording nobody will re-run, asciinema is lighter.

Setup

# macOS
brew install charmbracelet/tap/vhs ffmpeg ttyd
# Debian/Ubuntu
sudo apt install ffmpeg && sudo snap install ttyd --classic && go install github.com/charmbracelet/vhs@latest

vhs --version && ffmpeg -version && ttyd --version   # all three are required

Tape file structure

Every Set goes above the first interaction command. A Set placed lower is silently discarded — see Gotchas.

Output demo.gif              # 1. output (gif/mp4/webm/ascii)
Require my-app               # 2. fail fast if the app is missing

Set Shell "bash"             # 3. settings, all grouped before any command
Set FontSize 20
Set Width 1200
Set Height 600
Set Theme "Catppuccin Frappe"
Set WindowBar Colorful
Set Padding 20
Set TypingSpeed 75ms

Hide                         # 4. hidden setup — Ctrl+L before Show
Type "export TERM=xterm-256color"
Enter
Sleep 500ms
Ctrl+L
Show

Type "my-app --demo"         # 5. visible interactions, with deliberate pauses
Sleep 500ms
Enter
Sleep 2s
Down 3                       # 6. app interaction
Enter
Sleep 3s                     # generous final frame before the loop restarts

Quick reference

Command	Purpose
`Output file.gif`	Output file + format (gif/mp4/webm/ascii); repeat for several formats
`Require app`	Fail if the program is not on PATH
`Set Key Value`	Terminal settings (FontSize, Width, Height, Theme, Framerate, …)
`Type "text"` / `Type@100ms "text"`	Emulate typing (optionally at a per-line speed)
`Enter` / `Tab` / `Space` / `Escape`	Key presses
`Up`/`Down`/`Left`/`Right` (`Down 3`)	Navigation with optional repeat count
`Ctrl+key`, `Alt+key`, `Shift+key`	Modifier combos
`Sleep 2s`	Fixed pause (ms or s)
`Wait+Screen@30s /regex/`	Block until screen content matches, with a timeout
`Hide` / `Show`	Control recording visibility (execution continues either way)
`Screenshot file.png`	Capture the current frame
`Env VAR "val"` / `Source other.tape`	Set an env var / include another tape

vhs validate demo.tape    # parse-check, no rendering
vhs demo.tape             # record
vhs themes                # list themes
vhs new demo.tape         # scaffold from template

Full command + settings detail: reference/COMMAND-REFERENCE.md.

Use case	Width	Height	FontSize
README GIF	1200	600	20
Docs/tutorial	1400	800	18
Social media	1200	630	22
Full TUI app	1600	900	16
Compact CLI	800	400	20

Recording a tape for an app

Read the app's --help output or its source to learn how it launches, which keys it responds to, and which states are worth showing. Draft a tape covering those states, then vhs validate demo.tape → vhs demo.tape → watch the rendered file → adjust. Watching is the step that matters: validation parses syntax and cannot tell you the demo outruns the viewer.

Bound the demo before drafting: a README GIF shows one workflow in 10–30 seconds — three to five states, each held long enough to read (Sleep 2s–3s). Past 30 seconds, cut states or split into a second tape rather than adding scenes; a demo that shows everything shows nothing, and the GIF size grows with it.

Copy-paste starting points (Basic CLI, Interactive TUI, Build-and-Run, Multi-Panel, CI golden file, composable Source tapes): reference/TEMPLATES.md.

Examples

✅ Output first, settings grouped above the commands, Require guarding the binary, a pause after typing and a long final frame:

Output demo.gif
Require my-app

Set Shell "bash"
Set FontSize 20
Set Width 1200
Set Height 600

Type "my-app status"
Sleep 500ms
Enter
Sleep 3s

❌ Same tape, three defects — Set Width lands after Type and is dropped, nothing separates typing from execution, and a missing binary produces a confusing empty GIF instead of an error:

Output demo.gif

Type "my-app status"
Enter
Set Width 1200

✅ Pacing a TUI whose startup time varies — wait on a screen match instead of guessing a Sleep:

Type "my-tui"
Enter
Wait+Screen@30s /Ready/
Down 3
Sleep 500ms
Enter
Sleep 3s

Gotchas

A Set below the first command is silently dropped, and vhs validate still exits 0. Verified on vhs 0.11.0: Set FontSize 40 after a Type rendered at the default size, and the same holds for Set TypingSpeed — there is no per-setting exception. Keep every Set above the first Type/key command and confirm by watching the output, because nothing in the toolchain reports this. To vary typing speed mid-tape, use the per-line Type@100ms "…" form.
vhs validate only parses. It never launches the app, so a missing binary, a wrong keybinding, or a demo that races ahead of the app all pass. Add Require <app> so a missing dependency fails loudly rather than rendering an empty terminal.
Type "cmd" does not press Enter. Follow it with an explicit Enter, and put Sleep 500ms between them so the viewer can read the command before it runs.
Hide hides output, not execution. Commands inside a Hide block still run. End the block with Ctrl+L before Show so leftover setup output doesn't open the recording.
Wait times out. Raise it per command (Wait+Screen@30s /ready/) or globally (Set WaitTimeout 30s) for a slow-booting TUI, rather than padding with a longer Sleep that will still be wrong on a slower machine.
VHS records in a fresh shell, so your prompt customizations are absent. Pin Set Shell "bash" to get the same prompt on your machine and in CI.
A TUI that renders with wrong colors or wrapping is usually a terminal-setup problem. Pin it in the Hide block: Env TERM "xterm-256color" plus Type "stty rows 50 cols 120".
GIFs cross 5 MB quickly. GitHub renders them inline, but the README crawls. Try Set Framerate 15 first — it is the cheapest win and costs little perceived smoothness — then gifsicle -O3 --lossy=80, and switch to MP4 before shrinking dimensions past readability.

Optimize & CI

Size reduction, playback tuning, and the GIF-vs-MP4-vs-WebM decision tree: reference/OPTIMIZATION.md. Recording in GitHub Actions, plus ASCII output as a golden file for UI regression tests: reference/CI-INTEGRATION.md.

Integration

Pairs with build-tui — record the TUI right after building it, and commit the .tape next to the source so the GIF regenerates with the app. Use screenshot-local instead when the target is a web UI on localhost.

External: VHS · VHS Action · examples · themes · gifsicle.