Markdown that runs.
rundot runs the code blocks in a markdown file, one step at a time. Write a release checklist, a deploy or a setup guide once, and run it the same way every time.
uv tool install rundot
Python 3.12+ · macOS & Linux · other ways to install
---
title: Say hello
inputs:
- name: NAME
description: Who to say hello to
---
# Say hello
Prose is left alone. Blocks marked
run are run, in order.
## 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")
```
What people use it for
- Release checklistsTag, build, publish, announce. In order, every time.
- Incident runbooksThe steps you need at 3am, already checked.
- Dev setupOne setup guide that works the same on every machine.
- OnboardingGuides new contributors can run, not just read.
- DeploysAsk before anything destructive happens.
- Database migrationsBackups and safety checks built into the steps.
- Agent proceduresFixed steps for your LLM to follow.
- Rare choresThe job you do twice a year and always forget.
01 · Check
Know it works before it runs.
rundot check catches broken frontmatter, undeclared placeholders and shell or Python syntax errors, with line numbers. --dry prints every command with its inputs filled in, and runs nothing.
- Shell syntax errors & shellcheck warnings
- Typos in frontmatter keys
- Inputs used but never declared
02 · Confirm
Pause for the bits only a person can do.
A confirm block stops the run until someone answers y. Inputs can be checked against a pattern or a list of choices. Secrets are hidden as you type them and shown as **** in the output and the transcript.
```confirm
Publish the GitHub release notes
for v<VERSION>.
```
03 · Library
Your runbooks, everywhere.
Drop books in ~/runbooks and run them by name from any project. A book runs in the folder you're in, so the same one works in every project.
$ cd ~/Projects/website
$ rundot rebuild-frontend
04 · Agents
Agents improvise. Runbooks don't.
A runbook gives an agent a fixed set of steps to follow instead of working them out each time. Paste this prompt into your chat, or into your CLAUDE.md or AGENTS.md. It teaches the format and asks the agent to check and dry-run every runbook before running it.
Loading… open prompt.txtAlso in rundot
Renders on GitHub
A runbook is ordinary markdown, so it reads fine without rundot installed. Docs →
Transcripts
Set output_path to keep every command, its output and how the run ended. Docs →
Step through it
--step asks before each block. --show-code shows each block's code. Docs →
More than shell
Shell and Python are built in. Other languages can be added as backends. Docs →
Try it on your next release.
uv tool install rundot