Asciicast Expect

The asciinema expect subcommand runs a scripted terminal scenario and exports an asciicast recording, an animated GIF, an H.264 MP4, and named PNG snapshots. Recording is provided by this fork of asciinema; GIF and snapshot rendering use the bundled Rust dependency on agg; MP4 encoding uses a system ffmpeg executable.

Install this fork with Cargo:

cargo install --locked --git https://github.com/trdthg/asciinema

Scenarios use ordinary shell input plus #$ directives. This complete gcc-hello.sh example creates a C source file with a heredoc, compiles it, and runs the result. #$ snapshot writes a named PNG snapshot at that point in the terminal session:

#$ expect \$

#$ snapshot before-create-source
cat > hello.c <<'EOF'
#include <stdio.h>

int main(void) {
    puts("Hello, expect!");
    return 0;
}
EOF
#$ expect \$
cat hello.c
#$ expect \$
#$ snapshot after-create-source

#$ snapshot before-compile
gcc -Wall -Wextra -std=c11 hello.c -o hello
#$ expect \$
#$ snapshot after-compile

#$ snapshot before-run
./hello
#$ expect Hello, expect!
#$ expect \$
#$ snapshot after-run

Scenario directives

Every directive starts with #$. Other non-comment lines are typed into the shell and submitted with Enter.

Directive	Description
#$ expect REGEX	Wait until terminal output matches REGEX. The command fails after --timeout seconds.
#$ snapshot LABEL	Add a named point to the recording and export a PNG named after LABEL.
#$ delay MILLISECONDS	Set the delay between characters typed by subsequent shell commands and send directives.
#$ wait MILLISECONDS	Set the pause before each subsequent scenario instruction.
#$ send TEXT	Send TEXT without pressing Enter. Standard escapes such as \n, \r, and \t are decoded.
#$ sendcharacter TEXT	Send TEXT literally, without escape decoding or pressing Enter.
#$ sendcontrol LETTER	Send an ASCII control key, for example #$ sendcontrol c for Ctrl-C.
#$ sendarrow DIRECTION [COUNT]	Send up, down, left, or right arrow keys. COUNT defaults to 1.
#$ sendlinearrow DIRECTION [COUNT]	Send an arrow key followed by Enter, repeated COUNT times.

SSH session

An interactive SSH session can be part of a scenario when the target host is already configured for non-interactive authentication:

#$ expect \$
ssh work@localhost
#$ expect \$
uname -a
#$ expect \$
exit
#$ expect \$

exit is required: it closes the remote shell and returns to the local shell before the recorder sends its final EOF. Without it, the outer shell remains open and the scenario does not finish cleanly.

Run it with an explicit .sh filename:

asciinema expect gcc-hello.sh

Use --monitor to view raw PTY input and output in an alternate screen with a five-row progress display. The panel keeps the latest steps with source line, instruction type, and summary, and restores the previous screen before export begins.

For gcc-hello.sh, the command writes gcc-hello/gcc-hello.cast, gcc-hello/gcc-hello.gif, gcc-hello/gcc-hello.mp4, and PNGs below gcc-hello/snapshots/. Use --output-dir DIR, --theme THEME, --font-size PIXELS, or --ffmpeg PATH to customize output. The scenario's relative shell files, such as hello.c and hello, are created beside the scenario file.

asciinema

asciinema (aka asciinema CLI or asciinema recorder) is a command-line tool for recording and live streaming terminal sessions.

Unlike typical screen recording software, which records visual output of a screen into a heavyweight video files (.mp4, .mov), asciinema CLI runs inside a terminal, capturing terminal session output into a lightweight recording files in the asciicast format (.cast), or streaming it live to viewers in real-time.

The recordings can be replayed in a terminal, embedded on a web page with the asciinema player, or published to an asciinema server, such as asciinema.org, for further sharing. Live streams allow viewers to watch terminal sessions as they happen.

asciinema runs on GNU/Linux, macOS and FreeBSD.

Notable features:

• recording of terminal sessions to a file, with optional keyboard input capture and configurable environment variable capture,
• replaying of recordings inside a terminal, with adjustable speed, looping, idle time limiting, step-by-step navigation, pause-on-markers, and optional terminal auto-resize,
• local and remote live streaming of terminal sessions to multiple viewers in real-time, including a built-in HTTP server with an embedded web player for LAN/localhost viewing,
• combined sessions: record to a file while streaming locally and remotely at the same time,
• lightweight asciicast recording format, with native reading and writing of zstd-compressed (.zst) recordings (8% of the original size on average),
• conversion from asciicast v1/v2/v3 to asciicast v2/v3, raw terminal output, or plain text,
• concatenation of multiple recordings into one, with timing adjusted automatically,
• mid-session controls: pause/resume capture and add markers on the fly via customizable key bindings,
• session metadata capture, including terminal size, terminal theme, command, and title,
• configuration file support for defaults such as recording command, capture options, playback speed, idle time limit, notifications, and key bindings,
• headless mode, configurable terminal window size, and exit-status propagation for scripted and CI-friendly recording and streaming,
• support for stdin/stdout in conversion and playback from local files, stdin, or HTTP(S) URLs,
• integration with asciinema server, e.g. asciinema.org, for uploads, hosting, remote live streaming, self-hosted servers, visibility control, descriptions, and synchronized audio URLs.

To record a session run this command in your shell:

asciinema rec demo.cast

To stream a session via built-in HTTP server run:

asciinema stream -l

To stream a session via a relay (asciinema server) run:

asciinema stream -r

Check out the Getting started guide for installation and usage overview.

Building

Building asciinema from source requires the Rust compiler (1.82 or later), and the Cargo package manager. If they are not available via your system package manager then use rustup.

To download the source code, build the asciinema binary, and install it in $HOME/.cargo/bin in one go run:

cargo install --locked --git https://github.com/asciinema/asciinema

Then, ensure $HOME/.cargo/bin is in your shell's $PATH.

Alternatively, you can manually download the source code and build the asciinema binary with:

git clone https://github.com/asciinema/asciinema
cd asciinema
cargo build --release

This produces the binary at target/release/asciinema. You can just copy the binary to a directory in your $PATH.

To generate man pages and shell completion files, set ASCIINEMA_GEN_DIR to the path where these artifacts should be stored. For example:

ASCIINEMA_GEN_DIR=/foo cargo build --release

The above command will build the binary and place the man pages in /foo/man/, and the shell completion files in the /foo/completion/ directory.

Note

Windows is currently not supported. See #467. You can try PowerSession instead.

Development

All development happens on develop branch. This branch contains the current generation (3.x) of the asciinema CLI, written in Rust.

The previous generation (2.x), written in Python, can be found in the python branch.

If you wish to propose non-trivial code changes, please first reach out to the team via forum, Matrix or IRC.

Donations

Sustainability of asciinema development relies on donations and sponsorships.

If you like the project then consider becoming a supporter or a corporate sponsor.

asciinema is sponsored by:

• Brightbox

Consulting

If you're interested in integration or customization of asciinema to suit your needs, check asciinema consulting services.

License

© 2011 Marcin Kulik.

All code is licensed under the GPL, v3 or later. See LICENSE file for details.