Terminal Session Recording with Asciinema: An Interactive Approach

Sometimes, you need to capture something from your terminal. This isn’t news – we’ve all shared commands with teammates or copy-pasted the output of a script. Terminal session recording is a common need for developers who want to share command-line workflows, debug issues, or create reproducible tutorials.

Beyond the humble copy/paste, you’ve probably used several ways to capture terminal output already:

• Redirecting output to text files
• Exporting your session log
• Taking a screenshot (or a video!)

This is far from a new problem, and we already have tools in our toolbelts to fit many situations. And yet, what if we introduced a new one?

Today, we’ll be exploring asciinema!

What Is asciinema

Asciinema (pronounced “as-kee-nuh-muh”) is an open-source tool for recording terminal sessions. However, unlike the methods we mentioned above, it introduces a new layer into the playback of those recordings. This yields an interesting benefit beyond a conventional video: Your audience can capture text from the video player.

Yes, you read that correctly! When viewing an asciinema recording (whether in a terminal or in a web browser), you can pause the video and click+drag select the text being displayed at any point. The playback session exposes the raw text from the recording, allowing viewers to copy from it, search through it, or scale it up and down without losing image clarity.

You can see an example recording below.

How Does It Work for Terminal Session Recording?

Asciinema’s workflow can be broken down into two stages, Recording and Playback.

Recording works how you might expect. It tracks input and output events taking place in our shell and stores them as a series of time-stamped events. Lines in the resulting file are JSON objects, structured in a format they call asciicast and categorized as on-screen text updates, entered control sequences, or any other user input observed during the session. This allows recording files to contain an accurate retelling of everything that happened in the user’s terminal.

Playback is where the rest of the magic happens. When you share an asciinema recording, viewers now have the option to either watch the recording in their own local terminal session or through an embedded player in their browser. Both methods provide the same interactive experience: play, pause, speed adjustments, and text selection.

Getting Started with asciinema

Installing asciinema is straightforward. Homebrew and apt example commands are shown below, but instructions for other systems are available in the documentation.

# macOS with Homebrew
brew install asciinema

# Ubuntu/Debian
sudo apt install asciinema

Once installed, recording a session is as simple as:

asciinema rec demo.cast

This starts recording your terminal. Perform your commands, and when you’re done, press Ctrl+D or type exit to stop recording. The session is saved to demo.cast, and you can now play it back with the following command.

asciinema play demo.cast

Sharing Your Recording

Now that you have an asciinema recording, what should you do with it? These will depend on your use case, as well as the assumptions you can make about your audience. Let’s talk through your options.

Upload to asciinema.org

If you’re comfortable with making the recording public (i.e., nothing sensitive was captured during the session), then the easiest sharing mechanism is to upload it to asciinema.org. The CLI can even handle this directly. Running asciinema upload demo.cast in your terminal will upload your recording and return a shareable link.

Note that by default, these links are “private” in the sense that other users cannot search for them, but anyone who obtains the link will be able to view the recording.

Share the Recording File Manually

If you don’t want your recording to be publicly available, you can still use external tools to share the recording with your audience. Add it to your git repository, store it with your project’s documentation, or attach it to a bug report. As long as you can reasonably expect your users to install the asciinema CLI, this method is a perfect fit.

Embed the Web Player in Your Hosting Environment

An inline player is available for recordings that are hosted on an asciinema server (either asciinema.org or self-hosted). Or, you can directly leverage the provided JS packages to serve the player and your recordings from your server’s HTML pages.

Note that this option requires JavaScript in your environment, which is markedly absent in cases like GitHub’s Markdown renderer.

Self-Host Your Own asciinema Server

If you find yourself using this workflow often, additional documentation is available for creating your own private instance of the asciinema.org experience.

Why Use Asciinema for Terminal Session Recording?

No single medium is perfect for every situation, and asciinema is no different; it’s not a one-size-fits-all solution. However, there are some compelling reasons why you might consider using it. Let me walk you through them.

Context: Unlike a static screenshot or confusing wall of text, an asciinema recording shows exactly what happened, timing and all. It’s perfect for tutorials, bug reports, or demonstrating workflows to teammates.

Selectability: Again, these playback sessions are text-driven. No need for your users to squint at a GIF image to see whether you entered a single quote vs. a backtick.

File Size: Since asciinema recordings are simply text and timing data (as opposed to video frames), the disk size of the recording artifacts is conveniently small.

Conclusion

Asciinema fills a unique niche in the toolkit for terminal recording and sharing. It bridges the gap between plain text output and video, offering the best of both worlds: the clarity and timing of a recording with the selectability and accessibility of text. Whether you’re creating tutorials, documenting bugs, or sharing command-line workflows, asciinema deserves a spot in your toolkit.

Give it a try, and add a new tool to your arsenal!