Record your terminal with script and scriptreplay

A fascinating thing about humans is that we each have a particular learning style. Some people prefer to read about how something's done. Some people prefer to follow instructions from the start, while others prefer to get an overview before engaging. Other people like to listen to instructions from an instructor or a podcast. And yet another group wants instructions in the form of a video.

The trouble with video is that it can be difficult to produce and compress, and it is a lot of work to change once it's done. And besides that, viewers can't copy and paste Linux commands out of a video into their terminal.

Or can they?

The script and scriptreplay commands allow you to record a terminal session and then play it back later. There's no video involved. Instead, plain text files called typescripts are used, so the files are small and users can copy commands during playback.

Both script and scriptreplay commands are valuable documentation tools, and I find them useful in two scenarios:

1. No matter how sincerely I promise myself that I'll go through my shell history and gather the proper commands once I figure out the right way to accomplish a task, I rarely do.
2. Sometimes, my users don't want to see the input required of them; they want to see the interaction between them and the computer. You can tell a user to type ls and describe what they can expect to see in response, but it makes a greater impact when they see it happening themselves. I find users a lot braver in the terminal after playing a script file to see what it's like first.

[ Register for Ansible Basics: Automation Technical Overview and learn configuration management, provisioning, deploying, and managing compute infrastructure across environments with Ansible. ]

Record your terminal

To start recording with script, provide two destination files: a timing file and a typescript file:

$ script --timing=time.tm myscript

Output alerts you that script has started recording. Everything you do in your terminal while script is active is recorded. This includes everything going to stdin, stdout, and stderr, including your pauses, backspaces, auto-completions, and even your mistakes.

Press Ctrl+D or type exit to stop the recording when you've finished your demonstration.

The resulting typescript file, myscript in this example, is straightforward and relatively self-documenting:

Script started on 2022-01-06 22:27:01+13:00
0;seth:~/script^G$ echo "hello world"
hello world
0;seth:~/script^G$ exit
exit

Script done on 2022-01-06 22:27:10+13:00

You can edit this file. but beware of making too many changes because the output's timing has also been recorded.

Still, to correct minor errors, a quick edit with a text editor is an easy fix.

Playing a script

You can play a recorded script using the scriptreplay command:

$ scriptreplay --timing=time.tm myscript

This takes over your terminal session and uses it as a canvas to replay the input and output of what you recorded. The timing is replicated, too, so meaningful pauses for clarity are retained, which can be helpful to a user following along with the script playback.

Of course, the commands playing back in the terminal aren't being executed. It's just an instant replay, so it's safe to play scripts that delete files, make Git commits, or launch Ansible plays. Nothing in the playback of a script actually happens. It's just a movie.

Documentation in action

The script and scriptreplay commands are valuable tools for the "show don't tell" philosophy. Whether your target audience is you at some point in the future, long after you've forgotten what you were sure you'd never forget, or a timid new terminal user, seeing human-computer interaction can be illuminating and empowering.

Unlike screen captures, typescripts are small in file size and easy to update and edit. Unlike your shell history, typescripts aren't rotating. They don't go away unless you remove them yourself. And unlike shell scripts, a typescript demonstrates the steps without performing the process, encouraging the viewer to try each step, internalize it and commit it to memory, and gain a better understanding of what the terminal is truly capable of doing.