A screencast (i.e., a movie of what is happening on screen) helps developers demonstrate their programs to users and is useful for people seeking a way of explaining their problems to a support specialist. On Linux, there are many different solutions for this, such as recordMyDesktop, OBS Studio, or – as in the case of Gnome – the feature is integrated into the desktop environment. But if you only want to record shell commands and their output, you're using a sledgehammer to crack a nut. Asciinema [1] can be a good, lean alternative for these cases.

Asciinema consists of three components. The first is the actual recording tool for the command line. The second is a web-based hosting platform for asciinema videos, which is similar to YouTube or image hosts like Imgur.com or Gfycat.com. The third component is a JavaScript player that plays the asciinema videos [2]. Users only need the recorder unless you want to host your asciinema videos on the web yourself; in this case, you would have to set up the server components on a web server.

And … Action

Most current distributions include the screencast recorder for asciinema in their package sources. The application version counter is currently at 2.0.2. Ubuntu 18.04, Debian 10 "buster" (sudo apt install asciinema), and Fedora 28 (sudo dnf install asciinema) at least give you asciinema 2.0.0. More information about the installation, for example for the Python package manager Pip, can be found in the application documentation [3]. Having a recent version is important because the file format of the recordings changed with the release of asciinema 2.0 and many new functions have been implemented [4].

After the install, the easiest way to start recording is to type the asciinema rec command. Doing so opens a new shell in which asciinema records everything you type, and the system displays it on the screen. It continues until you stop recording by typing exit or pressing Ctrl+D. You can then either press Enter to upload the video to asciinema.org, or save it locally in the /tmp/ directory using Ctrl+C (Figure 1). The file name is always tmp<random code>-ascii.cast. Alternatively, you can pass a file name and path directly to asciinema at startup:

$ asciinema rec <example>.cast

Figure 1: Asciinema records the events on the desktop. The result is available as a special CAST file that can be played back via the terminal or a web-based player.

To play the locally saved recording, call asciinema again, this time with the play option and the movie file as a parameter. A typical call looks something like this:

$ asciinema play /<path>/<to>/ <example>.cast

Asciinema plays the screencast directly in the shell, but without executing the recorded commands locally – it is in fact a video, not a script. If necessary, you can use the space bar to pause playback or press "." to skip through the video frame. Press Ctrl+C if you want to stop the playback of the terminal movie completely.

When you're recording, keep in mind that asciinema records the events on the command line unchanged. It not only stores the commands and their output, but if you correct input at the command line, this is also shown in the asciinema video. Similarly, if you do nothing during the recording, for example because you need to look up the details of a command, the video pauses.

To avoid what are often involuntary and (for the viewer) boring breaks, add the --idle-time-limit=<seconds> option or the shortcut -i<seconds> to the call to record the asciinema video. This limits the timeout to the number of seconds specified in the option. For example, asciinema rec -i1 gives you a maximum timeout of one second.

Managing Shell Videos

Alternatively, you can upload the terminal video directly to asciinema.org on the web without any detours. You don't have to register with the service to do this; the video is uploaded automatically if you do not press Ctrl+C to cancel the action at the end of the recording.

Asciinema's terminal recorder then displays a URL in the style of https://asciinema.org/a/jl0[...]2wN, where you (or others) can play back the movie in a web browser (Figure 2). The link remains active for seven days, after which the system automatically archives the recording, and access to the movie is lost.

Figure 2: In the default configuration, asciinema automatically uploads the recorded movies to the in-house "YouTube alternative" for terminal movies.

If you want to keep the movie accessible for a longer period of time, you have to authenticate against asciinema.org on each computer where you want to create and upload recordings. To do this, enter the asciinema auth command and then open the link displayed in the terminal in a browser. You are then given the option to create an account on the asciinema website or to log in with an existing account. Asciinema will then automatically assign the terminal videos previously uploaded from this computer to your account.

The web portal (Figure 3) lets you manage your recordings. For example, you can change the metadata such as the title or insert a description. The terminal theme and the preview image can also be modified. Settings | Make public lets you publish your video on a list [5] accessible to all users. With the default setting, however, your uploads remain private. Unsuccessful movies, or ones you no longer want, can be deleted from the overview.

Figure 3: Asciinema's web portal lets you organize the terminal videos associated with your account. You can adjust the appearance of the thumbnails and the web player.

Embedding asciinema

The Share button gives you information on how to integrate the selected terminal video into any website, such as your own WordPress blog or the one of your projects' GitHub page. The page automatically generates HTML or Markdown tags that display an image in the web page linked to the video on asciinema.org. You will also find a short script snippet below, which can be used to embed the video directly into a website (if the content management of the site allows it).

Listing 1 demonstrates an asciinema-enriched website. The first section uses the script; the second uses the universal image. Figure 4 shows the resulting and still very rudimentary website in the browser. The asciinema movie played back in the web browser supports copy and paste actions at any point, so that the viewers can, for example, copy commands from the video directly into the terminal.

<!DOCTYPE html>
<html>
  <head>
    <title>Hello World</title>
  </head>
  <body>
    <h1>Included as script</h1>
    <script id="asciicast-jl0NXr88Lm7c7DGOIf8Jh92wN" src="https://asciinema.org/a/jl0NXr88Lm7c7DGOIf8Jh92wN.js" async></script>
    <h1>Included as image</h1>
    <a href="https://asciinema.org/a/jl0NXr88Lm7c7DGOIf8Jh92wN" target="_blank"><img src="https://asciinema.org/a/jl0NXr88Lm7c7DGOIf8Jh92wN.svg" /></a>
  </body>
</html>

Figure 4: The terminal videos hosted by asciinema can be easily integrated into your own web pages, such as a blog or GitHub page.

However, both variants have the disadvantage of embedding external resources into your own website (the script and the data loaded by asciinema or the embedded image). To avoid external data connections, you will therefore want to download the image of the terminal movie, upload it locally to your website, and then link only to the asciinema video. It's also possible to convert asciinema clips to animated GIF images using other applications (see the "Alternatives" box).