Runme comes with multiple client to interface with its kernel; CLI for the terminal, notebook and editor integration in VS Code, and a self-hosted web app version with the same features for the browser. Here's how to intall them:
The Runme CLI is ideal for power users who want to run markdown documentation from the terminal.
The easiest way on MacOS is to use Homebrew:
$ brew update
$ brew install stateful/tap/runme
On Windows, we distribute the binary through Scoop.sh:
$ scoop bucket add stateful https://github.com/stateful/scoop-bucket.git
$ scoop install stateful/runme
Alternatively, check out runme's releases and select a binary for your operating system. Let us know on Discord if you have a different preferred distribution mechanism.
If you have Go developer tools installed, you can install it with go install:
$ go install github.com/stateful/runme@latest
If you don't have go developer tools installed and still want to use this method, download and install go.
Download Binaries directly
You can find a binary for your OS/arch on our releases page. Let us know on Discord if you have a preferred distribution mechanism.
See the doc page on the cli for installation instructions.
Runme has a nice TUI that you can use simply like so:
# short for "runme tui"
This allows you to quickly execute any script present in the README.
Runme won't work if your current working directory doesn't contain a README file at the top level!
You can use the
--chdir flag to alter the working directory or
--filename to specify any other markdown file, without changing the environment's working directory.
Runme parses every shell or bash code block of a markdown file and allows you to execute it within your terminal environment. It comes with several commands that help you to run code blocks in your markdown successfully:
Parses commands directly from a markdown (e.g. README) to make them executable.
branch Suggest a branch name (aka branchGPT)
completion Generate the autocompletion script for the specified shell
fmt Format a Markdown file into canonical format
help Help about any command
list List available commands
login Log in to Runme
logout Log out from Runme
print Print a selected snippet
run Run a selected command
suggest Use our suggestion engine to give contextual advice
tui Run the interactive TUI
--allow-unknown Display snippets without known executor (default true)
--background Enable running background blocks as background processes
By default, Runme will try to open a
Readme.md file in your current work directory but you can modify this by using the
chdir flags, e.g.:
runme ls --filename SUPPORT.md --chdir ./.github
Running Commands Directly
The TUI is nice, but what if you just want to run a specific command quickly?
To run a specific script by name, use the
runme run <command> subcommand.
Runme for VS Code
Extensions Tab in the VS Code sidebar and search for "Runme". The CLI is contained inside the extension.
Alternatively, you can go to the VS Code Marketplace and click the green
That's it. Now, any time you open a Markdown file (
*.mdx) it will open as a Runme notebook.
Bleeding Edge Features
A pre-release version of Runme is offered for curious developers who want to try our latest enhancements to the extension. Head to the extension configuration and click Switch to Pre-release Version to use it. If you don’t see such an option, ensure your VS Code is at least 1.63.0.
Default Markdown Viewer
Install the VS Code Runme extension just like every other VS Code extension, open any
.mdx file in VS Code with commands, then click to run them (and much more). Then go create your own custom runnable markdown files! If you like to use Runme as your default markdown file viewer in VS Code, follow these steps:
- Right-click on any
*.mdxfile in the explorer window (in the directory file list, not under "Open Editors").
- Pick "Open With"
- Pick "configure default editor" at the bottom of the list
- Pick "Run your README.md - Runme"
or set the following in your
.vscode/settings.json file of your project:
You can also switch by just doing a right-click on the file and go to
"Open With ...", e.g.:
Runme for Web
Runme can run as a self-contained web app. Since Runme's notebook UX is built on top of the VS Code platform, we can leverage the code-server binary to run it as a local self-contained web app.
Just run following command to install
$ wget -O- https://aka.ms/install-vscode-server/setup.sh | sh
Followed by launching Runme inside of it:
$ code-server serve-local --install-extension stateful.runme --start-server
Just follow the link in the logs to launch into the web app.
[2023-05-21 12:43:29] info Found existing installation at /Users/sourishkrout/.vscode-cli/server-stable-web/bin/b3e4e68a0bc097f0ae7907b217c1119af9e03435
[2023-05-21 12:43:29] info Starting server...
* Visual Studio Code Server
Server bound to 127.0.0.1:8000 (IPv4)
Extension host agent listening on 8000
[12:43:29] Installing extensions...
Web UI available at http://localhost:8000/?tkn=6e6560a2-75ff-4cda-aad1-1bf68e188c6f
[12:43:29] Extension host agent started.
We are working on providing a single command option to install and run Runme for Web from the CLI.
How It Works
Runme's functionality when run as a web app mirrors VS Code's UX. Go ahead and check out Getting Started for next steps.