Quick start

Betamax currently supports macOS and Linux. Windows is not supported because the upstream libghostty-vt-sys native build does not support Windows.

Install

Install the CLI with Homebrew from joshka/homebrew-tap. If Homebrew requires trusted taps, trust the formula first.

Rust users can install from crates.io with cargo-binstall.

mise users can install the same release archives with its packslip backend, which checks each archive against a manifest signed by the release workflow. Releases after 0.3.0 carry that manifest; for 0.3.0, use Homebrew or cargo-binstall.

cargo install betamax also works, but it builds Ghostty’s terminal library from source and needs Zig 0.15.2 on PATH. See Build from source, or use one of the prebuilt binaries.

GIF, PNG, screenshot, and state JSON outputs are written in process. MP4 and WebM output require ffmpeg on PATH.

brew install joshka/tap/betamax
brew trust --formula joshka/tap/betamax

cargo install cargo-binstall
cargo binstall betamax

mise use -g packslip:joshka/betamax

# macOS
brew install ffmpeg

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install ffmpeg

Create a tape

Create a starter tape, render it, and optionally append an extra Output from the CLI without editing the tape.

The starter tape includes a compact command summary and writes demo.gif by default. The CLI output path is appended as another Output command. It does not replace outputs already in the tape.

betamax new demo.tape
betamax run demo.tape
betamax run demo.tape --output target/demo.png

Validate tapes

Validate one tape or a group of tapes without rendering.

Validation parses syntax and enforces command ordering. It does not start a shell, load a theme, run Require checks, or write output files. Use betamax run for a full execution check.

betamax validate demo.tape
betamax validate "examples/*.tape"

List themes

List theme names and use the exact value with Set Theme "...".

See Themes and layout for lookup behavior and layout settings, and Window styling for presets and window decoration.

betamax themes
betamax themes --json
betamax themes --markdown

Next steps

Tape files: structure tapes, wait for output, and hide setup.
Examples: copy a tape that is close to what you want.
Terminal testing: assert on terminal output with state JSON.
GitHub Action: render tapes on pull requests and post previews.
Differences from VHS: move existing VHS tapes over.
Tape reference: every command and setting.