Introduction to VHS

VHS allows users to generate terminal GIFs programmatically using code. Instead of manually recording a screen and hoping for no typos, you write a script that defines what should happen in a virtual terminal. This approach is highly reproducible and especially useful for integration testing or demoing CLI tools in documentation.

Prerequisites and Installation

To run VHS, users must have ttyd and ffmpeg installed on their system, as these dependencies handle the terminal emulation and video rendering. Once those are in your $PATH, you can install VHS through various package managers.

For instance, on macOS or Linux, you can use Homebrew with brew install vhs. You can refer to the official repository for other installation methods.

Creating and Running a Tape

A .tape file contains a sequence of instructions such as typing commands, pressing keys, or waiting. These commands tell the VHS virtual terminal exactly what to execute, how fast to type, and when to pause.

Users can start a new project by generating a blank tape file using the vhs new command:

Once the tape file is generated, you can open it in your preferred text editor. Inside, you can specify settings like Set FontSize 46 or Set Width 1200, followed by interaction commands like Type or Sleep.

For example, a simple script might look like this:

After finalizing your script, you feed it back into VHS to produce the GIF:

Advanced Recording Features

Sometimes writing out a script manually can be tedious. VHS can record terminal actions directly into a tape file for later editing. By running the record command, VHS captures your live keystrokes and timing:

Once finished, you can open cassette.tape to tweak the timings or fix any mistakes before rendering the final output.

In addition, developers can hide setup and cleanup steps from the final rendering. The Hide command instructs VHS to stop capturing frames. It's useful to pause a recording to perform hidden commands. This is particularly handy for compiling binaries or authenticating before the visible demonstration begins. You can resume recording frames by running Show.

When you're ready to share your creation, VHS includes a publish feature:

This uploads the GIF to Charm's servers and provides a shareable URL, making it easy to embed in pull requests or markdown files.