Asciinema: Terminal Session Recorder

January 20, 2022 3 minute read

Useful links

First and foremost, open these in new tabs. They are amazing documentations from official sources.

[as-kee-nuh-muh].
The word “asciinema” is a combination of English “ASCII” and Ancient Greek “κίνημα” (kínēma, “movement”).

Marcin Kulik, founder of asciinema project

Info: Currently asciinema only supports *nix and macOS. Windows users could still use asciinema in WSL Linux distro as a workaround.

In a nutshell, asciinema is a recorder that captures user input and output (stdout and stderr) in the terminal. It does this by utilizing pseudo-terminal to capture all data going in & out to terminal, timestamp it and save it to a file.
The file is in asciicast format (JSONL) and is comparatively smaller than video format such as mp4 and mov. This is because it only contains stream of text to be played back in a compatible terminal emulator.
The recorded asciicast file can be re-played back in the terminal easily. You can also use the open-source asciinema player to embed the player in your website.
asciicast file can also be uploaded to the public asciinema.org which allows the recording to be watched and shared on the web.
Even better, one could also host a non-public asciinema server instance for private use.
Lastly, the asciicast file can also be converted to gif using asciicast2gif for better compatibility. For example, the gif can be uploaded to websites such as Medium which don’t support embedding script tag.

Latest asciinema release can be easily installed with pipx or pip.

pipx install asciinema
# or
python3 -m pip install asciinema

To record a terminal session,
```
asciinema rec output.cast
```
This will save the recording to output.cast which can be uploaded or used for playback.
One useful option is to include -c <command> which overwrites the default SHELL command to record. For eg, one could do -c "tmux attach -t <session>" to record a tmux session.
To playback the recording in terminal,
```
asciinema play output.cast
```
Keep in mind that this only plays back the recording and does not re-execute all the commands in the recorded terminal session.
To upload the recording to public asciinema.org
```
asciinema auth
asciinema upload output.cast
```

To convert the recording to gif

npm install --global asciicast2gif
asciicast2gif output.cast output.gif