How to Convert Terminal Recordings into GIFs with asciicast2gif and Its Successor agg
Visual content is often easier to share and digest than plain text, especially in technical settings. For DevOps engineers, system administrators, or developers showcasing terminal-based workflows, GIFs are an excellent format. The asciicast2gif tool (originally built for converting asciinema terminal recordings into GIFs) became popular for this purpose. While this project has been archived, its successor, agg, offers more robust features and is actively maintained.
In this post, we’ll cover how to use both tools effectively and highlight why you should consider migrating to agg.
Why Convert Terminal Recordings to GIFs?
Sharing terminal-based commands or troubleshooting workflows can be tedious through screenshots or text descriptions. Here’s why GIFs are a great alternative:
- Engagement: Animated tutorials are more interactive and capture attention.
- Simplicity: GIFs allow users to follow along without needing to run commands themselves.
- Portability: Embed GIFs in documentation, emails, or social media for easy sharing.
- Demonstrations: Perfect for teaching, presentations, or sharing technical demos.
With tools like asciicast2gif, this process becomes simple and efficient.
What is asciicast2gif?
asciicast2gif is a tool designed to convert terminal recordings (captured using asciinema) into GIFs. Asciinema records terminal sessions as lightweight, shareable “asciicast” files. However, asciicast files need compatible players, which makes sharing them outside of development environments tricky. Converting them to GIFs allows you to share them across any platform easily.
Why is the Project Archived, and What’s Next?
asciicast2gif is no longer actively maintained. Its GitHub repository states that the project has been archived, and its developer recommends using the newer agg for better performance and modern support. If you’ve been using asciicast2gif, migrating to agg will offer you:
- Faster conversion times
- Higher-quality GIFs
- Active maintenance and support
Let’s explore how to use both tools, starting with a brief introduction to the legacy option and then moving on to agg.
Setting Up asciicast2gif
Although it’s archived, some users may still prefer asciicast2gif if they are working with older workflows. To set it up, follow these steps:
1. Install Dependencies
Make sure you have the following installed:
- asciinema (for recording terminal sessions)
- Docker or native dependencies like
ImageMagick(if running locally)
sudo apt-get install imagemagick gifsicle
Alternatively, run the tool via Docker:
docker pull asciinema/asciicast2gif
2. Record Your Terminal Session
Use asciinema to record a session:
asciinema rec demo.cast
Perform the actions you want to showcase, then type exit to stop recording.
3. Convert the Recording to GIF
To convert the .cast file to a GIF, run:
docker run --rm -v $PWD:/data asciinema/asciicast2gif demo.cast demo.gif
The output demo.gif will be saved in the same directory.
Limitations of asciicast2gif: Since the tool is archived, it may not support modern terminal features or optimized GIF output, which is why switching to agg is recommended.
Migrating to agg: The Improved Successor
Why agg Is Better
- Faster rendering speeds
- Reduced CPU usage during conversion
- More configuration options for styling GIFs (e.g., resolution and font size)
agg is fully compatible with asciinema recordings, making the transition smooth.
1. Install agg
To install agg, use the following steps based on your platform:
cargo install agg
This requires the Rust package manager, cargo. If you don’t have it installed:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
2. Convert an Asciinema Recording to GIF
Once installed, convert any asciinema .cast file with:
agg demo.cast -o demo.gif
3. Customize the Output
agg offers several options to customize GIFs, including setting the resolution, colors, and playback speed. Here are a few common flags:
agg demo.cast -o demo.gif --cols 80 --rows 24 --fps 15
--colsand--rows: Set the width and height of the terminal window--fps: Adjust frames per second for smoother animation
Optimizing GIFs for Sharing
After generating the GIF, you may want to compress or optimize it using gifsicle:
gifsicle -O3 demo.gif -o optimized-demo.gif
This ensures smaller file sizes without sacrificing too much quality, making it easier to share across platforms.
Common Use Cases
- Documentation: Embed GIFs in technical guides to help users visualize commands.
- Training: Create interactive training material for DevOps teams or students.
- Social Media: Share cool terminal hacks or workflows on platforms like Twitter.
Conclusion
Converting terminal recordings into GIFs is an effective way to communicate technical workflows. While asciicast2gif was once a popular choice, its successor agg is now the preferred tool for this task. By switching to agg, you can enjoy faster conversions, better output quality, and active support.
Ready to take your DevOps monitoring to the next level? Automate incident response and reduce downtime with Akmatori, an AIOps platform designed for stress-free on-call management.
And for affordable virtual machines and reliable bare metal servers worldwide, check out Gcore.
Thanks for reading—start turning your terminal sessions into shareable animations today!