asciinema : enregistrer, rejouer et partager ses sessions terminal

Documenter une procédure en ligne de commande avec des captures d’écran ou une vidéo, c’est lourd à produire et pénible à relire : impossible de copier une commande depuis une image. asciinema règle ce problème en enregistrant la session terminal sous forme de texte horodaté. Le résultat est léger, rejouable dans un terminal ou dans un navigateur, et le texte reste sélectionnable.

Cet article fait le tour de l’outil dans sa génération actuelle (CLI 3.x, réécrite en Rust) : installation, enregistrement, relecture, diffusion en direct, conversion, partage et intégration dans une page web.

Qu’est-ce qu’asciinema ?

asciinema est un outil en ligne de commande, sous licence GPL v3, qui enregistre et diffuse en direct des sessions terminal. Au lieu de filmer l’écran, il tourne dans le terminal et capture la sortie de la session dans un fichier au format asciicast (.cast). L’écosystème comprend trois briques :

asciinema CLI : l’enregistreur (commandes rec, play, stream, session, convert, cat, upload, auth) ;
asciinema player : un lecteur web en JavaScript pour intégrer les enregistrements dans n’importe quelle page ;
asciinema server : la plateforme d’hébergement et de partage, utilisable via asciinema.org ou auto-hébergée.

L’outil fonctionne sous GNU/Linux, macOS et FreeBSD. Windows n’est pas pris en charge nativement.

Pourquoi pas une simple vidéo ?

Poids : un fichier .cast est du texte (JSON ligne par ligne), quelques kilo-octets là où une vidéo pèse des mégaoctets. La CLI 3.x lit et écrit aussi nativement des enregistrements compressés en zstd (.zst).
Texte copiable : dans le lecteur web, on peut mettre en pause et copier une commande.
Rendu net à toutes les tailles, puisque le terminal est redessiné par le lecteur.
Éditable : le format est lisible et modifiable avec un éditeur de texte.

Installation

Via le gestionnaire de paquets

# Debian / Ubuntu
sudo apt install asciinema
# Fedora
sudo dnf install asciinema
# Arch Linux
sudo pacman -S asciinema
# macOS (Homebrew)
brew install asciinema

Attention à la version. Les dépôts des distributions ne fournissent pas toujours la génération 3.x. Sur Debian 13 « Trixie », par exemple, le paquet proposé est la version 2.4.0 (ancienne génération en Python), qui ne dispose ni de stream, ni de session, ni de convert. Vérifiez avec :

apt-cache policy asciinema
asciinema --version

Via le binaire officiel (recommandé pour la 3.x)

Le projet publie des binaires précompilés pour Linux (x86_64 glibc ou musl, aarch64) et macOS. À la date de rédaction, la dernière version est la 3.2.1 (16 juin 2026). Exemple pour Linux x86_64, avec vérification de l’empreinte SHA-256 publiée sur la page de release :

VER=v3.2.1
curl -fLo /tmp/asciinema \
  https://github.com/asciinema/asciinema/releases/download/${VER}/asciinema-x86_64-unknown-linux-gnu
echo "1b405bbda565b33c3c4718de67fedc3535580603c0694b1ff3fb04f363430a20  /tmp/asciinema" | sha256sum -c -
sudo install -m 0755 /tmp/asciinema /usr/local/bin/asciinema
asciinema --version

Pour une autre version ou une autre architecture, reprenez le nom du fichier et son empreinte sur la page des releases.

Autres méthodes

# Compilation depuis les sources (Rust 1.82+ requis)
cargo install --locked --git https://github.com/asciinema/asciinema

# Image conteneur officielle (allouer un TTY avec -it)
docker run --rm -it -v "$PWD:/data" --workdir=/data ghcr.io/asciinema/asciinema rec demo.cast

Enregistrer une session

asciinema rec demo.cast

Un nouveau shell démarre ; tout ce qui s’affiche est enregistré. Pour terminer : Ctrl+D ou exit. Depuis la 3.0, le nom de fichier est obligatoire et rec n’envoie plus rien automatiquement sur internet.

Options utiles :

# Titre + temps morts limités à 2 s
asciinema rec -t "Mise à jour Debian" -i 2 maj.cast

# Enregistrer une commande précise au lieu d'un shell interactif
asciinema rec -c "htop" htop.cast

