How to Record a Terminal Session on Mac & Linux (Video or GIF)

There are two ways to record a terminal, and most bad terminal demos come from picking the wrong one. This guide covers both, including how to record a terminal session on Mac and Linux, how to record a terminal to a GIF, and which approach fits which destination. Commands for asciinema, VHS and script are from each project's own documentation; ZoomCap commands are from our docs.

Option 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 hard to beat for documentation. VHS takes the same idea further: you script the entire session in a .tape file and it renders a deterministic GIF or video, which suits 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 plus CI regenerates it)
• Anywhere file size matters and a web player is embeddable

The limit: text recorders only see the terminal. If your demo opens a browser, a GUI or a second app, none of that appears.

Option 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. A Product Hunt gallery asset. For all of these you need actual video, and that is where the problems start, because raw terminal footage is some of the worst-looking screen recording there is.

How to record a terminal session on Mac

As text

1. Install asciinema: brew install asciinema.
2. Start recording: asciinema rec demo.cast. A new shell starts inside the recording.
3. Run your demo, then type exit or press Ctrl+D to stop.
4. Replay locally with asciinema play demo.cast, embed the player in your docs, or convert to a GIF (below).

No install at all: macOS ships the BSD script command. script -r session.log records with timing, and script -p session.log plays it back. It is fine for a personal log and awkward to share, which is why asciinema exists.

As video

• ZoomCap's CLI: run npx zoomcap record from any terminal. On macOS 15+ it records at 60fps by default with system audio and mic through ScreenCaptureKit; older macOS versions fall back to ffmpeg and record video only. A ● REC item sits in the menu bar while it runs, and typing bursts become zooms without any editing.
• Shift+Command+5, choose “Record Selected Portion”, and draw around the terminal window. Free and built in; no zoom, no editing. Our Mac screen recording guide covers every option.
• OBS Studio: free, with a window capture source for just the terminal. You add zooms in an editor afterwards.

How to record a terminal session on Linux

As text

1. Install asciinema from your package manager (for example sudo apt install asciinema) or from asciinema.org.
2. asciinema rec demo.cast, run the demo, then exit.
3. Or use util-linux's script --timing=time.log session.log and replay with scriptreplay --timing=time.log session.log.

As video

• ZoomCap's CLI: npx zoomcap record records X11 sessions and tracks clicks and typing for automatic zoom. It records video only: no Wayland and no system audio yet, so record a voiceover separately if you need one.
• Your desktop's built-in recorder: GNOME, for example, has screen recording in its screenshot tool. Fine for a quick clip, no editing.
• ffmpeg on X11: ffmpeg -f x11grab -framerate 30 -i :0.0 terminal.mp4 records the display with no UI at all. Add -video_size and an offset to capture just a region.
• OBS: free and reliable on X11 and Wayland, with no editor or automatic zoom.

More Linux options, including Wayland-native ones, are in our Linux recorder roundup.

Why raw terminal video fails: the legibility math

Your terminal font is maybe 13px on a 2560px-wide display. X's inline player shows that recording at roughly 500px wide on a phone, so your text is now under 3 pixels tall. Nobody is reading that. This is the main reason terminal demos get scrolled past: not the content, the size.

You have three fixes, in ascending order of quality:

1. Record a smaller region. Capture a 1280px window, not the full display. Better, but still static.
2. Bump the font before recording. 18–20px minimum for anything viewed on a phone. Do this regardless of what else you do.
3. 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.

If the result still looks soft, our list of reasons screen recordings look blurry covers scaling and compression.

The catch: click-based auto-zoom can't see a terminal

Here is the detail most write-ups of auto-zoom screen recorders skip: almost all of them key their zooms off mouse clicks. A terminal session is keyboard-driven. There is little to click, so there is little to zoom to, and the feature does nothing on exactly the content that needs it most.

Why ZoomCap for terminal demos

