Change log

paulrun is now rundot. The project was renamed from paulrun to rundot. Nothing else changed: subcommands, flags and the runbook format all work as before. To move over:

Install rundot instead of paulrun, and run rundot instead of paulrun.

Imports start with rundot instead of paulrun, and backends register in the rundot.backends entry point group, which was paulrun.backends.

PAULRUN_LIBRARY is now RUNDOT_LIBRARY, and blocks get RUNDOT_RUNBOOK_DIR instead of PAULRUN_RUNBOOK_DIR.

The docs are at docs.rundot.dev and the code at github.com/phalt/rundot.

Entries below this note use the old name, as they were written at the time.

0.6.0

paulrun run's output is easier to scan:
- the overview and how the run finished are in boxes
- each step is a numbered blue rule, e.g. 1/3 Build
- each block is a bracket: ┌ with its language and when it started (HH:MM:SS.mmm), each line it printed after │, then └ ✓ exit 0 · 0.4s or └ ✗ exit 3 · 0.4s
- docstrings are dim, and confirms are in a yellow box
A line a block writes to stderr has a red │.
Code is hidden unless you pass --show-code. --dry always shows it.
The transcript is unchanged.
Backends: output takes an optional stderr=True for a stderr line, and stream() passes it when output accepts it. A backend that calls output(line) still works.

0.5.0

A block's output is fenced off between === LOG: <when it started> === and ========, with the time to the microsecond and a blank line either side, so it can't be mistaken for the block's code or paulrun's own lines. A block that prints nothing gets no LOG section. Under --step, a blank line comes before and after Run this block? too. The transcript is unchanged.

0.4.0

Add a cool logo to the cli output

0.3.0

A runbook can set step: true in its frontmatter to always run as if --step was given, asking before each run block. --no-step runs it straight through. check reports a step that isn't true or false.
The book picker, paulrun run with no runbook, now takes q to quit, and says so: Run which? (q to quit).
A block skipped under --step is now shown, and recorded in the transcript, as skipped rather than skipped (--step), since step: true skips blocks too.

0.2.0

A runbook library

keep runbooks you use across projects in ~/runbooks, or wherever PAULRUN_LIBRARY says. Then run one by name from anywhere, e.g. paulrun rebuild-frontend. run, check and inputs all take a book's name as well as a path, and a file where you are is always used before a book with the same name. paulrun library lists the books in your library, with each one's title and description. paulrun run, with no runbook, lists them by number and runs the one you pick.
A new docs page, Your runbook library, with a worked example of a book that rebuilds a frontend under nvm.
Breaking: paulrun go is now paulrun run, and you don't need to type it: paulrun RELEASING.md runs RELEASING.md. Anything after paulrun that isn't a command is a runbook to run, so paulrun go is no longer a command. paulrun on its own still shows help.
Breaking: blocks now run in the folder you run paulrun from, not the folder the runbook is in. A relative output_path is now relative to that folder too. A runbook kept at the root of its project, run from there, works as before. One run as paulrun path/to/RUNBOOK.md from another folder now works on that other folder and writes its transcript there. This includes blocks run by external backends, whose cwd is now the folder paulrun was started from.
Blocks get PAULRUN_RUNBOOK_DIR, the folder the runbook is in, so a runbook can still use files kept next to it.
Running a runbook shows the folder blocks will run in, as directory: straight after the title, so you can check it before answering Start?. --dry shows it too.
paulrun library, the book picker and paulrun inputs are in colour in a terminal: names you type are bold cyan, details are dim, and secrets and problems stand out. Piped output has no colour, as before.
Inputs can have a default, shown at the prompt and used when you press enter. The environment still comes first. check reports a default that isn't text, doesn't match the input's pattern, or is on a secret.
Inputs can have choices: the only values accepted, listed at the prompt. You type the choice itself, and a value from the environment has to be one of them too. check reports choices that aren't a list of text, a choice the pattern refuses, a default that isn't a choice, and choices on a secret.

0.1.0

Initial release. paulrun runs hand-written markdown runbooks.

paulrun go runs a runbook's steps in order, streaming each block's output as it's printed and stopping at the first block that fails.
run blocks for shell (sh, bash, shell) and Python (python, py), with the python frontmatter key to choose the interpreter.
docstring blocks to show notes as the runbook runs, and confirm blocks to pause for steps done by hand.
input blocks to ask for a value part way through a run, once it exists: a pull request number from a step done by hand, or a one-time code that expires in seconds.
Inputs, collected from the environment or by asking, with an optional pattern to check them against. Plain inputs fill in <NAME> placeholders; secrets are hidden as you type them and replaced with **** everywhere paulrun shows or records them.
paulrun go --dry to see every block with its inputs filled in, without running anything.
paulrun go --step to run, skip or quit at each block.
Transcripts: with output_path set, every run is added to a plain record of what ran, what it printed and how it finished.
Ctrl-C stops a run cleanly, letting a running block stop and recording how far the run got.
paulrun check to find problems before running anything: missing or malformed frontmatter, undeclared placeholders, secrets used as placeholders, blocks outside a step, and shell and Python syntax errors, with shellcheck warnings when it's installed.
paulrun inputs to list the inputs a runbook needs, and paulrun backends to list the languages paulrun can run.
Backends for other languages can be added by any package, through the paulrun.backends entry point group.