Discover and run code snippets directly from your markdown files, e.g. runbooks, docs, or READMEs (defaults to local
README.md).
Runme is a tool that makes runbooks actually runnable, making it easier to follow step-by-step instructions. Users can execute instructions, check intermediate results, and ensure the desired outputs are achieved. Authors can create predefined golden paths and share them with others. Runme combines the guardrails of a pipeline with the flexibility of scripting, where users can check intermediary results before moving on.
Runme achieves this by literally running markdown (ubiquitous for docs inside repos). More specifically, Runme runs your commands inside your fenced code blocks (shell, bash, zsh). It's 100% compatible with your programming language's task definitions (Makefile, Gradle, Grunt, NPM scripts, Pipfile or Deno tasks, etc.). Runme persists your runbooks in markdown, which your docs are likely already using.
The easiest way on MacOS is to use Homebrew:
$ brew updateInstall runme:
$ brew install runmeor via NPM:
$ npm install -g runmeAlternatively, 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 github.com/stateful/runme@latestThe Runme CLI contains several commands that allow you to discover and run workflows within your project.
Given the following README.md file:
# My Project
## Install
First update Brew dependencies:
```sh { name=update-brew }
brew update
```
...You can run this code cell by just calling
$ runme run update-brewRead more about how you can configure code cells in the Runme documentation.
Explore which workflows are available in your project.
$ runme listInstead of running the code of a code cell, print just outputs the code that would have been executed.
$ runme print hello-worldFind help and information to parameters and configurations.
$ runme helpYou can find an exhaustive list of examples in the official Runme documentation with examples demonstrating various use cases of Runme.
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.
The Runme community is growing, join us!
- Ask questions and be curious with us on Discord
- Read about real live Runme examples and use cases in our blog
- Meet the developers, learn about the roadmap and recent developments in our Community Meetings
- Subscribe for updates to our newsletter
See CONTRIBUTING.md for more information or just click on:
Apache License, Version 2.0