This is why ZoomCap also triggers on typing: it detects a burst of keystrokes (timing only, never which keys), closes in on where you last clicked, holds while you work, and releases when you pause. It does not follow the text caret, so click once into the terminal pane before you type and the zoom lands on the right place. ZoomCap is itself a CLI, which suits terminal demos: npx zoomcap record and you are recording.

We make ZoomCap, so weigh this accordingly. The CLI is part of the paid plans: $29 once or $12.49 a month. The free plan gives you the browser recorder and editor with 2 watermarked exports a month, but the browser recorder only sees clicks inside its own tab, so terminal recordings made there need zooms placed by hand. There is no Windows CLI yet, no motion blur, and speed changes apply to the whole video. Recordings are edited and encoded on your computer and never uploaded to us; the data flow is on our security page, and paid plans have a 14-day refund if it doesn't work for you.

How to record a terminal to a GIF

A GIF is still the default for READMEs and issue threads because it autoplays everywhere. Three ways to get one, from most to least deterministic:

1. VHS: script it, get a GIF

Install with brew install vhs (it needs ttyd and ffmpeg; other installs are on the VHS README). Then write demo.tape:

Output demo.gif
Set FontSize 28
Set Width 1200
Set Height 600
Type "npx mytool --help"
Sleep 500ms
Enter
Sleep 3s

Run vhs demo.tape and you get demo.gif. Change the Output line to .mp4 or .webm for video. vhs record > demo.tape writes a tape from a session you type live, which you can then tidy up.

2. asciinema plus agg

Record with asciinema rec demo.cast, then convert with asciinema's GIF generator: agg demo.cast demo.gif. You can set the font size and theme on the command line, which keeps text legible at README widths.

3. Record video, then convert

When the demo includes anything other than the terminal, record video and export a GIF. ZoomCap exports GIF directly from the editor, and our free MP4 to GIF converter runs in the browser. With ffmpeg, generate a palette first so the text doesn't band:

ffmpeg -i demo.mp4 -vf "fps=12,scale=800:-1:flags=lanczos,palettegen" palette.png
ffmpeg -i demo.mp4 -i palette.png -lavfi "fps=12,scale=800:-1:flags=lanczos[x];[x][1:v]paletteuse" demo.gif

Keep terminal GIFs to about 10–15fps and 800px wide; text doesn't need more frames, and size balloons fast. GitHub's limits and embed markdown are in adding a demo GIF to your README, and palette settings in more depth in turning a screen recording into a GIF.

A recordable-terminal checklist

• Font at 18px or more, and a high-contrast theme (not a 40%-opacity translucent one)
• A short prompt: ~/project $, not a three-line powerline
• Clean history, and clear before starting
• Window at roughly 16:9 proportions so the crop doesn't waste space
• Hide tokens and hostnames: set a throwaway prompt and unset secrets from your environment
• Type at natural speed; trim the dead air in the edit
• Rehearse once; the second take is almost always tighter

The decision table

And by destination:

The workflow we use for real video

1. Open two terminals: one for the demo, one for ZoomCap. Run npx zoomcap doctor once to check permissions, and npx zoomcap displays if you have more than one screen.
2. npx zoomcap record in the second terminal. On macOS 15+ that is a 60fps capture with system audio and mic.
3. Click into the demo terminal and run the demo. Typing bursts and clicks become zooms automatically.
4. Stop: on macOS, ⌃⌥S works from any app; otherwise switch back to the ZoomCap terminal and press q.
5. The editor opens in the browser: re-aim or delete any zoom, trim the fumbles, cut the dead air, add a background and captions. Speed-up applies to the whole video (1.5× or 2×), so cut long waits rather than speeding up one section.
6. Export MP4 from 720p up to 4K, or GIF for a README. Encoding runs locally; nothing is uploaded. 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.

When the job is docs rather than a demo, use asciinema. The best terminal-recording setup is both approaches, each where it belongs. For more on recording from the command line, see command-line screen recorders with auto zoom.

Frequently asked questions

Record your terminal demo

Try the editor free in your browser with nothing to install, then run npx zoomcap record for automatic zoom on your typing. The CLI, unlimited exports and no watermark are $29 once on the pricing page.