There are two philosophies for recording a terminal, and most bad terminal demos come from picking the wrong one. This guide covers both honestly — including when the tool we make is the wrong choice.
Philosophy 1: record the text (asciinema, VHS)
asciinema doesn't record pixels — it records the character stream of your session and replays it in a web player. The files are tiny, the "video" is crisp at any size, and viewers can pause and copy-paste commands straight out of the recording. That last property is unbeatable for documentation. VHS takes the same philosophy further: you script the entire session in a.tape file and it renders a deterministic GIF or video — perfect for demos that regenerate in CI whenever your CLI's output changes.
Use text-based recording when the destination is:
- Documentation or a README where readers copy commands
- A tutorial that must stay current (VHS + CI regenerates it)
- Anywhere file size matters and a web player is embeddable
Philosophy 2: record the pixels (real video)
Text-based recording stops working the moment your demo isn't purely text. A launch video that cuts from terminal to browser. A CLI that opens a UI. A social clip that needs to autoplay as MP4. A homepage hero. An App Store or Product Hunt asset. For all of these you need actual video — and that's where the problems start, because raw terminal footage is some of the worst-looking screen recording there is.
Why raw terminal video fails: the legibility math
Your terminal font is maybe 13px on a 2560px-wide display. Twitter's inline player shows that recording at roughly 500px wide on a phone — your text is now under 3 pixels tall. Nobody is reading that. This is the single reason terminal demos get scrolled past: not the content, the size.
You have three fixes, in ascending order of quality:
- Record a smaller region. Capture a 1280px window, not the full display. Better, still static.
- Bump the font before recording. 18-20px minimum for anything viewed on a phone. Do this regardless of what else you do.
- Zoom to the action. Show the full frame for context, then move in close on the command being typed and its output. This is what makes a demo watchable rather than merely legible.
The catch: click-based auto-zoom can't see a terminal
Here's the detail nobody covering "auto-zoom screen recorders" mentions: almost all of them key their zooms off mouse clicks. A terminal session is keyboard-driven — there's nothing to click, so there's nothing to zoom to, and the feature silently does nothing on exactly the content that needs it most.
This is why ZoomCap also triggers on typing: it detects a burst of keystrokes (timing only — never which keys), glides to where text is appearing, holds while you work, and releases when you pause. A terminal demo zooms itself the same way a click-driven UI demo does. As far as we know it's the only tool in the category that does this — appropriately, it is also itself a CLI: npx zoomcap record and you're recording, no app installed.
A recordable-terminal checklist
- Font at 18px+, a high-contrast theme (not your 40%-opacity vibe theme)
- A short prompt —
~/project $, not a three-line powerline - Clean history and
clearbefore starting - Window at 16:9-ish proportions so the crop doesn't waste space
- Type at natural speed — you can speed up dead air in the edit
- Rehearse once; the second take is always tighter
The decision table
| Destination | Use | Why |
|---|---|---|
| Docs / README reference | asciinema | Copy-paste, tiny files, always crisp |
| Auto-regenerating CLI docs | VHS | Scripted, deterministic, CI-friendly |
| Launch video / homepage | Real video with zoom | Mixed terminal + UI, needs MP4, needs polish |
| Social clips | Real video with zoom | Autoplay MP4, phone-sized player, legibility critical |
| README hero GIF | Either | VHS for pure CLI; video→GIF when a UI is involved |
The workflow we use
npx zoomcap record— starts a 60fps capture with system audio, no app install.- Run the demo. Typing bursts and clicks become zoom candidates automatically.
- The editor opens in the browser: re-aim or delete any zoom, trim the fumbles, speed up the slow parts, add a background.
- Export MP4 (720p/1080p) — or GIF for a README. Encoding runs locally; nothing is uploaded anywhere. MP4/H.264 is the right compatibility master; add a WebM sibling only when you control the player. Settings by channel are in MP4 vs MOV vs WebM.
And when the job is docs rather than a demo — use asciinema. The best terminal-recording setup is both philosophies, each where it belongs.