Asciinema is an excellent tool for recording and sharing terminal sessions.
The project is open-source and available on GitHub.
A key feature of asciinema is that it allows the viewer to copy-paste the text from the player itself directly.
The result of a terminal recording is an editable text file with extension
This file can be easily shared and embedded on any website.
However, markdown does not support rendering asciinema recordings.
Therefore, you will need to transform your asciinema recording into something that markdown can handle, such as
This post will show you step-by-step how to use asciinema to generate beautiful terminal recordings to enhance
First, let’s see the help page of asciinema using the wonderful tldr project:
Recording a terminal session
To install asciinema, follow the official guide. Once you have it installed, you can start recording a terminal session using the following command:
1 asciinema rec demo.cast
The previous command will create a recording file named
demo.cast, which you can replay directly in the terminal as follows:
1 asciinema play demo.cast
Insert the recording in a README
Now that you have your session recorded, you need to transform the
demo.cast into a
.gif file, which can be inserted in your
To do so, the asciicast2gif tool comes handy.
It allows to generate a
.gif files from
.cast asciinema recordings.
To install asciicast2gif using npm run the following command:
1 npm install --global asciicast2gif
Note: For asciicast2gif to work, you also need have ImageMagic installed on your system.
Once asciicast2gif is installed, make the file transformation as follows:
1 asciicast2gif -w 80 -h 30 demo.cast demo.gif
The previous command will produce a
demo.gif file with 80 characters width and 30 lines of height.
It can be inserted in
README.md, just as any other image:
PATH_TO_FILE is the path to your
demo.gif file on GitHub.
I have used this method to add a terminal screencast in the
README.md of DepClean (one of my tools), so that the users can easily grasp its basic usage.
Insert the recording in a website
To use asciinema on the browser, use the asciinema-player.
You will need
asciinema-player.js. You can download the latest version of these files here.
Then, use these files from page as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 <html> <head> ... <link rel="stylesheet" type="text/css" href="/asciinema-player.css" /> ... </head> <body> ... <asciinema-player src="/demo.cast"></asciinema-player> ... <script src="/asciinema-player.js"></script> </body> </html>
This will embed a player similar to the one presented in this post.