Skip to content

Quick start

This guide shows how to use asciinema CLI for recording, replaying and publishing terminal sessions.

For a broader overview of what's possible with asciinema check out the intro guide.

Install asciinema CLI

asciinema CLI is available in most package repositories on Linux, macOS, and FreeBSD. Search for a package named asciinema.

pipx install asciinema
sudo apt install asciinema
sudo pacman -S asciinema
brew install asciinema

Check the Installation section for all installation options.

Record a terminal session

To start a recording session use the rec command:

asciinema rec demo.cast

When done, press ctrl+d or enter exit to end the recording.

Instead of recording a shell you can record any command with --command / -c option:

asciinema rec -c htop demo.cast

The recording ends when you exit htop by pressing its q shortcut.

Replay directly in a terminal

To replay a recording in your terminal use play command:

asciinema play demo.cast

To replay it with double speed use --speed / -s option:

asciinema play -s 2 demo.cast

A unique feature of asciinema is the ability to optimize away idle moments in a recording using the --idle-time-limit / -i option:

asciinema play -i 2 demo.cast

You can pass -i 2 to asciinema rec as well, to set it permanently on a recording. Idle time limiting makes the recordings much more interesting to watch. Try it!

Share via

If you want to watch and share it on the web, upload it:

asciinema upload demo.cast

The above command uploads it to, which is a default asciinema server instance, and prints a secret link you can use to watch your recording in a web browser.


This step is completely optional. You can embed your recordings on a web page with asciinema player, or publish them to a self-hosted asciinema server instance.

Record and publish in one command

If you ommit the filename the recording is saved to a temporary file. When the recording session ends asciinema enters interactive mode, which lets you decide what to do:

$ asciinema rec
asciinema: recording asciicast to /tmp/tmpo8_612f8-ascii.cast
asciinema: press <ctrl-d> or type "exit" when you're done
$ echo hello
$ exit
asciinema: recording finished
(s)ave locally, (u)pload to, (d)iscard
[s,u,d]? _


This behaviour is likely to change in v3.0 of the CLI. Recording without filename will either be prohibited or will default to saving a file in a current directory.


These are the basics, but there's much more. See the Usage section for detailed information on each command of the CLI.

If you're interested in sharing your recordings via please familiarize yourself with docs on asciinema upload and asciinema auth commands.

Happy recording!