vhs
Write terminal GIFs as code for integration testing and demoing your CLI tools.
What is vhs?
VHS is a CLI tool that generates animated GIFs and videos of terminal sessions by executing scripts written in a domain-specific language. It solves the problem of creating reliable, reproducible demos and integration tests for command-line applications without manual screen recording. Developers write `.tape` files that specify terminal commands, timing, and visual settings, which VHS renders into shareable media.
CLI tool developers, open-source maintainers, technical educators, and DevOps engineers who need to create demos, tutorials, or automated visual tests for terminal-based software.
Unlike manual screen recording tools, VHS offers a code-first approach: recordings are scriptable, version-controlled, and can be integrated into CI/CD pipelines. Its extensive customization and ability to self-host via SSH provide flexibility and consistency across environments.
Overview
Your CLI home video recorder 📼
Use Cases
Best For
- Creating automated demo GIFs for CLI tool documentation
- Generating visual regression tests for terminal user interfaces (TUIs)
- Producing tutorial videos with precise timing and commands
- Maintaining up-to-date demo media via GitHub Actions
- Recording terminal sessions for bug reports or support
- Self-hosting a rendering server to use host-installed dependencies
Not Ideal For
- Teams needing instant, one-off screen captures without writing scripts
- Environments where installing ttyd and ffmpeg is restricted or complex
- Projects requiring recordings of graphical applications or web browsers
- Users who prefer real-time editing and collaboration on recordings
Pros & Cons
Pros
VHS defines terminal actions in .tape files, making recordings repeatable and versionable—core to its philosophy of treating demos as code for consistent integration tests and tutorials.
The tool offers extensive control over terminal appearance, including font, theme, padding, and playback speed, with detailed examples in the settings section for polished outputs.
An official GitHub Action automates GIF updates in pipelines, ensuring demo media stays synchronized with code changes without manual intervention.
The SSH server mode allows self-hosting to leverage host-installed tools, enabling rendering in environments where dependencies like ffmpeg are already set up.
Cons
VHS requires separate installations of ttyd and ffmpeg, adding setup complexity that can be a hurdle in constrained or locked-down environments.
Creating .tape files involves learning a domain-specific language with verbose syntax, which can be overkill for quick recordings compared to simpler screen capture tools.
The tool is exclusively designed for terminal sessions, making it unsuitable for recording GUI applications, browser interactions, or any non-terminal workflows.
Frequently Asked Questions
Related Projects
ScreenToGif🎬 ScreenToGif allows you to record a selected area of your screen, edit and save it as a gif or video.
terminalizer🦄 Record your terminal and generate animated gif images or share a web player
PeekSimple animated GIF screen recorder with an easy to use interface
Gifski🌈 Convert videos to high-quality GIFs on your Mac
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.