The plan for the asciinema CLI 3.0

As of now, the develop branch of asciinema CLI repo contains a complete rewrite of the CLI in Rust, with all functionality from the previously released version 2.4 working, with some changes to upload behavior and command line options.

The notable changes from 2.4:

  • asciinema rec now requires a filename, and doesn’t do any uploading
  • Uploading to asciinema server, such as, can only be done by explicitly running asciinema upload <filename>
  • There’s no asciinema server URL configured by default. When executing asciinema upload or asciinema auth for the first time you’re presented with a prompt where you can enter a server URL (use either prefilled “” value or enter a URL of your own self-hosted server), which is saved for future CLI invocations. See this demo. You can also configure server URL in the config file.
  • The config file changed from ~/.config/asciinema/config (ini-like format) to ~/.config/asciinema/config.toml (toml format).
  • Added built-in support for displaying notifications (“recording paused/resumed”) in tmux’s status bar when tmux session is detected
  • Replaced --cols 80 / --rows 24 options of asciinema rec with --tty-size 80x24
  • Renamed --stdin option of asciinema rec to --input (+ added short variant -I)
  • Added short variant -a to --append for asciinema rec
  • --raw option of asciinema rec is now replaced with --format raw (or -f raw)
  • asciinema cat now concatenates multiple asciicast files producing asciicast instead of raw output
  • -e variant of --env in asciinema rec was removed (we may need short -e for something more frequently used in the future)

The above changes are not set in stone, they’re subject to further tweaking, so let me know if you have thoughts on those.

The naming of long and short options is something I’d like to review once more, across all subcommands, make them consistent and understandable at a glance.

Some of the changes could be classified as “breaking” (e.g. removal or renaming of command line options, or no upload functionality in rec), which is why I’m doing it for 3.0 release. There were no breaking CLI UX changes for 10 years, time to clean up / revamp.

Other than the above changes, for 3.0 I’d like to implement several new features, which I mentioned previously in the Rust rewrite intro post. The rough plan for additional 3.0 features is as follows:

  • asciinema stream - live stream a terminal session
  • asciinema convert input.cast output.(txt|gif) - convert asciicast recording into another format
  • asciinema rec <directory> - create a recording in a directory using a filename template (e.g. <timestamp>.cast)

To implement asciinema stream I plan to integrate relevant parts of the tst codebase. tst has 2 modes of operation: 1. as a server, 2. as a forwarder. asciinema stream will likely work in a similar way. In the server mode, it will launch an HTTP+Websocket server on a local port, serving a simple HTML page with asciinema player embedded and automatically connected to the live stream over the Websocket. In the forwarder mode, it will forward the live stream to asciinema server, which will present the stream in real-time at a URL like<id>, in similar fashion as regular recordings are displayed.

As for asciinema convert, the idea is to have a built-in support to convert asciicast files into other formats. GIF output is one example - while there’s agg, having ability to run asciinema convert demo.cast demo.gif without installing additional tools would probably be welcomed by some users. Another use case is conversion to pure text representation. In asciinema CLI 2.x there is asciinema cat, which prints the raw output of a session, but this raw output includes all escape codes / control sequences for cursor movement, color change, etc. Turns out users’ expectation was to get a clean text log of a session instead. So, as mentioned earlier, in 3.0 asciinema cat will only concatenate multiple cast files into a one long session, fixing the name/behavior mismatch (“cat” is short for “concatenate”). New asciinema convert demo.cast demo.txt will do the conversion to pure text log, and we can optionally implement conversion to raw output (what cat did in 2.x) with something like asciinema convert -f raw demo.cast demo.raw.

Finally, asciinema rec <directory> would let you record sessions en masse, without need for manually coming up with unique filenames for every recording. Running asciinema rec ~/casts, where ~/casts is an existing directory, would generate a filename from a (configurable) template, saving the recording with this filename in ~/casts directory. This could be useful for people who record all their terminal sessions automatically (e.g. by integrating asciinema rec in their .bashrc). And asciinema rec . would record to an auto-generated filename in the current directory.

Final thought: I’m on the fence about the addition of the above new features in 3.0. We could have 3.0 release with the old feature set (same as in 2.4) very soon (right away), as just a “rewrite release”, and then implement the new stuff for 3.1 and later versions. Or, we could implement the new stuff for 3.0, and release it when it’s ready (integrating tst and agg shouldn’t be a lot of work though). At the moment I’m leaning for the latter, that is have 3.0 include the new stuff outlined above. My reasoning is that, from a user’s point of view it wouldn’t really be an upgrade if there’s nothing new/improved (and an implementation language change is an implementation detail, irrelevant for most of the users).