# Ajouter à un enregistrement existant / écraser
asciinema rec -a demo.cast
asciinema rec --overwrite demo.cast

# Sortie texte brut (format déduit de l'extension)
asciinema rec session.txt

# Ancien format, pour des outils tiers qui ne lisent que le v2
asciinema rec --output-format asciicast-v2 demo-v2.cast

Le répertoire de destination est créé automatiquement s’il n’existe pas, ce qui permet par exemple d’archiver toutes ses sessions par date :

# à la toute fin de ~/.bashrc
if [ -z "$ASCIINEMA_SESSION" ]; then
  exec asciinema rec ~/sessions/$(date '+%Y/%m/%d/%H-%M-%S')-$$.cast
fi

Pendant l’enregistrement, des raccourcis clavier configurables permettent de mettre la capture en pause et d’ajouter des marqueurs (points de repère utilisables à la relecture). Voir la page des raccourcis et celle des marqueurs.

Rejouer dans le terminal

asciinema play demo.cast          # vitesse normale
asciinema play -s 2 demo.cast     # vitesse x2
asciinema play -i 1 demo.cast     # temps morts plafonnés à 1 s
asciinema play https://exemple.org/demo.cast   # lecture depuis une URL

La relecture gère aussi la lecture en boucle, la navigation pas à pas, la pause sur les marqueurs et le redimensionnement automatique du terminal. La liste complète des options est dans asciinema play --help (la forme longue --help est nettement plus détaillée que -h).

Diffuser en direct

Nouveauté de la 3.0 : la commande stream diffuse la session en temps réel.

# Mode local : serveur HTTP intégré + lecteur web, pour un réseau de confiance (LAN)
asciinema stream -l

# Mode distant : relais via un serveur asciinema (asciinema.org ou auto-hébergé)
asciinema stream -r

# Enregistrer ET diffuser en même temps
asciinema session -l -r -o demo.cast

En mode local, aucune donnée ne quitte la machine en dehors des navigateurs des spectateurs ; il faut en revanche ouvrir le port correspondant dans le pare-feu. Par défaut, le serveur écoute sur 127.0.0.1 ; pour une écoute sur le LAN, précisez l’adresse et le port (asciinema stream -l 0.0.0.0:8080, par exemple).

Convertir et concaténer

# Export en texte brut (sans séquences d'échappement), idéal pour une doc
asciinema convert demo.cast demo.txt

# Sortie terminal brute (équivalent de l'ancien « cat » de la 2.x)
asciinema convert -f raw demo.cast demo.raw

# Conversion entre versions du format
asciinema convert demo-v2.cast demo-v3.cast
asciinema convert -f asciicast-v2 demo-v3.cast demo-v2.cast

# Concaténer plusieurs enregistrements (timing ajusté automatiquement)
asciinema cat partie1.cast partie2.cast > complet.cast

La conversion vers le texte est à sens unique : le .txt perd le timing et les métadonnées. Mieux vaut donc toujours enregistrer en asciicast et convertir ensuite.

Le format asciicast v3

Un fichier .cast est du JSON délimité par des retours à la ligne : une première ligne d’en-tête (taille du terminal, titre, thème…), puis un événement par ligne sous la forme [intervalle, code, données]. Exemple minimal :

{"version": 3, "term": {"cols": 80, "rows": 24}, "title": "Demo"}
[0.250, "o", "$ uptime\r\n"]
[0.800, "o", " 10:42:01 up 12 days,  3:14,  1 user,  load average: 0.12, 0.08, 0.05\r\n"]
[1.500, "m", "Fin"]
[0.300, "x", "0"]

Principaux codes : o (sortie), i (saisie clavier, seulement si activée), m (marqueur), r (redimensionnement), x (code de sortie). Par rapport au v2, le v3 utilise des intervalles relatifs entre événements au lieu de temps absolus, ce qui facilite l’édition à la main, et accepte des commentaires préfixés par #. La CLI enregistre aussi automatiquement le thème de couleurs du terminal d’origine.

Partager sur un serveur asciinema

# Lier la machine à un compte sur le serveur
asciinema auth

# Publier un enregistrement (options --description, --visibility… : voir --help)
asciinema upload --title "Mise à jour Debian" maj.cast

