charmbracelet

vhs: Record Scripted Terminal Demos and Tests

VHS turns text-based tape files into recorded terminal GIFs and other video formats. It suits developers who need repeatable CLI demos or terminal-based integration checks, provided ttyd and ffmpeg are available.

ActiveGoMITCLITerminalVideo
View on GitHub Compare
Stars
21.1k
Forks
483
Stars, last 30 days
+186
Last commit
12 days ago
Contributors
62

Our take

Activeregular commits and releases

Health score

47/100

How it is scored
Activity
49
Community
65
Issues
44
Pull requests
30

+186 stars in the last 30 days

  • Slower to merge pull requests than 95% of the projects we track

VHS is a capable fit for reproducible terminal demos and checks, with recent releases and commits and a broad contributor base supporting an active project.

Good fit if

  • Your work involves CLI tools and you want demos defined as editable, repeatable tape files.
  • You can provide ttyd and ffmpeg, or prefer the Docker image that includes dependencies.
  • You want to use it in CI or use its MIT-licensed code in a project.

Look elsewhere if

  • You need a recorder that works without the external ttyd and ffmpeg dependencies.
  • Your tests require a dedicated test framework rather than VHS's tape-based interaction and golden-output approach.
  • Your workflow is not based on terminal applications or command-line interaction.
All health signals
Last commit2026-09-24 (12 days ago)
Commits, last 90 days10
Releases, last 12 months3 (latest v0.12.1, 2026-09-24)
Contributors62 (top contributor: 58% of commits)
Issues closed, last 90 days3 (typically closed in 14 days)
Project age4 years

Checked on 2026-10-07 with the GitHub API.

Project history

Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.

Selected snapshot

Stars

21,327

Forks

494

Change since Nov 16, 2026: +7 stars·0 forks

Overview

VHS is a Go command-line tool for scripting terminal activity and rendering it as GIFs, videos, or image and text outputs. A tape file describes actions such as typing, key presses, waits, and terminal appearance, so demos can be regenerated rather than recorded by hand.

It is aimed at CLI developers who need polished walkthroughs or repeatable terminal output for integration checks. Tapes can also be recorded from a live session, shared through VHS publishing, or run through the built-in SSH server.

Key Features

  • Define terminal sessions in readable .tape files and render them from the command line.
  • Capture output as GIF, MP4, WebM, PNG frames, screenshots, or ASCII/text output.
  • Script typing, key presses, environment variables, pauses, and waits for screen content.
  • Configure terminal dimensions, fonts, themes, playback speed, and other presentation settings.
  • Use hidden sections for setup and cleanup that should not appear in the recording.
  • Record live terminal actions into a tape, then edit and replay the result.
  • Run tapes in CI, including generating golden text or ASCII files for comparison.
  • Publish GIFs or host VHS behind its SSH server for remote tape rendering.

Use Cases

  • CLI maintainers can create consistent GIFs for documentation and release announcements without manually recording each revision.
  • Developers can script a command-line walkthrough when a demo needs specific prompts, timing, or terminal styling.
  • Teams can generate ASCII or text outputs in CI to check terminal behavior against committed golden files.
  • A team with a self-hosted machine can render tapes remotely over SSH when the necessary commands are installed on that host.

What you need

Detected in the repository

  • Go 1.26.7 or newer (from go.mod)
  • A Dockerfile, so it can run in a container
  • Automated checks on GitHub Actions

License in plain words

MITpermissive

  • Commercial use: yes
  • Modify and redistribute: yes
  • You must keep: the copyright and license notice
  • Share your changes: no

A summary, not legal advice: the LICENSE file is what applies.

Getting Started

Install VHS and its ttyd and ffmpeg dependencies, then create and run a tape:

vhs new demo.tape
vhs demo.tape

See the README for installation options, tape syntax, and detailed configuration.

Alternatives

  • freeze: Freeze creates static images of code or terminal output, while VHS records scripted terminal sessions as GIFs or videos.
ProjectLanguageLicenseStarsStatus
vhsGoMIT21.1kActive
freezeGoMIT4.9kMaintained

Considerations

  • Rendering depends on ttyd and ffmpeg being available on PATH unless you use the provided Docker image. Commands and applications invoked by a tape must also be available in its execution environment.
  • Tape files make interactions repeatable, but terminal output can still depend on the shell and programs installed on the machine running VHS. CI users should control that environment when comparing generated output.
  • The project is active and has a diverse contributor base, but its issue handling is not instantaneous. Teams should account for the possibility that open issues may take time to resolve.
  • The built-in SSH server can run commands and applications on its host. Self-hosters should consider that access when configuring authentication and network exposure.
  • VHS is MIT-licensed. Review the license terms when incorporating or distributing it as part of another project.

Found this useful?

Share it with someone who would like vhs.

Comparisons