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 asciinema.org¶
If you want to watch and share it on the web, upload it:
asciinema upload demo.cast
The above command uploads it to asciinema.org, which is a default asciinema server instance, and prints a secret link you can use to watch your recording in a web browser.
Note
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
hello
$ exit
asciinema: recording finished
(s)ave locally, (u)pload to asciinema.org, (d)iscard
[s,u,d]? _
Note
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.
Next¶
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 asciinema.org please familiarize yourself with docs on asciinema upload and asciinema auth commands.
Happy recording!