Repolode
Submit
charmbracelet

charmbracelet/vhs

A Go CLI that records terminal sessions into GIFs, videos or ASCII output from scripted .tape files, for demos and integration tests.

View on GitHub
Stars
21,265
Forks
493
Open issues
177
Last commit
4 days ago

What is it?

VHS treats terminal recordings as code. You write a .tape file listing commands such as Type, Enter, Sleep and Wait, and VHS replays them inside a virtual terminal and renders the result as a GIF, MP4, WebM, PNG sequence, or text/ASCII golden file. Settings cover font family and size, window dimensions or column and row counts, themes, padding, margins, window bars and playback speed.

Because the output is deterministic text input, the same tape can be rerun whenever a CLI changes to keep demos current. Text outputs can be committed to git and diffed to act as golden files in integration tests. VHS also includes a record subcommand that generates a tape from a live session, a publish command for sharing GIFs, and an optional SSH server mode for running tapes on a remote host.

VHS depends on ttyd and ffmpeg being installed on the PATH. It is installable through Homebrew, Scoop, Nix, Docker, Go, and Linux packages.

Key features

  • 01Scripts terminal sessions with a simple .tape command language.
  • 02Outputs GIF, MP4, WebM, PNG frame sequences, and text/ASCII files.
  • 03Customizes font, window size, themes, padding, margins and window bars.
  • 04Records a tape file from a live terminal session.
  • 05Produces ASCII golden files for diffing in integration tests.
  • 06Runs as an SSH server for executing tapes on a remote host.

Use cases

  • Keeping README demo GIFs up to date by regenerating them in CI.
  • Integration testing a CLI by diffing text output against golden files.
  • Creating reproducible screencasts of terminal workflows for documentation or tutorials.

Quick start

  1. 1

    Install ttyd and ffmpeg, which VHS requires on PATH

  2. 2

    Install VHS with Homebrew on macOS or Linux

    brew install vhs
  3. 3

    Create a new tape file

    vhs new demo.tape
  4. 4

    Generate the GIF from the tape file

    vhs demo.tape

Things to know

  • Requires ttyd and ffmpeg to be installed separately and available on PATH.

In collections

CLI & terminal toolsTesting frameworks & test automation toolsStatic site generators & documentation tools

Topics

#cli#terminal#gif#screen-recording#testing#golang#documentation#ascii#command-line#recording

FAQ

What is vhs?
A Go CLI that records terminal sessions into GIFs, videos or ASCII output from scripted .tape files, for demos and integration tests. VHS treats terminal recordings as code. You write a .tape file listing commands such as Type, Enter, Sleep and Wait, and VHS replays them inside a virtual terminal and renders the result as a GIF, MP4, WebM, PNG sequence, or text/ASCII golden file. Settings cover font family and size, window dimensions or column and row counts, themes, padding, margins, window bars and playback speed.
Is vhs free to use? What license does it have?
vhs is open source under the MIT license. Check the license terms before using it in commercial products.
Is vhs still maintained?
Actively maintained. The last commit to vhs was on Nov 2, 2026.
What can I use vhs for?
Keeping README demo GIFs up to date by regenerating them in CI. Integration testing a CLI by diffing text output against golden files. Creating reproducible screencasts of terminal workflows for documentation or tutorials.
How do I install vhs?
Install ttyd and ffmpeg, which VHS requires on PATH Install VHS with Homebrew on macOS or Linux: brew install vhs Create a new tape file: vhs new demo.tape Generate the GIF from the tape file: vhs demo.tape
Where can I get vhs?
The source code and installation instructions are on GitHub: https://github.com/charmbracelet/vhs

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects