Runme
title: runme radar_quadrant: Tools radar_ring: Assess radar_position: inner created: 2026-05-22 last_updated: 2026-05-22 related: ["ContinuousIntegration", "GitLabForm", "Hammerspoon"]
runme is a CLI tool and VS Code extension that makes Markdown fenced code blocks executable, turning README files and runbooks into interactive, stateful workflows. The documentation IS the runbook — no separate Makefile or task runner required.
runme parses standard Markdown files and executes code within fenced blocks. Named blocks are the key primitive:
## Deploy to Production
```bash { name=deploy-prod }
kubectl apply -f k8s/
```
```bash { name=verify-deploy }
kubectl rollout status deployment/app
```Run a specific block: runme run deploy-prod
List all blocks: runme list
Environment variables set in one block persist to subsequent blocks — execution is stateful, like a notebook rather than a collection of independent scripts.
Shell, Bash, Zsh, Python, Ruby, JavaScript, TypeScript, Lua, PHP, Perl — via shebang syntax for non-shell languages.
The VS Code extension renders a "Run" button inline with each named code block. Output appears in a terminal panel beneath the block. Enables non-CLI users (PMs, support engineers, on-call responders) to execute runbook steps without leaving the editor.
| runme | Makefile | just | |
|---|---|---|---|
| Lives in | README.md | Makefile | justfile |
| Documentation | Same file | Separate | Separate |
| State across steps | Yes (env vars) | No | No |
| Named blocks | Yes | Targets | Recipes |
| Notebook-style | Yes | No | No |
The core advantage: runbooks written as Markdown remain human-readable documentation AND executable code. Steps don't drift apart from prose explanations.
brew install runme
# or
npm install -g runmerunme sits at Tools → Assess inner. Documentation rot — where README instructions fall out of sync with actual commands — is a persistent ops and onboarding problem. runme solves it structurally by making the prose and the executable code the same artifact. CNCF-affiliated, 2,100 stars, 305 releases. Trial gate: a real ops or onboarding runbook migrated to runme with at least one block executed in a real workflow.
