Demo recordings
Terminal demos in this repository are generated from VHS tape files. A tape is a plain-text script that drives a virtual terminal and produces a deterministic GIF. When you store tapes in the repo, anyone with VHS installed can review the recordings, compare changes between versions, and reproduce them locally.
Install VHS
# macOS
brew install vhs
# Other platforms: https://github.com/charmbracelet/vhs#installationVHS also requires ttyd and ffmpeg. Homebrew installs both as dependencies.
Run an existing tape
Run tapes from this directory:
cd docs/demos
vhs getting-started.tapeEach tape stages its own working directory in a hidden setup block, so glab picks up a project from a git remote no matter where you launch VHS from. Output paths in tape files are relative to this directory.
Shared styling
All tapes begin with Source base.tape, which pulls in the canonical terminal settings: dimensions, theme, typography, frame, and window bar. To change the look across every demo at once, edit base.tape. In a per-tape file, include only:
- The
Source base.tapeline. - An
Outputdirective for that tape's GIF. - A
Hide...Showblock that stages the working directory and prompt. - The script itself.
base.tape is a partial. It contains only Set directives. Do not run it directly with vhs.
Authentication
Tapes invoke glab against the live GitLab API, so you need to pass a valid token through the environment when you run vhs:
GITLAB_TOKEN="<your-personal-access-token>" vhs getting-started.tapeglab reads GITLAB_TOKEN before the keyring and config file, and VHS inherits its parent's environment, so the token reaches every command in the tape. To target a non-gitlab.com instance, set GITLAB_HOST the same way.
Notes on token usage:
- The token needs only the
read_apiscope. When a tape clones over SSH,gituses your SSH key, and the token isn't consulted for that step. - Don't bake tokens into tape files. Always pass tokens through the environment at recording time.
- When your interactive shell wraps
glabin an alias (for example,alias glab='op plugin run -- glab'), the bash session that VHS spawns might not inherit the alias, depending on your.bashrc. The bundled tapes defensively rununalias glabin their hidden setup block so they always exercise the binary onPATH. Do the same in new tapes.
Add a new tape
getting-started.tape is the reference example. Use it as the starting point for new tapes.
- Create a new
docs/demos/<name>.tapefile. - Copy the contents of
getting-started.tapeto your new file. Keep theSource,Output, andHide...Showblocks. You'll edit them in the next two steps. - Update the header comment and the
Outputpath for your demo. - Update the
Outputpath to point to your new GIF. - Replace the script section (everything after the
Showdirective) with the commands you want to record. - Run
vhs <name>.tapeto generate the GIF. - Commit the
.tapefile and the generated GIF together.
Guidelines for tape content
When you write the script, follow these conventions:
- Prefer flags that bound output, such as
--per-pageand--limit, instead of relying on the default config. The recording should look the same on any machine. - To time a long-running command, use
Wait+Screen /regex/instead ofSleepso the recording adapts to network latency.
Current tapes
| Tape | Output | Used in |
|---|---|---|
base.tape | (partial, sourced by other tapes) | All demos |
getting-started.tape | ../source/img/getting-started.gif | README.md, docs/source/_index.md |