asciinema - Terminal Session Recording

asciinema records terminal sessions as lightweight text-based files (not video), creating shareable, copy-pasteable recordings perfect for documentation and tutorials.

Key advantage: Recordings are text files (.cast), searchable, copy-pasteable, and ~1000x smaller than screen recordings.

Installation

macOS:

bash
brew install asciinema

Linux:

bash
# Debian/Ubuntu
sudo apt install asciinema

# Arch
sudo pacman -S asciinema

# Fedora
sudo dnf install asciinema

Basic Recording

Start recording:

bash
asciinema rec

• Terminal prompt shows [REC] indicator
• Everything you type is recorded
• Ctrl-D to stop recording

Save and upload:

bash
asciinema rec
# Do stuff...
# Ctrl-D to stop
# Prompted to upload or save locally

Save locally (no upload):

bash
asciinema rec demo.cast
# Do stuff...
# Ctrl-D saves to demo.cast

Playing Recordings

Play local file:

bash
asciinema play demo.cast

Controls during playback:

• Space - Pause/resume
• . - Step forward (when paused)
• Ctrl-C - Quit

Copy text from playback:

1. Pause with Space
2. Select text with mouse
3. Copy normally
4. Resume with Space

This is the magic - users can copy commands directly from your "video"!

Recording Options

Set title:

bash
asciinema rec --title "Docker Setup Tutorial"

Idle time limit (skip long pauses):

bash
asciinema rec --idle-time-limit 2
# Pauses > 2 seconds get compressed to 2s

Overwrite existing file:

bash
asciinema rec --overwrite demo.cast

Append to existing recording:

bash
asciinema rec --append demo.cast

Sharing Recordings

Option 1: Upload to asciinema.org

Upload after recording:

bash
asciinema rec
# Ctrl-D
# Choose 'yes' to upload
# Returns shareable URL

Upload existing file:

bash
asciinema upload demo.cast

Result: Public URL like https://asciinema.org/a/AbC123

Embedding:

html
<script src="https://asciinema.org/a/AbC123.js" id="asciicast-AbC123" async></script>

Option 2: Self-Host Server

Run local server:

bash
# Clone asciinema-server repo
git clone https://github.com/asciinema/asciinema-server.git
cd asciinema-server
docker-compose up

Upload to your server:

bash
asciinema upload --server https://your-server.com demo.cast

Option 3: Convert to GIF/Video

Using agg (asciinema GIF generator):

bash
# Install agg
cargo install --git https://github.com/asciinema/agg

# Convert to GIF
agg demo.cast demo.gif

Options:

bash
# Custom speed (1.0 = realtime, 2.0 = double speed)
agg --speed 2.0 demo.cast demo.gif

# Set dimensions
agg --cols 80 --rows 24 demo.cast demo.gif

# Set font size
agg --font-size 14 demo.cast demo.gif

# Custom theme
agg --theme monokai demo.cast demo.gif

Result: Shareable GIF for Slack, email, documentation.

Educational Use Cases

Tutorial Documentation

Record command sequences:

bash
asciinema rec docker-setup.cast --title "Docker Installation Guide"

# Demonstrate commands with explanations
echo "# Installing Docker on Ubuntu"
sudo apt update
sudo apt install docker.io
docker --version
echo "# Testing Docker"
docker run hello-world

Benefits:

• Students can pause and copy exact commands
• No typos from transcribing
• Searchable text (not OCR-ed video)

Student Submissions

Students record terminal work:

bash
# Student records lab completion
asciinema rec lab3-completion.cast
# Complete assignment...
# Upload and share URL with instructor

Instructor can:

• See exact commands used
• Verify process, not just results
• Copy commands to test locally
• Search for specific errors

Code Review Sessions

Record debugging session:

bash
asciinema rec --idle-time-limit 3 debug-session.cast
# Walk through code, show git diffs, run tests
# Share with team

Team can:

• Pause at any point
• Copy commands to reproduce
• See thought process in real-time

SWC Canvas Integration Ideas

Embed in Canvas pages:

html
<!-- In Canvas HTML editor -->
<script src="https://asciinema.org/a/YourCastID.js" 
        id="asciicast-YourCastID" 
        async 
        data-autoplay="true" 
        data-loop="true"></script>

