Executable Runbooks from Markdown
Enforce process. Track progress. Resume anytime.

Why Rundown?

Rundown transforms static documentation into interactive, stateful CLI runbook flows, bridging the gap between "how-to" and "done."

• Human-Readable: Write standard Markdown.
• Agent-Readable: Write standard Markdown.
• Machine-Executable: Rundown CLI executes and enforces your process.
• Stateful: It remembers where you left off. Close your terminal, reboot your machine, and rundown status picks right back up.
• Agent-Ready: Designed to be the perfect "runtime" for AI agents (like Claude) to execute long-running, complex tasks reliably.

Features

• Markdown-based runbooks - Define multi-step processes in readable .runbook.md files
• State persistence - Runbook progress survives context clears
• XState compilation - Runbooks compile to state machines for reliable execution
• CLI control - Simple commands to run, pass, fail, and navigate runbooks
• Template variables - Parameterize runbooks with {{variable}} syntax

Security

Rundown includes a Deno-inspired security policy layer that provides explicit allowlist-based permission control:

• Default-deny - Commands not in the allowlist require user confirmation
• Granular control - Separate allow/deny lists for commands, file access, and environment variables
• Runbook overrides - Per-runbook policy configurations for different trust levels
• CI-friendly - --yes flag for non-interactive execution with pre-approved commands

Key CLI flags:

• --allow-run <cmds> - Allow specific commands
• --allow-all / --deny-all - Trust or strict mode
• --policy <file> - Custom policy file
• --non-interactive - CI mode (auto-deny)

See Security Documentation for full configuration options.

Get Started

Install

npm install -g @rundown-org/cli

Create Your First Runbook

Create a runbook file deploy.runbook.md.

This example uses rundown echo to simulate commands so you can run it immediately without any setup.

---
name: Deploy to Production
---

## 1. Run Tests
- PASS CONTINUE
- FAIL STOP

```bash
rundown echo npm test
```

## 2. Build Application
- PASS CONTINUE
- FAIL STOP

```bash
rundown echo npm run build
```

## 3. Deploy
- PASS COMPLETE
- FAIL STOP

```bash
rundown echo npm run deploy
```

Run the runbook:

rundown run deploy.runbook.md

To make this real: Simply remove rundown echo from the code blocks to execute the actual npm commands.

Commands

Use rundown for every command. The package also installs a short rd binary pointing at the same CLI, but oh-my-zsh ships a core alias rd=rmdir that shadows it (shell aliases beat PATH), so rd is unreliable — prefer rundown. On oh-my-zsh, restore the short name by adding alias rd=rundown to ~/.zshrc after oh-my-zsh loads.

Command	Description
rundown run [file]	Start a runbook
rundown run [file] --input key=value	Set template variable (repeatable)
rundown run [file] --input-file path	Load variables from YAML file
rundown run [file] --prompted	Show commands without auto-executing
rundown pass	Mark current step as passed (evaluates PASS condition)
rundown fail	Mark current step as failed (evaluates FAIL condition)
rundown goto <n>	Jump to step number
rundown status	Show current state
rundown stop [message]	Abort runbook with optional message
rundown complete [message]	Mark runbook as complete with optional message
rundown stash	Pause enforcement (stash active runbook)
rundown pop	Resume enforcement (restore stashed runbook)
rundown ls	List active runbooks (JSON output by default)
rundown ls --all	List available runbook files
rundown ls --tags <tags>	Filter runbooks by comma-separated tags
rundown check <file>	Validate runbook file
rundown echo	Test helper: echo with configurable result
rundown prune	Remove stale runbook state files
rundown scenario <cmd>	List, show, or run scenarios
rundown scenario-suite <cmd>	List, show, or run scenario suite cases
rundown prompt <content>	Output content in markdown fences
rundown delegate <runbook> --step <id>	Delegate substep to child runbook
rundown claim <token>	Claim a delegation token and launch child
rundown abort <token>	Cancel a delegation token

Packages

Package	Description
@rundown-org/parser	Markdown runbook parser
@rundown-org/core	Runbook state management and XState compilation
@rundown-org/cli	Command-line interface
@rundown-org/mcp	MCP server for AI agent integration
@rundown-org/claude-code-plugin	Claude Code plugin for runbook orchestration

Documentation

See docs/README.md for the full documentation index, organized by audience and task.

Contributing

See CONTRIBUTING.md for instructions on setting up the development environment and running tests.

License

MIT