DEV Community

Cover image for Asciinema: The Secret Weapon for Better Documentation, Training, and Handovers
Anderson Leite
Anderson Leite

Posted on

Asciinema: The Secret Weapon for Better Documentation, Training, and Handovers

#documentation #devtools #productivity #tutorial

If you've ever tried to explain a complex terminal workflow through screenshots or struggled to document a series of CLI commands, you know the pain: Screenshots get outdated, videos are too large to embed, and written instructions often miss crucial context.

I'm using from few years now the asciinema, a lightweight tool that records your terminal sessions as text, making them shareable, searchable, and incredibly useful.

Here a quick example of how it works:

asciicast recorded

Which commands I issued to generate this gif?

asciinema rec --stdin demo.cast
echo 'Hello from asciinema!'
echo "I started this session with 'asciinema rec --stdin demo.cast'"
echo 'Will end it with ctrl + d (or exit) and convert this asciicast to a gif'
(ctrl + d to exit the asciinema session)
agg demo.cast demo.gif
(attached the file here... #stonks)
Enter fullscreen mode Exit fullscreen mode

And I can also upload a recorded asciicast, with asciinema upload demo.cast and it will be ending up at my profile, like this https://asciinema.org/a/Wjif8Ahd6obnzW8inKsNP1O1b

What Makes Asciinema Special?

Unlike traditional screen recordings, asciinema captures your terminal session as text-based data. This means:

  • Copy-pastable commands Viewers can select and copy commands directly from the playback
  • Lightweight files A 5-minute recording might be just 50KB instead of several megabytes
  • Searchable content Find specific commands or outputs quickly
  • Easy embedding Drop recordings into documentation, README files, or blog posts
  • Customizable playback Viewers can pause, rewind, and play at their own pace

Real-World Use Cases

1. Training and Onboarding

Imagine onboarding a new developer to your infrastructure. Instead of sitting through live demos or reading walls of text, they can follow along with an asciinema recording that shows:

  • Setting up development environments
  • Running deployment scripts
  • Debugging common issues
  • Navigating complex CLI tools

Example scenario: Recording a complete Docker setup process, from installation through creating a multi-container application. New team members can pause, copy commands, and follow at their own pace.

# Record your training session
asciinema rec docker-training.cast

# Share it via asciinema.org or embed in your docs
asciinema upload docker-training.cast
Enter fullscreen mode Exit fullscreen mode

2. Technical Documentation

Traditional documentation often separates explanation from execution. Asciinema bridges this gap by showing real-time context:

  • API testing workflows Demonstrate curl commands with actual responses
  • Configuration changes Show before/after states of config files
  • Troubleshooting guides Walk through debugging steps with live output
  • Tool comparisons Show side-by-side usage of different tools

The beauty? Your documentation shows exactly what users will see, including timing, errors, and recovery steps.

3. Handover Documentation

When transitioning projects or responsibilities, asciinema recordings become invaluable:

  • Document deployment procedures with all the edge cases
  • Capture one-time setup processes that are hard to remember
  • Show the "tribal knowledge" that usually lives only in senior developers' heads
  • Provide visual proof of system states and configurations

Pro tip: Combine asciinema recordings with markdown documentation. The written docs provide context and theory, while the recordings show practical execution.

4. Bug Reports and Support

Ever received a bug report that says "it doesn't work"? Asciinema recordings can transform support interactions:

  • Users can show you exactly what they tried
  • Support teams can provide step-by-step solutions
  • QA teams can document reproducible bugs
  • Developers can show expected vs. actual behavior

5. Conference Talks and Tutorials

Live coding demos are risky: Network issues, typos, and time pressure can derail presentations. Pre-recorded asciinema sessions:

  • Ensure smooth, error-free demonstrations
  • Can be edited to remove pauses or mistakes
  • Allow presenters to focus on explanation rather than typing
  • Provide attendees with a reference they can review later

6. Live Terminal Streaming

One of asciinema's lesser-known but powerful features is the ability to stream your terminal session live. This opens up exciting possibilities:

  • Remote pair programming Share your terminal with colleagues in real-time
  • Live coding sessions Stream terminal work to audiences without heavy video streaming infrastructure
  • Remote support Let support teams watch as users reproduce issues
  • Live workshops Conduct interactive terminal-based training sessions
  • Code reviews Walk through code changes in the terminal with distributed teams

How it works:

# Start streaming your terminal
asciinema rec --stdin --append

# Share the unique URL with viewers
# They can watch your terminal in real-time from their browser
Enter fullscreen mode Exit fullscreen mode

Unlike video streaming, asciinema streams are incredibly bandwidth-efficient since they're transmitting text data rather than video frames. Viewers can even copy-paste commands you're typing in real-time, making it perfect for hands-on training scenarios.

Use cases for streaming:

  • Live debugging sessions where multiple team members need to follow along
  • Real-time demonstrations during code reviews
  • Interactive workshops where participants can copy commands as you type
  • Remote infrastructure work where you want observers but don't want to share full screen access

Getting Started with Asciinema

Installation

Asciinema works on Linux, macOS, and Windows (via WSL):

# On macOS
brew install asciinema

# On Ubuntu/Debian
sudo apt-get install asciinema

# On Fedora
sudo dnf install asciinema

# Or via pip (cross-platform)
pip3 install asciinema
Enter fullscreen mode Exit fullscreen mode

Basic Usage

Recording is as simple as:

# Start recording
asciinema rec

# Do your work in the terminal
# Press Ctrl+D or type 'exit' to stop

# Upload and share
asciinema rec demo.cast
asciinema upload demo.cast
Enter fullscreen mode Exit fullscreen mode

Advanced Features

Set a recording title and add idle time limit:

asciinema rec -t "Kubernetes Deployment Tutorial" --idle-time-limit 2 k8s-demo.cast
Enter fullscreen mode Exit fullscreen mode

The --idle-time-limit flag compresses idle time in your recording, making it more viewer-friendly.

Live streaming your terminal:

# Stream your terminal session live
asciinema rec --stdin --append
# You'll get a URL that updates in real-time as you type
Enter fullscreen mode Exit fullscreen mode

Self-hosting:

# Host on your own server
asciinema rec --stdin demo.cast
# Upload to your custom asciinema-server instance
Enter fullscreen mode Exit fullscreen mode

Embedding in Documentation

Once uploaded to asciinema.org, you get an embed code:

<script src="https://asciinema.org/a/123456.js" id="asciicast-123456" async></script>
Enter fullscreen mode Exit fullscreen mode

Or embed locally using the asciinema-player JavaScript library in your docs website.

Converting to Animated GIFs

Sometimes you need a simple animated GIF instead of an interactive player, perfect for platforms that don't support JavaScript embeds, email newsletters, or legacy documentation systems.

Using agg (official tool):

Asciinema provides agg, a tool specifically for converting casts to GIFs:

# On MacOs
brew install agg

# Convert your recording to GIF
agg demo.cast demo.gif

# Customize the output
agg --font-size 20 --theme monokai demo.cast demo.gif

# Set specific dimensions
agg --cols 80 --rows 24 demo.cast demo.gif
Enter fullscreen mode Exit fullscreen mode

Using asciicast2gif (alternative):

# Install via npm
npm install -g asciicast2gif

# Convert to GIF
asciicast2gif demo.cast demo.gif

# Adjust speed (1.0 = normal, 2.0 = 2x speed)
asciicast2gif -s 1.5 demo.cast demo.gif
Enter fullscreen mode Exit fullscreen mode

Using Docker (no installation needed):

# Pull the image
docker pull asciinema2/asciicast2gif

# Convert your cast
docker run --rm -v $PWD:/data asciinema2/asciicast2gif demo.cast demo.gif
Enter fullscreen mode Exit fullscreen mode

Pro tips for GIF conversion:

  • Keep recordings under 30 seconds for reasonable file sizes
  • Use --idle-time-limit when recording to compress pauses
  • Optimize GIF size with tools like gifsicle: 
  gifsicle -O3 --lossy=80 -o optimized.gif demo.gif
Enter fullscreen mode Exit fullscreen mode
  • Consider using higher contrast themes for better readability in GIFs
  • Test the GIF at the size you'll actually embed it

When to use GIF vs interactive player:

Use Case GIF Interactive Player
GitHub README ✅ Perfect ⚠️ Thumbnail only
Blog posts (dev.to, Medium) ✅ Works everywhere ✅ Better UX
Email newsletters ✅ Only option ❌ Not supported
Internal docs (Confluence, Notion) ✅ Simple ✅ Copy-pastable
Presentations ✅ Reliable ⚠️ Needs internet
Social media ✅ Auto-plays ❌ Not supported

Best Practices for Creating Great Recordings

1. Prepare Your Script

Before recording, write out the commands you'll run. This ensures smooth flow and reduces mistakes.

2. Clean Your Prompt

Use a simple, readable prompt. Consider temporarily setting:

export PS1="$ "
Enter fullscreen mode Exit fullscreen mode

3. Add Context with Comments

Use echo statements to explain what you're doing:

echo "# Installing dependencies..."
npm install

echo "# Running tests..."
npm test
Enter fullscreen mode Exit fullscreen mode

4. Control Pacing

Use sleep commands to give viewers time to read output:

cat important-file.txt
sleep 3  # Give viewers time to read
Enter fullscreen mode Exit fullscreen mode

5. Edit Out Mistakes

Use the --idle-time-limit flag to compress long pauses, or use tools like asciinema-edit to trim sections.

6. Test Before Sharing

Play back your recording before sharing:

asciinema play demo.cast
Enter fullscreen mode Exit fullscreen mode

Integration Ideas

GitHub README

Add recordings to showcase your CLI tool in action:

<!-- Interactive embed (shows as thumbnail, links to asciinema.org) -->
[![asciicast](https://asciinema.org/a/123456.png)](https://asciinema.org/a/123456)

<!-- Or use an animated GIF for inline display -->
![Demo](./demo.gif)
Enter fullscreen mode Exit fullscreen mode

Internal Wiki

Embed recordings in Confluence, Notion, or your internal docs platform for interactive guides.

Runbooks

Include asciinema recordings in incident response runbooks to show expected command output and timing.

CI/CD Documentation

Record the full deployment process, from git push to production verification, showing all intermediate steps.

Asciinema vs. Alternatives

Feature Asciinema Video Recording Screenshots Written Docs
File Size ✅ Tiny ❌ Large ⚠️ Medium ✅ Tiny
Copy-paste ✅ Yes ❌ No ❌ No ⚠️ Manual
Searchable ✅ Yes ❌ No ❌ No ✅ Yes
Shows Timing ✅ Yes ✅ Yes ❌ No ❌ No
Live Streaming ✅ Yes ⚠️ Complex ❌ No ❌ No
Easy to Update ⚠️ Re-record ⚠️ Re-record ✅ Easy ✅ Easy
Works Offline ✅ Yes ✅ Yes ✅ Yes ✅ Yes

Common Pitfalls to Avoid

  1. Recording sensitive data Always review recordings before sharing. Avoid capturing API keys, passwords, or internal URLs.

  2. Too long recordings Keep recordings under 5 minutes when possible. Break complex processes into multiple recordings.

  3. Assuming all viewers have context Add intro text or comments explaining what's happening and why.

  4. Ignoring accessibility Provide written transcripts or summaries alongside recordings for accessibility.

  5. Not testing playback Always verify your recording plays correctly before sharing.

  6. Font rendering issues If you use nerdfonts or Unicode symbols at your terminal, remember to configure font settings on asciinema.org and select a different font there (I recommend use the Nerd Font - Fira Code in this case)

Advanced: Building a Knowledge Base

Consider creating a structured asciinema library:

docs/
├── onboarding/
│   ├── environment-setup.cast
│   └── first-deployment.cast
├── operations/
│   ├── monitoring-setup.cast
│   └── backup-restore.cast
└── troubleshooting/
    ├── database-issues.cast
    └── network-debugging.cast
Enter fullscreen mode Exit fullscreen mode

Create an index page that embeds all recordings with descriptions, making it easy for team members to find relevant tutorials.

Conclusion

Asciinema transforms terminal recordings from disposable demos into valuable, searchable documentation assets. Whether you're training new developers, documenting complex procedures, or handing off project knowledge, asciinema provides a lightweight, user-friendly way to capture and share terminal workflows.

The next time you're tempted to write "run these commands" in your documentation, consider recording an asciinema session instead. Your future self (and your colleagues) will thank you.

Quick Start Checklist

  • [ ] Install asciinema on your system
  • [ ] Record a simple demo: asciinema rec first-demo.cast
  • [ ] Play it back: asciinema play first-demo.cast
  • [ ] Upload to asciinema.org: asciinema upload first-demo.cast
  • [ ] Embed in your documentation or README
  • [ ] Try converting to GIF: agg first-demo.cast first-demo.gif
  • [ ] Create a template for future recordings

Have you used asciinema in your workflow? Share your experiences and tips in the comments below!

Top comments (0)