Runbooks

A runbook is an ordered list of commands that PocketCmd runs one after another on a server. Use it for deployments, maintenance routines and incident checklists. Runbooks are in the Runbooks tab of the Command Library, next to your snippets, and are part of Free.

Create a runbook

1. In the Runbooks tab, tap New Runbook.
2. Enter a name and, optionally, a description, tags and a folder.
3. Add steps with Add step, or pick a snippet from the library as the next step with Library. A snippet’s {{placeholders}} become the runbook’s variables. Drag a step’s handle to reorder it.
4. Enter a Summary command. It is required and is shown in lists as the runbook’s command.
5. Tap Save.

Each step has these fields:

Field	Purpose
Step name	Shown in the runner, for example “Run migrations”
Command	The shell command for this step
Description	Optional note on what the step does
Expected output	Optional text the step’s output should contain
Pause after	Wait for you before the next step starts
Continue on error	Go on to the next step even if this one exits with a non-zero status

A step you are not editing folds into a card with its name and command; a step with an expected output carries a Checks output badge. Tap a card to edit it. A snippet can also become a runbook with Convert to runbook in the editor’s menu.

Variables

Steps use the same {{name}} placeholders as snippets, with the same shell escaping. The editor collects the placeholders from every step into one Variables list, and the runner asks for all of them before the first step starts.

docker pull {{registry}}/{{image}}:{{tag}}
sudo systemctl restart {{service}}

Run a runbook

Tap the runbook, fill in its variables, pick the server under Run on server, and tap Run. The runner connects over SSH and runs the steps in order, showing each step’s command, output and status: PENDING, RUNNING, SUCCESS, FAILED or TIMED OUT.

All steps run in the same shell, so a cd or an exported variable in one step still applies in the next.

Step result	What happens next
Exit status 0	The next step starts, or the runner waits if the step has Pause after
Non-zero exit status	The run stops, unless the step has Continue on error
No output for 5 minutes	The command is interrupted with Ctrl-C and the step is marked TIMED OUT
Expected output set	The step shows Output verified or Verification failed. A failed check is reported but does not stop the run.

The expected output is matched as plain text anywhere in the step’s output. To stop a runbook when a check fails, make the command itself fail, for example with grep -q:

curl -s http://localhost:3000/health | grep -q '"status":"ok"'

When a step has Pause after, the runner waits after it with Continue to next step, so you can read the output first. The last step never pauses.

Stop ends the run at any time. The current command is interrupted by closing the shell, and no further steps start. The summary shows how many steps passed.

The runner has the same rules as for snippets: it needs a POSIX shell on the server, turns off shell history and masks secret variables. See Run a snippet on a server.

No automatic rollback

Steps that completed before a failure or a stop are not undone. Put irreversible steps last, and use Pause after on the step before them.

Example: deploy a web application

Step	Command	Pause after	Continue on error
Pull latest code	cd /var/www/app && git pull origin main	No	No
Install dependencies	npm ci --omit=dev	No	No
Run migrations	npm run migrate	Yes	No
Restart service	sudo systemctl restart app	No	No
Health check	curl -sf http://localhost:3000/health	No	No

The first step’s cd carries over to every later step because they share one shell.