Guide · Open source

How to use VHS: write terminal GIFs as code

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

VHS is a command-line tool from Charmbracelet that turns a plain text script, called a tape file, into a GIF or video of a terminal session. This guide shows you how to install it, write a short tape, render it, and use the record, publish and server features described in the project's README. By the end you will be able to produce a repeatable terminal demo from a text file.

VHScharmbracelet/vhs · ★ 21.2k · MIT Install options & downloads

Quick start

1Install ttyd and ffmpeg. Make sure both programs are installed and on your PATH before installing VHS.
2Install VHS. Use brew install vhs on macOS or Linux, or go install github.com/charmbracelet/vhs@latest.
3Create a tape. Run vhs new demo.tape and open the file in your editor.
4Write commands. Add an Output line, optional Set settings, then Type, Enter and Sleep commands.
5Render. Run vhs demo.tape to generate the file named in Output.
6Share or automate. Use vhs publish to host the GIF, or run it in tests and CI using the same tape.

Install VHS and its requirements

VHS needs two other programs, ttyd and ffmpeg, installed and available on your PATH. The README states this requirement directly, so install both before VHS.

macOS or Linux with Homebrew: brew install vhs
Go users: go install github.com/charmbracelet/vhs@latest
Arch Linux: pacman -S vhs
Windows with scoop: scoop install vhs or winget install charmbracelet.vhs
Docker: the README lists a ghcr.io image that includes dependencies

brew install vhs

Create and write a tape file

Generate a starter tape with vhs new, then open it in your editor. A tape file is a list of commands that VHS performs on its virtual terminal. Settings such as Output, FontSize, Width and Height go at the top of the file.

Output demo.gif sets where the render is written; you can list several outputs
Set FontSize, Set Width and Set Height configure the terminal
Type "..." emulates typing, Enter presses return, Sleep pauses for a time
Settings must appear at the top; the README notes that a setting after a non-setting command is ignored (except TypingSpeed)

vhs new demo.tape
vim demo.tape

Render the tape into a GIF

Run VHS with your tape file as the argument. When it finishes, the file named by Output appears in the current directory. The README example below writes demo.gif with a 1200x600 terminal and a 46px font.

Output demo.gif

Set FontSize 46
Set Width 1200
Set Height 600

Type "echo 'Welcome to VHS!'"
Sleep 500ms
Enter
Sleep 5s

Use Require, Output formats and Wait

Require lists programs that must be on your PATH, so the tape fails early if one is missing. Output can also produce MP4, WebM or a directory of PNG frames. The Wait command pauses until a regular expression matches the screen, which helps with timing.

Require gum and Require glow must appear at the top of the tape
Output out.gif, Output out.mp4, Output out.webm and Output frames/ are all listed in the README
Wait[+Screen][+Line] /regex/ waits for a specific condition

Require gum
Output out.mp4

Record a tape instead of writing one

If you prefer to perform the actions first, VHS can record your terminal session into a tape file. Type exit to stop recording, then edit the generated file to add settings and render it.

Record: vhs record > cassette.tape
Render: vhs cassette.tape

vhs record > cassette.tape
vhs cassette.tape

Publish or self-host VHS

vhs publish uploads a GIF to vhs.charm.sh and returns links for browser, HTML and Markdown sharing. VHS also includes an SSH server started with vhs serve; the README lists its settings as environment variables such as VHS_PORT (default 1976) and VHS_HOST (default localhost). Run vhs manual for the full command reference.

Publish: vhs publish demo.gif
Serve: vhs serve, then ssh vhs.example.com < demo.tape > demo.gif

vhs publish demo.gif

What people use it for

Adding an animated terminal demo to a project README
Keeping CLI examples current by regenerating the GIF from a script
Running integration tests on command-line programs with visual output
Recording a starter session with vhs record and then editing the tape

Frequently asked questions

How do I install VHS?

On macOS or Linux with Homebrew, run brew install vhs. You can also use go install github.com/charmbracelet/vhs@latest or a package manager such as pacman or scoop. In every case, ttyd and ffmpeg must also be installed and on your PATH.

What are the requirements for VHS?

The README says VHS requires ttyd and ffmpeg to be installed and available on your PATH. The project's Docker image includes these dependencies, so it is an option if you do not want to install them yourself.

Is VHS free to use?

VHS is released under the MIT licence, as stated in the repository. Check the LICENSE file in the repository for the full terms.

What are the alternatives to VHS?

The analysis lists asciinema, terminalizer and termtosvg as comparable projects. VHS differs in that you write a text tape file and render it, rather than only recording a session.

Can VHS record my whole screen as a video?

No. VHS records a virtual terminal, not the desktop. If you need ordinary screen video, a screen recorder is a better fit.

How do I fix a tape that does not run?

Check that ttyd and ffmpeg are installed and on your PATH, and use Require at the top of the tape to fail early when a program is missing. Also make sure Settings appear before other commands, because later settings are ignored.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

VHS suits developers and CLI maintainers who want repeatable terminal demos or integration tests that are written as code and easy to regenerate. If you need a graphical editor or plain screen capture, pick another tool, and be prepared to install ttyd and ffmpeg first.

Install options & downloads