Github stars icon


Github forks icon


Github watchers icon


Last commit: 2 days ago

Open issues: 20

License: Apache-2.0

Last update: about 14 hours ago

runme Overview

Setting up an existing codebase often starts with going through a README and copying/pasting the setup commands. Stateful’s runme aims to make this a little easier. This small tool allows you to run commands straight from markdown files. Currently, in alpha, it allows you to explore and run commands that are defined in code blocks.

runme latest README


Discover and run code snippets directly from your or other markdowns (defaults to local

runme makes a best effort approach to extracts all code snippets defined in code blocks and allowing to explore and execute them. runme is currently in early alpha.

You can execute commands from a different directory using a --chdir flag. To select a different file than, use --filename.


The easiest way on MacOS is to use Homebrew:

$ brew update

Install runme

$ brew install stateful/tap/runme

Alternatively, check out runme's releases and select a binary for your operating system.

If you have Go developer tools installed, you can install it with go install:

$ go install



$ runme help


$ runme list


$ runme print hello-world

Run selected command, Example: Update brew

$ runme run update-brew

Example Command

echo "hello world"

Contributing & Feedback

Let us know what you think via GitHub issues or submit a PR. Join the conversation on Discord. We're looking forward to hear from you.


Apache License, Version 2.0