Documentation › Following a runbook

Following a runbook

This page is for the operator: the person who has been given an interactive runbook and has to run it. You need a browser and a PowerShell, Bash or MySQL session, whichever the runbook is written for. Nothing is installed, and the runbook never runs a command itself; you paste each one into your own session.

Opening it

An interactive runbook is one .html file. Open it in a current browser (Chrome and Edge 102 or later, Firefox 112 or later; Safari 16.4 should work but is not tested), from wherever it was saved: a folder, a file share, a USB stick, an email attachment you saved. No internet connection is needed.

If you were sent its hash separately, check the file before you start (Publishing with a hash). A different hash means the file was changed on the way: get a fresh copy.

Across the top is the runbook's title, who prepared it, its version, and the systems it was written for. Read that line first: if the version is old or the system does not match yours, ask the author before going on.

The left column lists every step. Steps marked Done show a check mark, and the bar under the title shows how many are done. Click a step to jump to it.

Steps, in order

Each step is a card: its number, its title, the author's notes, and the code to paste. Steps unlock in order. The first step is ready; every other step is grayed out and dashed until the step before it is marked Done, and its Copy button and Done check box do nothing until then. A section heading is grayed out the same way until its first step is reachable.

When you have run a step and seen what the notes say you should see, check Done. The next step wakes up. Any Done mark can be undone: uncheck a step and it goes back to being the current one.

Read the notes before the code. They say what to expect, and where the author wants you to stop: "Stop here if…" means stop, and do what the note says, usually tell the runbook owner. Do not check Done past a stop point to see what happens.

A step with no code says "Nothing to paste for this step." It is something to do by hand, such as writing a number down.

Copying the code

Copy puts the whole code block on the clipboard, exactly as the author wrote it, with the line endings your shell expects. The label on the block says what the code is written in and where to paste it: a PowerShell, pwsh, Bash, sh or zsh session, or a MySQL client. Paste it, press Enter, and read the output against the notes.

A long block shows its first ten lines with a faded edge. Show all expands it, Pop out opens it full-screen with its own Copy button. Copy always copies the whole block, whether or not it is expanded.

If the button says "Copy failed", the browser would not give the page the clipboard. Select the code with the mouse and copy it the usual way.

Settings

Many runbooks start with a Settings step: the values that change from one run to the next, such as a server name, a folder or a limit. Each one is a field on that card. Type your values there, not into the code. As you type, the Settings code under the fields rewrites itself, quoted and escaped for the shell, so what you paste is always valid.

A number field accepts only a number; if you type something else, the field is marked and the code keeps the last good value. A yes/no setting is a check box.

Later steps may load a setting again, for use in a new terminal window or database session. Those lines also follow the fields, so they always paste your current value.

When you mark the Settings step Done, the fields lock, so a value cannot change halfway through a run. Uncheck Done to change one. Reset to the runbook values puts the author's starting values back.

Never type a password or other secret into a setting. The values are kept in plain text by the browser and in any progress file you save. A well-written runbook asks for credentials in the shell when it needs them.

Keeping your place

The browser remembers your Done marks and your settings for this runbook, so closing the tab and opening the file again later picks up where you were. That memory belongs to this browser on this computer, and to this runbook's exact text: a runbook built again from changed text, however small the change, starts fresh.

To carry your place somewhere else, or to keep a record, use the buttons in the left column:

• Save progress… writes a small file, named after the runbook with .progress.json on the end, holding every Done mark with the time it was made, and your settings. A note under the button shows when it was last saved and whether anything has changed since.
• Load progress… reads one back. It only loads into the same runbook text: a file saved from a different runbook, or from this one before its text changed, is refused. A file saved from a runbook built with an older Builder loads, as long as the text is unchanged. If the file name differs (browsers rename copies), it asks first. Loading replaces the Done marks and settings in the browser.
• Clear progress… unchecks every step. It asks whether to keep the settings you typed or reset those too.

The progress file is also the record of the run. Attach it to the ticket. Progress files describes what is in it.

Printing, dark mode, phones

Print prints every step in full, with nothing grayed out and no buttons, for a change record or for working from paper.

The runbook follows your system's light or dark setting. On a phone, the step list sits above the steps instead of beside them.

What stays on your machine

Everything. The runbook makes no network requests; its own settings forbid them, and the browser enforces that. Your Done marks, your settings and your progress files exist only where you save them. The About button shows the version of the Builder that made the file and the terms it comes under.

If a runbook opens with "This runbook cannot be shown", its text has a problem the Builder would have caught, which usually means it was edited after it was built. Send it back to whoever gave it to you.