Runbook

Summary

Runbook is a powerful CLI tool that transforms your operational procedures into interactive, executable notebooks. It combines the best of documentation and automation by letting you create dynamic runbooks using Markdown, Deno, or Python.

Think of it as "infrastructure as code" meets "documentation as code" - perfect for DevOps teams who want both flexibility and reliability.

At work, it empowered us to move 300 Mysql Clusters to TiDB with a small team recording over the course of 18 months.

Quick Start

uv tool install git+https://github.com/zph/[email protected]

# Initialize a new runbook project in a repo of your choosing
runbook init

# Create a new runbook
runbook create -l deno runbook-name.ipynb

# Edit the runbook
runbook edit runbook-name.ipynb

# Plan the runbook
runbook plan runbook-name.ipynb --embed file.json --parameters '{"arg": 1, "foo": "baz"}'

# Run the runbook
runbook run runbook-name.ipynb

Background

What is a Runbook?

A runbook is an executable document that combines:

• Clear markdown documentation
• Runnable code blocks
• Parameterized inputs for reusability
• Built-in safety checks

It's ideal for operations like encoding your Disaster Recovery Operations, spinning up a new cluster, or restoring from snapshots.

When Should You Use This?

• ✅ When you need semi-automated tools with audit trails and safety checks
• ✅ When you want rapid iteration on operational procedures with built-in rollback steps
• ✅ When you need something more powerful than shell scripts but don't want to build a full application
• ✅ When you want to make complex operations both safe and repeatable

Runbook Best Practices

1. Structure your runbooks with:
   • Clear purpose and summary
   • Step-by-step descriptions
   • Warning signs and precautions
   • Verification steps
   • Execution steps in logical order
   • Rollback and cleanup steps
2. Keep read-only operations flexible
3. Require explicit confirmation for destructive actions using the confirm flag
4. Include pre-flight checks before any system modifications
5. For critical operations, use pair execution:
   • One person to run the procedure
   • Another to verify and validate safety checks

Workflow

1. Initialize a new folder project with runbook init...
2. Create a new runbook with runbook create -l deno runbook-name.ipynb
3. Edit the runbook with runbook edit runbook-name.ipynb (or using editor of choice) and add your title, description, steps
4. For complex runbooks, offload the coding details into an SDK that you build beside the runbooks that can be reused across multiple runbooks
5. Plan that runbook for a specific run `runbook plan runbook-name.ipynb --embed file.json --parameters '{"arg": 1, "foo": "baz"}'
6. Run the instance of a runbook with either runbook run runbook-name.ipynb or use VSCode to run it code runbooks/runs/runbook-name.ipynb
7. Depending on auditing needs, you can either commit the "runs" folder to your repo or only keep the "binder" folder committed.
   1. In case of strict auditing needs, we recommend you add auditing of commands in the local SDK as well as in your cloud provider

Installation

We recommend using uv for installing runbook as a cli tool. If you already use pipx, you can use that instead.

uv tool install git+https://github.com/zph/runbook.git

Or pin to a version

uv tool install git+https://github.com/zph/[email protected]

CLI

Usage: runbook [OPTIONS] COMMAND [ARGS]...

Options:
  --cwd PATH  Directory for operations (normally at root above runbooks, ie
              ../.runbook.yaml) and can be set with RUNBOOK_WORKING_DIR or
              WORKING_DIR environment variables
  --help      Show this message and exit.

Commands:
  check    Check the language validity and formatting of a runbook.
  convert  Convert a runbook between different formats
  create   Create a new runbook from a template
  diff     Compare two runbooks and show their differences
  edit     Edit an existing runbook
  init     Initialize a folder as a runbook repository
  list     List runbooks
  plan     Prepares the runbook for execution by injecting parameters.
  review   [Unimplemented] Entrypoint for reviewing runbook
  run      Run a runbook
  show     Show runbook parameters and metadata
  version  Display version information about runbook

Shell completion is included via click library and enabled as follows link

# Bash
# Add this to ~/.bashrc:
eval "$(_RUNBOOK_COMPLETE=bash_source runbook)"

# Zsh
# Add this to ~/.zshrc:
eval "$(_RUNBOOK_COMPLETE=zsh_source runbook)"

# Fish
# Add this to ~/.config/fish/completions/foo-bar.fish:
_RUNBOOK_COMPLETE=fish_source runbook | source

For advanced completion setup see docs

Principles

• Prefer deno for better package management and developer ergonomics with typing
  • But allow for other kernels (python) as secondary option, via compatible libraries
• Make runbook batteries included for interfacing with shell commands and common runbook operations

Caveats

1. Running notebook in VScode does not set the timings necessary in notebook for being auditable and exported later
   1. Recommendation: if auditable runs are needed, use jupyter via browser runbook run TITLE
2. Notebooks have different structured ids per cell depending on run environment
   1. Recommendation: if requiring consistency, write your own pre-processor to standardize on an id format
3. Built-in shell package requires a shell environment and is only expected to run on Linux or Mac not Windows.
   1. Recommendation: Windows support is out of scope for now but we'll review PRs

Deno / Typescript

1. Parameter cells must use let declarations to allow for param overriding
   • var or let work in Deno notebooks but only let works if using runbook convert a.ipynb a.ts and running the ts version

Developing runbook cli

For development we use the following tools:

• hermit to manage developement tool dependencies (see .hermit/bin)
• uv python package manager and cli runner (see pyproject.toml)

Necessary deps can be seen in pyproject.toml and .hermit/bin

Use .hermit/bin/activate-hermit to activate the environment.

Readme Changes

README.md is generated from .config/README.md.template and should be updated there.