Asciinema: making movies at the command-line

In open-source circles there are many situations, such as bug reports, demos, and tutorials, when one might want to provide a play-by-play of a session in one's terminal. The asciinema project provides a set of tools to do just that. Its tools let users record, edit, and share terminal sessions in a text-based format that has quite a few advantages compared to making and sharing videos of terminal sessions. For example, it is easy to use, offers the ability to search text from recorded sessions, and allows users to copy and paste directly from the recording.

History

Marcin Kulik started the project in 2011; it was originally called "ascii.io" and then renamed to asciinema and published to the Python Package Index (PyPI) in 2013. The asciinema project now consists of several parts: a command-line interface (CLI) recorder and player, a web player, the asciicast file format for recordings, the agg utility to create animated GIFs, and the asciinema virtual terminal (avt) used by the project's other components.

Each project has its own license; the asciinema CLI and agg are available under the GPLv3, while the other components are Apache 2.0-licensed. The project's components have undergone a number of changes and rewrites in the past 13 years. Version 3.0 of the CLI, released in September 2025, featured a complete rewrite in Rust, as well as an updated (v3) file format.

The project provides hosting for recordings on asciinema.org for users who don't mind storing them with a third party. The terms of service seem fairly standard for an open-source project that provides content hosting. LWN readers can explore some of the published recordings to get a sense of how others are using the tools. I should note that the project seems to have done a good job keeping recordings online: I have recordings from 2017 that are still available.

The server software is open-source too, of course, for those who prefer to self host. It is written in Elixir and uses the Phoenix Framework; the server is available under the Apache 2.0 license. The most recent server release, v20251114 from November 2025, included new search features and stricter validation of uploaded asciicast files.

Setting the stage

The asciinema CLI is packaged for most popular Linux distributions, but in some cases the available version is outdated. Debian 13, for example, has the 2.4.0 release from October 2023. The project provides Linux binaries for x86-64 with each release, or users can choose to use Rust's cargo to build from source.

After installing the CLI, the asciinema command can be used to record terminal sessions, play them back, or upload the recording to asciinema.org (or another server). For example, this command will record a terminal session to the file lwn.cast:

    $ asciinema rec -i 1 --window-size 80x24 lwn.cast

The use of rec tells asciinema to record, -i 1 optimizes the recording to get rid of any idle moments in the recording longer than one second. That can be fairly useful when recording demos, to get rid of any pauses between composing commands, etc. The --window-size option does what it says on the tin; it sets the terminal window size for the session to the number of columns and rows specified.

As the "how it works" page explains, asciinema captures all terminal output, including window resize events as well as the escape and control sequences in their unfiltered form. By default, asciinema does not record keyboard input (lest it record passwords, for example) but that can also be enabled with the -I option.

The lwn.cast file is plain text; by default, asciinema rec saves a session as an asciicast v3-formatted file, which is a newline-delimited JSON format. Opening the v3 file output in a text editor will show that the first line has metadata about the version of asciinema used, size of the terminal, environment variables, and so forth. The rest of the file includes a line for every element in the event stream—that is, basically each line output to the terminal during the recording session. Each line is a JSON array with the following fields:

    [interval, code, data]

The interval is the time since the previous event, in seconds. The code is the type of event, such as "o" for output, "i" for input, "m" for a marker used for playback or navigation, and so forth. The rest of the line is the data in UTF-8 encoding.

The v2 format, used by the 2.x versions of asciinema, is also still available as an output option with asciinema 3.x in order to share recordings with users who have not upgraded. Or one can use the "asciinema convert" option to take a v3 recording and output it as v2. The CLI also offers a raw output format that includes the raw terminal output without timing or metadata and a plain-text format that does not include control sequences or colors in the output.

Performance

I've found asciinema particularly useful in the past for recording demos and sharing them as embeds for blog posts or to play back during talks. Fumbling around on the keyboard during a talk is not my favorite thing to do, and if something can go wrong during a live demo, it probably will. Prerecording a session's demos not only makes for a smoother presentation; it allows a speaker to share the demos for the audience to review later. An asciinema recording can be a helpful supplement to provide along with slides and video of a talk.

The "asciinema play filename.cast" command plays a session recording back in the terminal. The terminal-based player is a bit limited in terms of controls; it only supports pausing with the "Space" key, stepping through the recording one frame at a time with the "." key, or advancing to a marker by pressing "]". A marker is similar to a chapter on a DVD or a track on a CD.

The web-based player is written in JavaScript and Rust (compiled to WebAssembly). The project has a quick start that demonstrates how to embed the player on a web page without needing to host a separate asciinema server. If a recording is hosted on asciinema.org or another server, it can be embedded in a web page with a "<script>" tag. The web version is more full-featured than the CLI player; it allows rewinding and fast-forwarding playback, stepping backward and forward through a recording, and more. It is also possible to link directly to a specific time in a video by appending something like "?t=M:SS", where M would be the minutes and SS would be the seconds.

Users can copy and paste from the CLI or web-based players, which can make asciinema recordings quite useful for tutorials or otherwise sharing with coworkers or collaborators. Showing a coworker how to do something at the terminal is easy as pie when they can watch a realtime recording of it being done and pause to copy the commands to their own terminal. Likewise, it may be a useful format to include with bug reports and the like; why settle for a log file when it's possible to include a detailed session that shows exactly what happens when a bug is encountered?

The 3.0 release added two new commands for live streaming terminal sessions, "asciinema stream" and "asciinema session". The "stream" command publishes a live stream either through a built-in HTTP server, or by feeding the stream through an asciinema server as a relay. The "session" command allows a user to live stream a session and record it to a file at the same time. That can be ideal if one has to do a live demo for coworkers and save it for posterity as well.

Prior versions of asciinema made it too easy to accidentally upload recordings, but that is no longer the case. Users must specify a filename when recording a session, and uploading is a manual step that requires the user to pick a server to upload to. To upload a recording, use "asciinema upload recording.cast". Note that the project allows users to upload recordings that are not linked to an account; those sessions are deleted after seven days. Recordings associated with an account are preserved indefinitely. Here is a basic demo created with asciinema that shows its ability to capture rich terminal output:

Assuming one has JavaScript enabled, the embedded player should show up above this sentence. Note that this demonstrates another feature of asciinema; it allows setting a terminal theme for playback that is different from the terminal settings used to record a session. I've chosen the "Monokai" theme here so that the player will stand out more for readers who have the site set to dark mode.

The project provides Linux container images for those who would like to self host the asciinema server using Docker, Podman, or Kubernetes. The quick start instructions include a configuration to run all of its services with Docker Compose. There is also a high-level explanation of the configuration for those who want to understand what's going on under the hood; it may be helpful for those who wish to try running the services with a different container manager or without one entirely.

The project is largely a one-person show; there are a number of contributors to the various components, but Kulik has thousands of commits to each repository, while those of other contributors tend to number in the single digits. Kulik has kept the project running pretty well for nearly 15 years; it is mature, updates come out regularly, and he seems to care about maintaining backward compatibility for asciinema's users. There is a Discourse forum for users to discuss the project, and the project is on the fediverse for those who would like to keep up with updates.