Au premier usage d’une commande liée au serveur (upload, stream -r, auth), la CLI demande l’URL du serveur à utiliser, préremplie avec asciinema.org. On peut aussi la fixer via la variable ASCIINEMA_SERVER_URL ou le fichier de configuration, ce qui est pratique avec une instance auto-hébergée.

Intégrer un enregistrement dans une page web

Pas besoin de serveur asciinema pour afficher un enregistrement sur son site : le lecteur web suffit. On dépose le fichier .cast à côté de la page, puis on charge le CSS et le JS du lecteur (ici via le CDN jsDelivr, version 3.17.0, la dernière publiée sur npm au moment de la rédaction) :

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/asciinema-player@3.17.0/dist/bundle/asciinema-player.css" />

<div id="demo"></div>

<script src="https://cdn.jsdelivr.net/npm/asciinema-player@3.17.0/dist/bundle/asciinema-player.min.js"></script>
<script>
  AsciinemaPlayer.create('/casts/demo.cast', document.getElementById('demo'), {
    idleTimeLimit: 2,
    loop: false,
    theme: 'dracula',
    poster: 'npt:0:03'
  });
</script>

Le lecteur gère aussi les marqueurs (chapitres), le contrôle programmatique (player.play(), player.seek()…) et de nombreuses options d’affichage : voir la liste des options. Sous WordPress, ce code se colle dans un bloc « HTML personnalisé ». Pour ne pas dépendre d’un CDN, on peut aussi héberger soi-même les deux fichiers récupérés sur la page des releases du lecteur.

Obtenir un GIF

Quand une vraie image animée est nécessaire (README, forum, messagerie), le projet fournit agg, un générateur de GIF à partir de fichiers asciicast :

agg demo.cast demo.gif

Installation et options (police, thème, vitesse…) : documentation d’agg.

Configuration

Depuis la 3.0, la configuration utilisateur se trouve dans ~/.config/asciinema/config.toml (format TOML), avec un fichier système optionnel /etc/asciinema/config.toml. Les sections principales sont [server], [session] (paramètres de rec, stream et session) et [playback]. On y fixe par exemple l’URL du serveur, la limite de temps mort, la vitesse de lecture ou les raccourcis clavier.

mkdir -p ~/.config/asciinema
vi ~/.config/asciinema/config.toml

La liste exhaustive des clés est dans la documentation de configuration 3.x.

Sécurité : ce qui est capturé

Tout ce qui s’affiche est enregistré : un token, un mot de passe affiché par un cat ou une variable d’environnement imprimée se retrouvent en clair dans le fichier. Relisez le .cast (c’est du texte) avant de le publier.
La saisie clavier n’est pas capturée par défaut. L’option -I / --rec-input l’active ; elle enregistre alors aussi ce que vous tapez sans écho, mots de passe compris. À n’utiliser qu’en connaissance de cause.
Seule la variable SHELL est capturée par défaut ; n’ajoutez des variables (--rec-env) que si elles ne contiennent rien de sensible.
En diffusion locale, le flux est servi en HTTP clair : à réserver à un réseau de confiance.

Passer de la 2.x à la 3.x : ce qui change

Réécriture complète en Rust, binaire autonome sans dépendance Python.
rec exige un nom de fichier et ne téléverse plus rien : utilisez asciinema upload.
Le format par défaut devient asciicast v3 (le lecteur web le gère depuis sa version 3.10.0) ; --output-format asciicast-v2 reste disponible.
cat ne fait plus que concaténer ; l’ancien comportement passe par convert -f raw.
Configuration déplacée de ~/.config/asciinema/config (style INI) vers config.toml ; la variable ASCIINEMA_API_URL devient ASCIINEMA_SERVER_URL.
Nouveautés : stream, session, convert, capture du thème du terminal, propagation du code de sortie (--return), mode sans terminal (--headless) pour les scripts et la CI.

En résumé

asciinema est l’outil idéal pour documenter des procédures en ligne de commande : asciinema rec pour capturer, asciinema play pour relire, le lecteur web pour intégrer dans un wiki ou un blog, et convert pour en extraire le texte. La seule précaution notable concerne la version : si votre distribution fournit encore la 2.x, passez par le binaire officiel pour profiter de la diffusion en direct et du format v3.