saumzzz/runme

Execute commands inside your runbooks, docs, and READMEs.

Runme runs Markdown

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.

Installation

The easiest way on MacOS is to use Homebrew:

$ brew update

Install runme:

$ brew install runme

or via NPM:

$ npm install -g 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 github.com/stateful/runme@latest

Commands

The Runme CLI contains several commands that allow you to discover and run workflows within your project.

Run Workflows

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-brew

Read more about how you can configure code cells in the Runme documentation.

List

Explore which workflows are available in your project.

$ runme list

Print

Instead of running the code of a code cell, print just outputs the code that would have been executed.

$ runme print hello-world

Help

Find help and information to parameters and configurations.

$ runme help

Examples

You can find an exhaustive list of examples in the official Runme documentation with examples demonstrating various use cases of Runme.

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.

Community

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

Contributing

See CONTRIBUTING.md for more information or just click on:

LICENCE

Apache License, Version 2.0