starred/asciinema
1
0
Fork 0
mirror of https://github.com/asciinema/asciinema.git synced 2026-04-24 23:45:50 +03:00
Code Issues 8 Projects Releases 5 Packages Wiki Activity
5 releases 35 tags
  • v3.0.0 f21ff096f0

    v3.0.0 Stable

    kerem released this 2025-09-15 18:37:39 +03:00 | 79 commits to develop since this release

    📅 Originally published on GitHub: Mon, 15 Sep 2025 15:44:23 GMT
    🏷️ Git tag created: Mon, 15 Sep 2025 15:37:39 GMT

    This is a complete rewrite of asciinema in Rust, upgrading the recording file format, introducing terminal live streaming, and bringing numerous improvements across the board.

    Check out the announcement blog post for high level overview. Refer to the changelog for the complete list of changes.

    Thanks to all the contributors who helped making it better, specifically @xfgusta, @gnachman, @mustafamohsen. Very special thanks to @moritzdietz for feedback, testing and fixes! Last but not least, thanks to @storpool for sponsoring work on several features that landed in this release.

    Below is an overview of the most notable changes since 2.4.

    New features

    stream command

    The new stream command enables terminal session live streaming, providing local mode (built-in HTTP server) and remote mode (relaying via asciinema server).

    Local mode uses built-in HTTP server, allowing viewing of the stream on trusted networks (e.g. LAN). In this mode no data is sent anywhere, except to the viewers' browsers, for which you need to open a firewall port. The CLI bundles latest version of asciinema player, and uses it to connect to the stream from the page served by the built-in server.

    $ asciinema stream --local
::: asciinema session started
::: Live streaming at http://127.0.0.1:37881
::: Press <ctrl+d> or type 'exit' to end
$ _

    Remote mode publishes the stream through asciinema server (either asciinema.org or a self-hosted one), which acts as a relay, delivering the stream to the viewers at a shareable URL.

    $ asciinema stream --remote
