Master Terminal Session Recording with Asciinema: Install, Record, Play & Audit

Asciinema is an open‑source, free terminal session recorder that saves command‑line input and output with timestamps, allowing playback in a terminal or web browser.

It consists of three sub‑projects: the asciinema recorder, the asciinema.org website with an API for uploading and displaying recordings, and a JavaScript player for web playback.

Installation

Asciinema is written in Python and can be installed via

apt‑get

,

yum

or

pip

:

<code># apt-get install asciinema</code>

After installation, check the version:

<code># asciinema --version<br/>asciinema 2.0.2</code>

Recording

Use

asciinema rec

to start a recording. Several options are available:

--stdin

– record standard input (e.g., passwords).

--append

– append to an existing file.

--raw

– save raw STDOUT without timing data.

--overwrite

– overwrite existing file.

-c

– command to run (default $SHELL).

-e

– environment variables to capture (default SHELL,TERM).

-t

– set a title.

-i

– maximum idle time.

-y

– answer yes to all prompts.

-q

– quiet mode (no prompts).

End a recording with

exit

or

Ctrl+D

.

Playback

Play a recording with

asciinema play file.cast

. Options include:

-s

– speed multiplier.

-i

– maximum idle time during playback.

During playback, space pauses/resumes,

Ctrl+C

quits, and “.” steps forward frame by frame.

File format

Recordings are stored in

.cast

files. The first line is a JSON header containing version, dimensions, timestamp, environment, and title. Subsequent lines are JSON arrays with three elements: elapsed time, a fixed string, and the actual output.

<code># cat ops-coffee.cast<br/>{"version":2,"width":237,"height":55,"timestamp":1572646909,"env":{"SHELL":"/bin/bash","TERM":"linux"},"title":"ops-coffee"}<br/>[0.010014, "o", "root@onlinegame:~# "]<br/>[1.296458, "o", "exit"]</code>

The format is compact, stream‑readable, and supports appending, making it suitable for long‑running sessions and audit logs.

Automatic audit logging

To record every user session automatically, add the following to

~/.bash_profile

for the target user:

<code>export LC_ALL=en_US.UTF-8<br>/usr/local/bin/asciinema rec /tmp/$USER-$(date +%Y%m%d%H%M%S).log -q</code>

The

-q

flag suppresses prompts, so a recording starts on each login. This provides a complete, searchable audit trail that captures both commands and their output, unlike the shell

history

command.