Skip to main content

Getting started with Runme CLI

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

Runme TUI Usage

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

Warning!

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.

Usage:
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

Flags:
--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/docs.runme.dev")
--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 "README.md")
--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 Readme.md file in your current work directory but you can modify this by using the filename and chdir flags, e.g.:

runme ls --filename README.md --chdir ../..

You can also specify a full path in filename:

runme ls --filename ../../README.md

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.