::: asciinema session started
::: Live streaming at https://asciinema.org/s/TQGS82DwiBS1bYAY
::: Press <ctrl+d> or type 'exit' to end
$ _

    If you self-host asciinema server, and have automatic stream recording enabled, you can have a record of all your local sessions ready to be browsed and replayed.

    You can use --local and --remote modes together as well. Check out asciinema stream --help for all options.

    More details about how asciinema server implements streaming can be read here.

    session command

    The new session command allow for simultaneous recording and streaming. It's a more generic version of rec and stream combined.

    $ asciinema session -l -r -o demo.cast`
::: asciinema session started
::: Recording to demo.cast
::: Live streaming at http://127.0.0.1:43829
::: Live streaming at https://asciinema.org/s/SG82TQYDbYAwiB1S
::: Press <ctrl+d> or type 'exit' to end
$ _

    Check out asciinema session --help for all options.

    convert command

    The new convert command performs recording conversion between asciicast versions, and allows exporting to plain text log or raw output.

    You can convert asciicast v2 recording to asciicast v3 format like this (v3 output is default):

    asciinema convert demo-v2.cast demo-v3.cast

    Or, you can convert asciicast v3 recording to asciicast v2 format like this:

    asciinema convert -f asciicast-v2 demo-v3.cast demo-v2.cast

    You can also export a recording to a plain text log view, without any escape sequences, color information, just pure text as if you copied terminal's contents into a clipboard at the end of the session:

    asciinema convert demo.cast demo.txt

    The output format is inferred to be txt from the file extension, but you can be explicit about it:

    asciinema convert -f txt demo.cast demo.log

    Check out asciinema convert --help for all options.

    asciicast v3 file format

    The new asciicast v3 file format is the new default output format for rec, session and convert commands.

    Notable changes in this new format:

    • it uses relative timestamps (intervals) for events, while v2 used absolute time (since session start) - this makes edits substantially easier
    • the header has been restructured, grouping related things together, e.g. all terminal related metadata is now under term
    • it supports new "x" (exit) event type for storing session exit status
    • it supports line comments with # character

    Terminal theme capture

    asciinema can now capture the actual terminal theme and save it in the recording file header under term.theme.

    This is done by querying a terminal for colors using OSC 4, OSC 10 and OSC 11 sequences. It works on terminals that support the above queries, which is most these days.

    asciinema player uses the saved theme when it's present in the recording file, falling back to its default built-in theme otherwise.

    Plain text output

    The plain text output mentioned earlier with the convert command can also be used with rec and the new session command.

    Similarly, this output format is inferred from the .txt file extension, and can be explicitly selected with --output-format txt.

    Note that, it's always possible to convert from asciicast to txt, but not in the reverse order because plain text output loses all metadata and timing information. Therefore it's typically better to default to asciicast output.

    Improvements

    Server URL prompt

    When using a command that integrates with asciinema server (upload, stream, auth) for the first time, a new server URL prompt is shown, pre-filled with https://ascinema.org.

    This lets you choose an asciinema server instance explicitly and intentionally. Handy for self-hosted scenarios. The choice is saved for future invocations.

    If the server URL is preconfigured, either via config file or ASCIINEMA_SERVER_URL environment variable, then the prompt is not shown. The configuration also takes precedence over the URL entered at the prompt.

    Automatic creation of parent directories

    When recording to a file inside a non-existing directory, that directory (and all its parents) is now automatically created.

    This is useful for example when you want to record all your terminal sessions automatically with a shell config like this:

    # the very end of .bashrc
if [ -z "$ASCIINEMA_SESSION" ]; then
  exec asciinema rec ~/sessions/$(date '+%Y/%m/%d/%H-%M-%S')-$$.cast
fi

    Here asciinema will create directories for years, months and days that are present in the output path.

    Improved built-in documentation

    The --help messages have been significantly improved, containing detailed information about the effect and context for every option/flag. Make sure to use the long form --help instead of short h - the former is much more detailed!

    The new man pages contain similar amount of information as the --help output. They can be generated by setting ASCIINEMA_GEN_DIR to a desired man page output directory when building asciinema from source. See the README for details.

    Shell auto-completion

    Shell auto-completion files for bash, zsh and fish can now be generated at build time as well. Like with man page generation, this is done by setting ASCIINEMA_GEN_DIR.

    Breaking changes

    This major release is a good occasion for rethinking things and correcting mistakes from the past. We tried to keep it to a minimum though!

    No automatic uploads anymore

    Since the very first version of asciinema, the filename argument to asciinema rec was optional (this is historical, I talk about this more in the blog post). When not present, the recording was saved to a tmp file, uploaded to asciinema.org, then automatically deleted.

    This now changed - the filename is always required, and the rec command no longer has upload capability.

    To publish a recording to asciinema.org or a self-hosted asciinema server, use the explicit asciinema upload <filename>.

    asciicast v3 as the new default output file format

    This may or may not be a breaking change for you. If you don't use any custom tooling around asciicast files, then you probably won't see a difference, as both the asciinema server and player support the new format already.

    If you do use your own or community-provided tooling that reads asciicast files, then you may want to use --output-format asciicast-v2 with the rec command for backward compatibility.

    Changed behavior of the cat command

    The cat command in asciinema 2.x dumped the raw terminal output from one or more recording files. It both exported (converted) and concatenated.

    In 3.0, the cat command only concatenates. It expects at least two arguments, and outputs a new recording in the file format matching that of the first input file.

    You can use asciinema convert --output-format raw for the 2.x behavior.

    New config file format and location

    The user configuration file, previously at ~/.config/asciinema/config, has been moved to to ~/.config/asciinema/config.toml, and its format changed from "ini-style" to TOML.

    The most notable changes are:

    • the api section has been renamed to server
    • the record section has been renamed to session - the session for the rec, stream and session commands can now be configured there
    • the play section has been renamed to playback

    Check the configuration docs for details.

    How to get it

    You can download prebuilt asciinema CLI 3.0 binaries for GNU/Linux and macOS attached to this GitHub release (below), or build it from source.

    Happy recording!

    Downloads