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.
To get started with Runme on MacOS, the recommended method of installation is using Homebrew, a popular package manager that simplifies the installation process. First, ensure your Homebrew is up to date to avoid any compatibility issues:
$ brew update
With Homebrew updated, proceed to install Runme. This command will fetch the latest stable release of Runme and install it on your system:
$ brew install runme
If you prefer using NPM (Node Package Manager) for managing your packages, Runme can also be installed globally via the following command:
$ npm install -g runme
For users with different setups, you can visit Runme's releases page and download a binary suitable for your operating system. For those with Go developer tools set up, Runme can be installed using the go install command:
$ go install github.com/stateful/runme@latest
Runme’s CLI (Command Line Interface) offers a set of commands designed to help you seamlessly discover and execute workflows within your project. Below are examples demonstrating the use of these commands:
Suppose you have a README.md file in your project directory with the following content:
# My Project
## Install
To initiate the installation process, start by updating Brew dependencies with the following command:
```sh { name=update-brew }
brew update
...
```
To execute the update-brew code cell from the README.md file, simply use the runme run command followed by the name of the code cell:
$ runme run update-brew
For more details and advanced configurations for code cells, refer to the Runme documentation.
To navigate through and identify available workflows in your project, use the runme list command. This command will display a list of all workflows you can run:
$ runme list
The print command is useful when you need to review the code within a code cell without executing it. It outputs the code present in the specified code cell, providing a quick way to inspect the code:
$ runme print hello-world
Find help and information to parameters and configurations.
If you need assistance or information regarding various parameters and configurations available with Runme, the help command provides quick access to helpful information:
$ runme help
Feel free to explore further and experiment with the commands to get a deeper understanding of Runme’s functionalities!
You 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