Or link to GIF:

markdown
![Docker Setup Tutorial](https://your-site.com/docker-setup.gif)

Advanced Features

Custom Prompts/Metadata

Add environment info:

bash
asciinema rec \
  --title "Zellij Setup" \
  --env SHELL,TERM,USER \
  zellij-demo.cast

Speed Control

Record at normal speed, play faster:

bash
# Record normally
asciinema rec demo.cast

# Play at 2x speed
asciinema play --speed 2 demo.cast

Or set default speed:

bash
# In ~/.config/asciinema/config
[play]
speed = 2.0

Streaming (Live Recording)

Stream to asciinema.org:

bash
asciinema rec --stream
# Returns URL viewers can watch LIVE

Use case: Live terminal-based lectures.

File Format

.cast files are JSON:

json
{
  "version": 2,
  "width": 80,
  "height": 24,
  "timestamp": 1234567890,
  "env": {"SHELL": "/bin/zsh", "TERM": "xterm-256color"}
}
[0.123, "o", "$ ls\r\n"]
[1.456, "o", "file1.txt  file2.txt\r\n"]

Advantages:

• Text-based (Git-friendly)
• Editable (fix mistakes!)
• Compressible
• Searchable

Edit recordings:

bash
# Open demo.cast in text editor
nvim demo.cast

# Search for timestamp, delete unwanted sections
# Save and play

File Size Comparison

10-minute terminal session:

• Screen recording (video): ~50-100 MB
• asciinema (.cast): ~50-100 KB
• asciinema GIF: ~5-10 MB

1000x smaller than video!

Best Practices

Start with a clean slate:

bash
# Clear screen before recording
clear
asciinema rec demo.cast

Narrate as you go:

bash
echo "# Step 1: Install dependencies"
sudo apt install package
echo "# Step 2: Configure"
./configure

Use idle-time-limit:

bash
# Skip thinking pauses
asciinema rec --idle-time-limit 2 demo.cast

Test before sharing:

bash
asciinema play demo.cast
# Verify it looks good

Add titles for organization:

bash
asciinema rec --title "Week 3: Git Workflows" week3.cast

Tips for Educational Content

Demo-first, explain-later workflow:

1. Record demo (pure terminal work)
2. Convert to GIF
3. Embed in article with written explanation
4. Include .cast file for copy-paste

Create command cheat sheets:

bash
# Record common command sequences
asciinema rec docker-cheatsheet.cast

# Commands shown in recording:
docker ps
docker images
docker run -d nginx
docker logs <container>
docker exec -it <container> bash

Students watch once, copy commands as needed.

Progressive complexity:

• Week 1: Basic commands (short recordings)
• Week 2: Piping and filtering (medium)
• Week 3: Scripting (longer sessions)

Each with .cast files for reference.

Integration with Obsidian

Link recordings in notes:

markdown
## Docker Setup

Recording: [docker-setup.cast](file:///path/to/docker-setup.cast)

Watch with: `asciinema play docker-setup.cast`

Key commands:
- `docker run hello-world`
- `docker ps -a`

Or embed GIFs:

markdown
![Docker Demo](_attachments/docker-demo.gif)

Comparison: asciinema vs Screen Recording

Common Workflows

Quick demo for colleague:

bash
asciinema rec --idle-time-limit 2
# Show the thing
# Ctrl-D
# Upload and send URL

Tutorial for documentation:

bash
asciinema rec tutorial.cast --title "Getting Started"
# Record thorough walkthrough
# Convert to GIF
agg --speed 1.5 tutorial.cast tutorial.gif
# Embed in docs

Student lab verification:

bash
# Student:
asciinema rec lab-submission.cast
# Complete lab...
# Upload and submit URL

# Instructor:
asciinema play <student-url>
# Verify process and results

Links

asciinema Official Site

• URL: https://asciinema.org↗
• Summary: Terminal session recorder with text-based format
• Related: agg, Terminal Workflows

NetworkChuck Video: 37 INSANE Linux Commands

• URL: https://www.youtube.com/watch?v=6P-vjgPx9ww↗
• Summary: Features asciinema as one of the most amazing CLI tools
• Related: Lazy Docker, Mosh, Wormhole