asciinema README

The project's README from github.com/asciinema/asciinema. As one markdown file: README.md.

asciinema

Build Status license

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.

asciinema CLI demo

Notable features:

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

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

This requires the Rust toolchain (1.82 or later) with Cargo, installed via your system package manager or rustup.

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

Alternatively, you can build from a local checkout. First download the source code:

git clone https://github.com/asciinema/asciinema
cd asciinema

The recommended way to get the toolchain is the Nix dev shell, which provides everything needed and just works:

nix develop

If you don't use Nix, you need Rust with Cargo, as above.

Then build the binary with:

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.

For toolchain setup and build instructions, see Building. Run the test suite with cargo test.

If you'd like to propose or submit any changes, please read the contribution guidelines first.

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:

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.

asciinema (asciinema/asciinema)

Searching Database…

17.9K ·GitHub
Asciinema
What is this?It's a command-line tool for recording and live-streaming terminal sessions. Instead of heavyweight video, it saves lightweight asciicast (.cast) files you can replay in a terminal, embed on a web page, or publish to asciinema.org.
Does it record video, like a regular screen recorder?No video is involved: it runs inside the terminal and captures output as text-based .cast files, with native zstd-compressed (.zst) recordings averaging just 8% of the original size. Recordings can also be converted to raw terminal output or plain text.
How do I install it and start recording?Build it from source: install the Rust toolchain (1.82 or later) with Cargo via rustup or your package manager, then run the README's one-shot build command — the binary lands in $HOME/.cargo/bin. Capturing a session is then a single command run in your shell.
Will it work on my Windows machine?No — Windows is currently not supported (tracked in issue #467), and the README points Windows users to PowerSession instead. asciinema runs on GNU/Linux, macOS and FreeBSD.
Can people watch my terminal session live while I work?Yes — it streams to multiple viewers in real time, locally via a built-in HTTP server with an embedded web player for LAN/localhost, or remotely through a relay like asciinema.org. It can even record to a file while streaming at the same time.
What can I control while a recording is running?Customizable key bindings let you pause/resume capture and add markers on the fly. It can also capture keyboard input and environment variables, and stores session metadata like terminal size, theme, command, and title.
What does playback look like?Replays run in the terminal with adjustable speed, looping, idle time limiting, step-by-step navigation, pause-on-markers, and optional terminal auto-resize. You can play from stdin or HTTP(S) URLs, not just local files.
Can I use it in scripts or CI?Yes — a headless mode with configurable terminal window size and exit-status propagation makes recording and streaming scriptable and CI-friendly.
What are similar projects?hexyl, nginx-rtmp-module, you-get, edit, hydra, Sunshine, soundcraft, Captura
Which topics is it in?terminal-app, capture, screen-recorder, remote, recording, player, http-server, resume, freebsd, real-time, streaming, bsd
Creator
asciinema
Size
4.9 MB
Stars
17.9K
Updated
CommitAug 14Releasev3.2.1Jun 16
Age
14y
Commits · 90 Days