A Shell Script for Working Step by Manual Step

While I prefer a project’s deployment process to be automated, some systems just aren’t made for automation. For instance, many content management systems are designed to be updated by a live user— someone manually selecting check boxes, filling in text fields, and clicking submit buttons. Often, all that configuration is stored in a complex format in the database, making it risky to update with a script. In the end, a manual process is not only the cheapest, but also the safest way to go.

But even though the process may be manual, remembering it doesn’t have to be.

Before making manual changes to a production system, I like to practice on my development system. I reset my local settings and run through the procedure a couple of times to make sure they really do update what I want. During these practice sessions, I write down each step so I don’t have to work from memory later.

To make it easier to apply these instructions to production, I’ve created a shell script that I call instruct. Pipe in some formatted step-by-step instructions, and it’ll feed them back to you one at a time. You can find it in this Gist.

Each line is shown one at a time. Hit Enter to see the next instruction. Lines surrounded by triple backticks are copied to the system clipboard, and the next line of text has the icon next to it. Blank lines are ignored. To insert a blank line, use a triple dash (---).

I’ve been using this script to make manual deployments more reliable for several years now. Putting text onto the system clipboard allows pasting exact text, which eliminates typos. Hopefully, it’ll help you make your own manual step-by-step processes more reliable, too.