If you've ever tried to explain how a command-line tool works, you know the struggle. A static screenshot is worth a thousand words, but it often fails to capture the interactive, dynamic nature of the terminal. A full-blown video recording or a GIF can do the trick, but they come with their own set of problems: large file sizes, blurry text, and no way for the viewer to pause and inspect the content.
I recently found myself in this very predicament. I was putting the finishing touches on a personal project I've been using for years, a command-line task manager called Perennial Task. It's a simple, file-based tool I built to help me manage recurring responsibilities, those tasks that, like the name suggests, come back recurringly. I wanted to showcase its features in the README file on GitHub, but I felt that a simple block of text wouldn't do it justice. I needed something better.
That's when I had an idea: what if I could record my terminal session and play it back as a lightweight, crisp, and interactive animation? This led me down a rabbit hole, and after a lot of tinkering, I’m excited to introduce my solution: term-to-svg.
What is term-to-svg?
term-to-svg is a command-line tool that records your terminal sessions and converts them into animated Scalable Vector Graphics (SVG) files. Unlike GIFs, which are raster-based and can become pixelated, SVGs are vector-based, which means they look sharp at any resolution, have incredibly small file sizes, and can even be styled and manipulated with CSS and JavaScript.
In short, term-to-svg allows you to create beautiful, high-fidelity animations of your terminal sessions that are perfect for embedding in documentation, blog posts, or anywhere on the web.
Features
I designed term-to-svg to be both powerful and easy to use. Here are some of its key features:
High-Fidelity Playback: It accurately interprets ANSI escape codes for everything from cursor movements and color changes to screen clearing and scroll regions. This means your recorded session will look exactly like it did in your actual terminal.
Two Animation Engines: You can choose between two different animation engines: modern and efficient CSS animations (the default), or the powerful and self-contained SMIL engine.
Highly Configurable: You can customize everything from the terminal dimensions and font size to the color scheme and font family, all through simple command-line flags.
Automatic Geometry Detection: If your script command saves the terminal dimensions in the log file, term-to-svg will automatically detect and use them.
Lightweight and No Dependencies: It's a simple PHP application with no external runtime dependencies, so it's easy to get up and running.
How it Works
The process is simple. First, you record your terminal session using the standard script command with the --timing flag:
script --timing=rec.time rec.log
Then, you perform whatever actions you want to record in the new subshell that appears. When you're done, just type exit.
Finally, you use term-to-svg to convert the two generated files (rec.log and rec.time) into an animated SVG:
And that's it! You now have a beautiful, animated SVG of your terminal session.
Why I Built This
As I mentioned, the initial spark for term-to-svg came from my work on Perennial Task. Perennial Task is a command-line tool for people who want a simple, local-first way to manage their tasks, especially the recurring ones. All tasks are stored as individual XML files that you own and control. It has features like flexible rescheduling, task prioritization, and both interactive and non-interactive modes. I needed a way to show how all of this worked, not just tell. Now, with term-to-svg, I can create demos like this one:
Give it a Try!
I'm really happy with how term-to-svg turned out, and I hope you'll find it as useful as I do. It’s open-source and licensed under the MIT License, so you're free to use and modify it as you see fit. You can find the source code and more detailed installation instructions on the GitHub repository.