Skip to main content

How Runme CLI Works

Install Runme

If you haven't already installed Runme CLI, please complete the steps in installation before proceeding.

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

# short for "runme tui"

Runme TUI Usage

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

Available commands

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 executes commands inside your runbooks, docs, and READMEs. Parses commands
directly from Markdown files to make them executable.

runme [flags]
runme [command]

Available Commands:
branch Suggest a branch name (aka branchGPT)
completion Generate the autocompletion script for the specified shell
extension Check your Stateful VS Code extension status
fmt Format a Markdown file into canonical format
help Help about any command
list List available commands
login Log in to Runme (optional)
logout Log out from Runme
open Launch Runme in a headless web client
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)
--allow-unnamed Allow scripts without explicit names
--background Enable running background blocks as background processes
--chdir string Switch to a different working directory before executing the command (default "~/oss/")
--entries int Number of entries to show in TUI (default 5)
--env-order stringArray List of environment files to load in order. (default [.env.local,.env])
--exit Exit TUI after running a command
--filename string Name of the README file (default "")
--filter string Regular expression to filter results, by filename and task name
--git-ignore Whether to respect .gitignore file(s) in project (default true)
-h, --help Help for runme
--ignore-pattern stringArray Patterns to ignore in project mode (default [node_modules])
--insecure Run command in insecure-mode
--load-env Load env files from local project. Control which files to load with --env-order (default true)
--project string Root project to find runnable tasks
-s, --server string Server address to connect runner to
--tls string Directory for TLS authentication (default "~/Library/Application Support/runme/tls")
-v, --version Version of runme

Run a Markdown file

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

You can also specify a full path in filename:

runme ls --filename ../../

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.