Quick Start

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

01InstallGet the CLI.02Repo ToolsSet up development.03CreateWrite and render.04ValidateCheck syntax first.05ThemesFind style names.06ExamplesRender fixtures.

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.

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

# macOS
brew install ffmpeg

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

Notes

Homebrew is the shortest path. Cargo works well when Rust is already part of the machine.

Repository Software

The checked-in examples and development commands need Rust and Cargo from rustup, mise for the repository toolchain, pnpm for the documentation site, and ffmpeg only when rendering MP4 or WebM outputs.

The important non-Rust tool is Zig 0.15.2. Betamax uses the safe libghostty-vt Rust wrapper; its libghostty-vt-sys dependency fetches a pinned Ghostty source commit and runs Zig to build the native VT library. That Zig version is an upstream Ghostty build requirement until Ghostty supports newer releases such as 0.16.

mise is the documented path because it is small and works across the repository today. Other toolchain managers can work too, including Nix or a manually installed Zig 0.15.2 on PATH. PRs that document another reproducible setup are welcome.

mise install
pnpm install

Toolchain

The repository pins Zig 0.15.2 in .mise.toml, so mise run … commands use the version Ghostty expects.

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

Output

CLI-provided outputs append to the tape for that run. They do not rewrite the source file.

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"

Fast Check

Validation is structural. It is meant to catch ordering and parsing problems before a PTY starts.

List Themes

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

See Themes And Styling for lookup behavior, layout settings, and frame decoration.

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

Remember

Theme names are matched by name. Copy the exact value into Set Theme ”…”.

Repository Examples

Clone the repository to render the checked-in examples.

Rendered outputs are written under examples/output and copied to target/betamax-examples for local inspection. The Examples page explains what each tape demonstrates. The Tape Reference documents every command and setting.

git clone https://github.com/joshka/betamax
cd betamax
mise install
pnpm install
mise run render-examples

Where Files Go

Example renders land under examples/output and are copied to target/betamax-examples for inspection.