Vhs Terminal Recorder

VHS Terminal Recorder

When to use

Use this skill only when vhs or Charmbracelet VHS is actually the right surface:

• user says vhs, Charmbracelet VHS, .tape, terminal GIF, terminal recording, command-line screencast, or scripted terminal demo
• docs need a reproducible recording of CLI behavior
• an existing VHS tape needs authoring, validation, rendering, or debugging

Do not use it for arbitrary desktop capture, browser product tours, video editing, or one-off interactive work that cannot be made deterministic. Use a video/screen-capture workflow instead when the subject is not a terminal.

Mental model

VHS runs a tape file in a pseudo-terminal and renders the terminal session to GIF, MP4, or WebM. Treat a tape like a small executable test:

• the tape must create or point at deterministic state
• commands shown to viewers should be short and intentional
• setup belongs behind Hide / Show
• vhs validate checks tape syntax but does not prove the commands work
• vhs <file> executes the tape and can mutate files, hit the network, or run project commands

This skill is not the VHS language reference. For exact syntax, generate or inspect live docs:

vhs --help
vhs manual
vhs new /tmp/example.tape
vhs validate /tmp/example.tape

Setup and verification

VHS is the Charmbracelet CLI from https://github.com/charmbracelet/vhs. Before depending on it, verify the local binary and help:

vhs --version
vhs --help

Use command-specific help for current flags:

vhs record --help
vhs validate --help
vhs publish --help

Rendering also depends on the local VHS render stack, especially ttyd and ffmpeg. If vhs validate passes but rendering fails before running the tape, check those binaries before changing tape logic.

If vhs is missing and the user wants it installed, prefer the upstream-supported package manager for the current machine. The common macOS/Linux path is:

brew install vhs

For Windows, Arch, Nix, Docker, Debian/RPM packages, or Go source installs, use the upstream installation section instead of copying commands from memory: https://github.com/charmbracelet/vhs#installation

First render can be slow because VHS may initialize browser/rendering caches. Do not misdiagnose that as a bad tape until validation passes and the render actually fails.

Authoring rules

Start from a hand-written tape for agent-created demos. Use vhs record only as a rough draft, then clean the tape before committing it.

Keep tapes deterministic:

• keep Output, Require, and most Set commands at the top of the tape before visible actions; VHS docs call out top-of-file ordering for dependencies and settings
• set Output, Set Shell, Set Width, Set Height, Set FontSize, Set TypingSpeed, and Set Theme explicitly
• add Require <program> for every external command the tape depends on
• create fixtures or temp files in hidden setup instead of relying on the user's current shell state
• prefer fake/sample values over real accounts, tokens, private paths, or production URLs
• constrain noisy commands with flags, known fixtures, or small output windows
• keep Type lines simple; put complex setup in a script or separate hidden commands instead of relying on nested quotes or command substitution
• use Wait+Screen@<timeout> /pattern/ or Wait@<timeout> /prompt-or-line/ for readiness; reserve Sleep for presentation timing after readiness has happened
• when waiting on a server, file watcher, or network dependency, prefer a hidden shell readiness loop or a visible command followed by a VHS Wait+Screen; do not rely on a bare fixed sleep

Minimal skeleton:

Output demo.gif

Require bash
Require your-cli

Set Shell "bash"
Set Width 1200
Set Height 700
Set FontSize 28
Set Theme "Builtin Dark"

Hide
Type "mkdir -p /tmp/vhs-demo && cd /tmp/vhs-demo"
Enter
Type "your-cli init --fixture small >/dev/null"
Enter
Show

Type "your-cli status"
Enter
Wait+Screen@5s /ready|ok|complete/
Sleep 1s

Best-practice scenarios

Create a docs GIF. Author a tape beside the docs or examples it supports, use a small deterministic fixture, validate it, render it, then inspect the output file before reporting success:

vhs validate docs/demo.tape
vhs docs/demo.tape

Render another format. Prefer GIF for lightweight README embeds. Use MP4 or WebM when quality or file size matters:

Output demo.mp4
Output demo.webm

Use Output frames/ for a PNG sequence when post-processing is needed. Use text outputs such as Output golden.ascii only for integration-test/golden-file workflows, not as the normal docs artifact.

Choose a theme. Do not guess theme names from memory. List them and copy the theme string exactly:

vhs themes
vhs themes --markdown

Validate several tapes. Quote globs so the shell does not expand or reject them before VHS sees the pattern, especially in zsh:

vhs validate 'docs/*.tape'

Debug a failing tape. Validate first. If validation passes, run each viewer-facing command directly in a clean shell or temp directory. Most VHS failures are ordinary command failures hidden inside a recording.

Use recording mode. Reach for vhs record only to capture an exploratory interaction or learn a rough sequence. Rewrite the result into a short scripted tape with hidden setup, explicit dimensions, and no accidental local state.

Safety and publishing

Rendering executes the tape. Read untrusted tapes before running them.

Never capture or publish secrets. Before rendering or committing, scan the tape for tokens, real customer data, private paths, .env output, shell history, git remotes, and account-specific prompts.

Publishing uploads a GIF to vhs.charm.sh. Treat it as an external side effect: only run vhs publish <file>.gif or vhs <file> --publish when the user has explicitly approved that exact file for public sharing.

Pitfalls

• vhs validate is parse-only; it does not run Require checks or prove the demo commands succeed.
• Unquoted globs can fail in the shell before VHS runs.
• Long command output makes unreadable recordings. Shrink the scenario instead of increasing terminal height until everything fits.
• Nested quoting and shell command substitution inside Type lines can produce confusing parse errors. Simplify the line or move setup into a small script.
• Plain Wait /pattern/ watches the current line. Use Wait+Screen /pattern/ when matching command output anywhere on the terminal.
• VHS supports useful commands beyond the common demo path, including Screenshot, Source, Copy, Paste, and version-dependent Env; check vhs manual before using them, and never use Env as a way to smuggle real secrets into recordings.
• Default shell, prompt, theme, size, and font can vary by machine. Set the recording surface explicitly.
• Sleep hides races in the final video. Use hidden readiness checks for anything that depends on a server, file watcher, background job, or network.
• Do not commit generated videos unless the repo expects binary demo assets. If unsure, ask before adding large GIF/MP4/WebM files to version control.