Skip to main content

CLI in the Terminal

Feeling like Runme is great, but you want something even more powerful? Well, lucky for you, there is a Runme CLI!

Runme can be run not only as a VS Code extension but also as a CLI tool to run certain code snippets within your

Also, you can parse markdown files and easily run their commands right from the terminal, with no VS Code required.

Runme CLI run commands from terminal

The Runme CLI is ideal for power users who want to get the absolute most out of Runme.


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

If you don't have go developer tools installed and still want to use this method, download and install go.

All other platforms

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.

Basic Usage

Runme has a nice TUI that you can use simply like so:

Runme TUI Usage


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 this behavior, without changing the environment's working directory.

This allows you to quickly execute any script present in the README.

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:

    runme --help
Parses commands directly from a README (best-effort) to make them executable under a unique name.

runme [command]

Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
list List available commands.
print Print a selected snippet.
run Run a selected command.

--chdir string Switch to a different working directory before executing the command. (default ".")
--filename string A name of the README file. (default "")
-h, --help help for runme
-v, --version version for runme

By default, Runme will try to open a file in your current work directory but you can modify this by using the filename and chdir flags, e.g.:

runme ls --filename --chdir ./.github

Running Script 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!