Record Your Terminal Session and Convert it to a GIF Image – ASCIINEMA

When we make a code documentation, software installation manual, or create presentations, we often add a code snippet to help us to convey messages to the audiences.
But sometimes, animated snippets is more helpful. On this article, we will learn how to record our terminal session with asciinema.

According to their website, asciinema [as-kee-nuh-muh] is a free and open source solution for recording terminal sessions and sharing them on the web. The asciinema website also provides asciicast, an asciinema player in html5 format. With asciicast we can share our terminal sessions instantly after we finished recording.

How to Install ASCIINEMA on Ubuntu

Thanks to Ubuntu package maintainers, asciinema is available on its Ubuntu official package. So that we don’t need to add a custom PPA or build asciinema manually. To install asciinema program, we simply need to run sudo apt install asciinema, and voila, we have asciinema installed on our machine.

sudo apt install asciinema

How to record a terminal session with ASCIINEMA

Once asciinema installed on our machine, we can record a terminal session by typing asciinema rec or asciinema rec /path/to/output.cast in our terminal emulator. Once we finished recording our session, press <ctrl + d> or type “exit” to exit the asciinema and save the output.

For more information about recording usage, we can type asciinema rec --help

➜ asciinema rec --help
usage: asciinema rec [-h] [--stdin] [--append] [--raw] [--overwrite] [-c COMMAND] [-e ENV] [-t TITLE] [-i IDLE_TIME_LIMIT] [-y] [-q] [filename]

positional arguments:
  filename              filename/path to save the recording to

options:
  -h, --help            show this help message and exit
  --stdin               enable stdin recording, disabled by default
  --append              append to existing recording
  --raw                 save only raw stdout output
  --overwrite           overwrite the file if it already exists
  -c COMMAND, --command COMMAND
                        command to record, defaults to $SHELL
  -e ENV, --env ENV     list of environment variables to capture, defaults to SHELL,TERM
  -t TITLE, --title TITLE
                        title of the asciicast
  -i IDLE_TIME_LIMIT, --idle-time-limit IDLE_TIME_LIMIT
                        limit recorded idle time to given number of seconds
  -y, --yes             answer "yes" to all prompts (e.g. upload confirmation)
  -q, --quiet           be quiet, suppress all notices/warnings (implies -y)

How to render ASCIINEMA cast file to a GIF image

Asciinema provides a utility tool called agg, asciinema gif generator. Agg is written in Rust programming language. It uses Kornel Lesiński’s excellent gifski library to produce optimized, high quality GIF output with accurate frame timing.

To render asciinema cast file to a gif image, we can simply run it with agg /path/to/input.cast /path/to/output.gif. We can also pass parameters to customize the output such as change the terminal theme, change the terminal size, etc.

Below is the command to render gif sample above

agg --cols 80 --rows 20 --theme solarized-dark ~/Desktop/input.cast ~/Desktop/output.gif

For more information about agg, type agg --help or go to their official GitHub repository.

How to install agg – asciinema gif generator on Ubuntu

To install agg, we can do it in two ways, build manually with Cargo or install it with snap package manager.

Install agg from Snap Package Manager

snap install asciinema-agg

*note on installing agg from snap, the binary file would be asciinema-agg instead of agg

Install agg from Cargo (Rust Package Manager)

To build agg manually, make sure Rust programming language is installed on our machine. Once it’s installed, we can install agg by running command below

cargo install --git https://github.com/asciinema/agg