asciinema

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

$ asciinema auth

$ asciinema rec [path/to/recording.cast]

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

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

$ asciinema rec [[-i|--idle-time-limit]] 2.5

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

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

asciinema [global-options] <command> [command-options] [arguments]

Common commands:
  asciinema record [filename] [options]
  asciinema play <filename|url> [options]
  asciinema upload <filename>
  asciinema auth
  asciinema cat <filename|url>
  asciinema config <subcommand>

record [filename]
    Records a new terminal session. If filename is omitted, a temporary file is used and automatically uploaded to asciinema.org upon exit.

record -i , --idle-time-limit
    Limits recorded idle time to N seconds. Any idle time exceeding this will be truncated.

record -c , --command
    Specifies the command to record. Defaults to $SHELL if not provided.

record -t , --title
    Sets the title of the recording, which is displayed on asciinema.org.

record --append
    Appends new recording to an existing .cast file.

record --overwrite
    Overwrites an existing .cast file.

record --raw
    Records raw terminal output, without timing information. This results in a plain text file.

play
    Plays an existing .cast file or a recording directly from an asciinema.org URL.

play -s , --speed
    Sets the playback speed (e.g., 0.5 for half speed, 2.0 for double speed). Valid range: 0.1-5.0.

play -i , --idle-time-limit
    Limits displayed idle time during playback to N seconds.

play -w x, --window-size x
    Overrides the terminal dimensions during playback (e.g., 80x24).

upload
    Uploads a local .cast recording to asciinema.org.

auth
    Links your local asciinema installation with your asciinema.org account, enabling you to manage your uploaded recordings.

cat
    Dumps the full output of a recording to standard output (stdout), useful for piping to other commands.

--version
    Displays the asciinema version information.

asciinema is a free and open-source command-line tool that allows you to record your terminal sessions and replay them in a browser or directly in the terminal. It's an excellent utility for creating software demos, debugging terminal interactions, or sharing command-line workflows.

Unlike traditional video recordings, asciinema captures terminal output as plain text with timing information, resulting in lightweight files. These recordings can be played back at different speeds, paused, or even copied directly from the displayed text. It supports uploading recordings to the asciinema.org website for easy sharing and embedding, making it a popular choice for documentation and tutorials.

Due to its text-based nature, asciinema cannot record graphical applications or non-textual terminal output (e.g., images). While recordings are lightweight, very long sessions can still generate large .cast files. Sharing recordings publicly on asciinema.org requires awareness of any sensitive information that might be displayed in the terminal during recording.

asciinema recordings are stored in a simple, human-readable JSON-based format (.cast files). This format includes metadata (e.g., terminal dimensions, timestamp, title) and an array of events, where each event represents a terminal output chunk along with a timestamp indicating when it occurred. This open format allows for easy parsing and manipulation of recordings.

The asciinema.org website serves as a public hosting and embedding platform for asciinema recordings. Users can upload their recordings, which are then playable directly in a web browser. The platform provides embedding code, making it easy to integrate recordings into blogs, documentation, and websites, enhancing their utility for tutorials and demonstrations.

asciinema was created by Marcin Kulik, with its first stable release (version 1.0) in late 2011/early 2012. It emerged as a lightweight, text-centric alternative to traditional screen recorders for terminal use, emphasizing the open .cast file format and the complementary asciinema.org platform for sharing. It quickly gained popularity in the Linux community for its simplicity and effectiveness in documenting terminal workflows.

script(1), tmux(1), screen(1), byobu(1)