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
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