Working with the CLI? You should probably start using asciinema!

Whether you’re a sysadmin, a developer or simply using the CLI as part of your day job, there are many reasons why you might be willing to share what you see on your terminal. What comes to mind immediately is to create a screencast or jump on Google Hangouts to share your screen.

But the problems with sharing video feeds or recordings are quite annoying:

• When sharing your screen, the video feed is inconsistent and depends upon the peers’ available bandwidth.
• Having a meeting just to share your screen means blocking 2 (or more) people’s time instead of allowing things to be asynchronous.
• Sharing a recording often means uploading/downloading a fairly large file or making a compromise with the size…which means degrading the video quality/bitrate to have a reasonably sized file.
• There’s no way to copy and paste what you see on the prompt

Why asciinema?

asciinema is a free and Open Source solution for recording terminal sessions and sharing them on the web.

This is best explained on the official site:

Record and share your terminal sessions, the right way. Forget screen recording apps and blurry video. Enjoy a lightweight, purely text-based approach to terminal recording.

Think about recording a training or sharing a troubleshooting session with your colleagues? asciinema it is! If you’re interested to know more, read how it works.

Recording, playing and sharing

Now let’s get to the techy parts. Recording a session is very straight forward. Use the rec command and give it a path where to save the JSON file.

$ asciinema rec /tmp/postfix-basics.json

To play the recording, use the play command.

$ asciinema play /tmp/postfix-basics.json

When you’re happy with the results, you can upload your recording to the asciinema website and share it with others or keep it private instead.

$ asciinema upload /tmp/postfix-basics.json

Taking it from there, you’ll be able to embed the recording on a web page. This is for example what I’ve been doing for months with my drucker project. Read more about sharing and embedding.

Wrapping up, and a word of warning

Like what you see? Give asciinema a try! It’s available on Linux (APT), Mac OS X (brew) and *BSD and can conveniently be installed via PIP as well.

One final word of warning: make sure you’re using a recent version to have all commands and parameters available (e.g. the current package version - 0.9.8 - in Ubuntu Xenial is very outdated). In doubt, try asciinama’s master branch:

$ git clone https://github.com/asciinema/asciinema.git
$ cd asciinema
$ python3 -m asciinema --help

This should return something like:

$ python3 -m asciinema --help

Record and share your terminal sessions, the right way.

positional arguments:
  {rec,play,upload,auth}
    rec                 Record terminal session
    play                Replay terminal session
    upload              Upload locally saved terminal session to asciinema.org
    auth                Manage recordings on asciinema.org account

(snip)

I personally like to use the following when recording a new session.

$ asciinema rec -t "Postfix Basic Training" -i 2 /tmp/postfix-basics.json

• -t allows to give your recording a title
• -i sets (in seconds) the maximum terminal inactivity we should record

When you’re ready to share your screencast with the world or your colleagues, simply type:

$ asciinema upload /tmp/postfix-basics.json

And to associate the newly-uploaded screencast with your asciinema account (so that you can manage it), type:

$ asciinema auth
Open the following URL in a browser to register your API token and assign any recorded asciicasts to your profile:
https://asciinema.org/connect/c35902cb-djd8-4e31-ael8-66685b609d14

---

---

---

---