rundown

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 9 Open GitHub ↗

Rundown is a tool for defining executable workflows using markdown.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<img src="logo.png" alt="Rundown Logo" width="400">


 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](docs/reference/security.md) for full configuration
options.

## Get Started

### Install

```bash
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.

````markdown
---
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:

```bash
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](packages/parser)                         | Markdown runbook parser                         |
| [@rundown-org/core](packages/core)                             | Runbook state management and XState compilation |
| [@rundown-org/cli](packages/cli)                               | Command-line interface                          |
| [@rundown-org/mcp](packages/mcp)                               | MCP server for AI agent integration             |
| [@rundown-org/claude-code-plugin](packages/claude-code-plugin) | Claude Code plugin for runbook orchestration    |

## Documentation

See **[docs/README.md](docs/README.md)** for the full documentation index,
organized by audience and task.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on setting up the
development environment and running tests.

## License

MIT

rundown

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README