asciinema

Record and share terminal sessions

TLDR

Associate the local install of asciinema with an asciinema.org account

$ asciinema [[a|auth]]

Make a new recording and save it to a local file (finish it with or type exit)

$ asciinema [[r|record]] [path/to/recording.cast]

Replay a terminal recording from a local file

$ asciinema [[p|play]] [path/to/recording.cast]

Replay a terminal recording hosted on

$ asciinema [[p|play]] https://asciinema.org/a/[cast_id]

Make a new recording, limiting any idle time to at most 2.5 seconds

$ asciinema [[r|record]] [[-i|--idle-time-limit]] 2.5

Print the full output of a locally saved recording

$ asciinema [[ca|cat]] [path/to/recording.cast]

Upload a locally saved terminal session to asciinema.org

$ asciinema [[u|upload]] [path/to/recording.cast]

Stream the current terminal on a local webpage

$ asciinema [[st|stream]] --local

SYNOPSIS

asciinema [-h|--help] [-V|--version] <COMMAND> [<args>]

Commands: rec, play, cat, upload, auth, server, install, uninstall

PARAMETERS

-h, --help
Show help message and exit

-V, --version
Display asciinema version

Asciinema is a versatile open-source tool designed to record and replay terminal sessions with precise timing and styling. Unlike traditional screen recordings, it produces compact, JSON-based files called asciicasts (v2 format), which are lightweight, text-searchable, and easily embeddable in websites via the Asciinema player.

This makes it ideal for tutorials, demos, bug reports, and documentation. Sessions capture exact input/output, cursor movements, and colors from your shell.

Key workflow: Launch asciinema rec to begin recording (outputs a local .cast file), stop with Ctrl+D or exit. Replay locally with asciinema play file.cast, adjusting speed or idle time. Share by uploading to asciinema.org using asciinema upload, generating a unique URL for playback.

Supports custom commands, environment vars, titles, and limits like duration or idle detection. Cross-platform (Linux, macOS, BSD, WSL), with players for terminals, browsers, and VS Code. No root required; binaries available via package managers or direct download.

CAVEATS

Subcommands have extensive options; use asciinema <command> --help for details. Recordings may miss graphical elements outside terminal output. Uploads require account on asciinema.org.

POPULAR REC OPTIONS

-c CMD: Command to run; -t TITLE: Set title; -d SECS: Duration limit; --idle-time SECS: Idle detection; -w COLS x ROWS: Terminal size

POPULAR PLAY OPTIONS

-s SPEED: Playback speed (e.g. 2x, 10x); --idle-time SECS: Skip idle; -w COLS x ROWS: Set dimensions

HISTORY

Created by Marek Kašík in 2013 as a modern alternative to tools like script(1). Initial release on GitHub; reached v1.0 in 2014. Evolved to asciicast v2 JSON format (2015) for better web support. Actively maintained with 10k+ stars; binaries for easy install since v2.0 (2018). Widely used in docs, CI/CD, and education.