🏃‍♂️‍➡️📕 paulrun

What is paulrun?

paulrun runs hand-written markdown runbooks.

A runbook is a normal markdown file that a person can read and follow without paulrun. Mark a code block run, and paulrun runs it for you. Everything else stays documentation.

Example runbook

Save this as hello.md:

---
title: Say hello
inputs:
  - name: NAME
    description: Who to say hello to
---

# Say hello

A runbook is just markdown. paulrun runs the blocks marked `run`, shows the
`docstring` ones, and leaves everything else alone, like this paragraph.

## Greet

```docstring
Saying hello to <NAME>.
```

```sh run
echo "Hello, <NAME>!"
```

## Count the letters

```python run
import os

name = os.environ["NAME"]
print(f"{name} has {len(name)} letters")
```

Check it, then run it:

paulrun check hello.md
paulrun hello.md

hello.md: ok
NAME (Who to say hello to): Paul
Say hello
directory: /home/you/hello
inputs: NAME=Paul
  1. Greet
  2. Count the letters
2 run blocks
Start? [y/N] y

=== Greet ===
Saying hello to Paul.
    echo "Hello, Paul!"
Hello, Paul!
exit 0 (0.0s)

=== Count the letters ===
    import os

    name = os.environ["NAME"]
    print(f"{name} has {len(name)} letters")
Paul has 4 letters
exit 0 (0.1s)

finished: ok (0.1s)

check finds problems before anything runs. Then paulrun asks for the inputs, shows the plan, and runs each step in order, stopping at the first command that fails.

Your runbook library

Keep runbooks you use across projects in ~/runbooks, and run them by name from anywhere:

$ paulrun library
library: /home/you/runbooks
rebuild-frontend     Rebuild the frontend
update-project-deps  Update a project's dependencies

$ cd ~/Projects/website
$ paulrun rebuild-frontend

A book runs in the folder you're in, so one book works for every project. See Your runbook library.

Why use paulrun?

Release steps get forgotten. Writing them down helps; making the written-down version run itself fixes it.

• It's just markdown - A runbook reads like documentation, renders on GitHub, and works fine without paulrun.
• Check before you run - paulrun check finds broken frontmatter, undeclared placeholders and syntax errors.
• See what would happen - paulrun --dry RELEASING.md shows every command with its inputs filled in, and runs nothing.
• Inputs and secrets - Ask for values once, check them against a pattern, and keep secrets off the screen and out of the log.
• Manual steps too - confirm blocks pause for the things only a person can do.
• A record of every run - An optional transcript keeps every command, its output and how it finished.
• More than shell - Shell and Python blocks are built in, and other languages can be added as backends.

Install

paulrun is a command-line tool, so install it on its own rather than into a project:

uv tool install paulrun

Or with pip:

pip install paulrun

paulrun needs Python 3.12 or later and bash, and runs on macOS and Linux. Windows isn't supported. It's for runbooks you run yourself, at a terminal; there's no CI mode.

Getting started

👉 Read the full documentation for the runbook format, every command, and writing your own backend.

See examples/ for more runbooks, including a real release, and PUBLISHING.md for the runbook paulrun releases itself with.

Want to help? See CONTRIBUTING.md.