How to record a terminal session and share it

Record the text, not the pixels

A three-minute screen recording of a terminal is perhaps 40 MB of video. The same session recorded as output plus timing data is a few tens of kilobytes.

That difference is not really about size. It is about what you can do afterwards:

• Search it. Find the command that produced the error.
• Copy out of it. The person following along can paste the command rather than retyping it from a video.
• Edit it. Cut the ninety seconds where a package installed.
• Scan it. Check mechanically whether a token went past.
• Diff two runs. Which is impossible with video.

You can always render a GIF from a text recording when you need a picture. You cannot go the other way.

The editing pass nobody does

A raw recording is mostly waiting. A build, an install, a large copy — long gaps where nothing happens and the viewer is watching a cursor.

Two edits fix almost everything:

Cap the idle time. Anywhere nothing happened for more than a couple of seconds, compress it to a couple of seconds. This alone typically halves the length and changes nothing about what is shown.

Cut the dead ranges. The four-minute install, the false start, the typo and its correction. Specify them as time ranges and apply them, rather than re-recording — re-recording is how a nine-minute session becomes a nine-minute session again.

A nine-minute recording becomes ninety seconds without a single frame being faked.

Take the secrets out before you share it

Terminal sessions collect credentials with no effort whatsoever: an environment variable printed by accident, a token in a URL, a connection string in an error message, an SSH key path, an API response containing a session key.

Scan before it leaves your machine. Pattern matching finds well-formed things — keys with recognisable prefixes, long base64 strings, private key headers, connection strings — and it will not find a password that looks like an ordinary word.

So treat the scan as a first pass, not a guarantee. If a tool tells you it catches everything, it is wrong; if it tells you roughly what it misses, believe it and read the transcript yourself as well.

Turning it into a picture

Two different outputs, for two different places:

An animated GIF, for a ticket, an issue or a chat where the point is the sequence of events.

Still frames, for documentation, where a GIF is worse than useless because the reader cannot pause it. The useful trick is picking the moments automatically: the interesting frames in a terminal recording are the ones just before a long quiet gap, because that is where a command finished and left its output on screen.

The programs for this

• SessionForge is the recorder: record captures a command’s output with exact timings, replay plays it back at real speed with an idle cap, info describes it, and cat dumps the text.
• RecordDeck is the edit pass: info shows where the long gaps are, preview shows what an edit list would do, and apply writes a new recording — nine minutes to ninety seconds without re-recording anything.
• ScreenFlow renders a recording to an animated GIF, with a size, a speed, an idle cap and a theme.
• CaptureStudio finds the moments worth a still — moments names the seconds that are worth a picture, shot renders one — and turns them into PNGs.
• ClipStudio indexes a library of recordings, searches across them, and scans for secrets before you share one. It is honest about its hit rate rather than promising to catch everything.

Free while we are in preview, one file each, Windows and Mac.

The recording format

These use a JSON-lines cast file: one line per output event, with a timestamp and the bytes. It is the same idea as asciinema’s format — plain, appendable, and readable with an ordinary text editor if you ever need to fix one by hand.