runme

A shell-script driven task runner.

Install

With cargo

cargo install --force runme

Binaries on macOS, Linux, Windows

Download from Github Releases, unzip and add runme to your $PATH.

GitHub Actions

extractions/setup-crate can be used to install just in a GitHub Actions workflow.

- uses: extractions/setup-crate@v1
  with:
    owner: sigoden
    name: runme

Get Started

First, run runme --runme-create build test to quickly create boilerplate Runmefile.sh

#!/usr/bin/env bash

set -e

# @cmd build project
# @alias b
build() {
    echo Run build
}

# @cmd test project
test() {
    echo Run test
}

eval $(runme --runme-eval "$0" "$@")

To define a new task, simply create the bash function and add the @cmd above it. Task is just function

Then, try running one of your commands!

$ runme build
Run build
$ runme test
Run test

Runme uses argc to parse Runmefile.

Why use runme?

runme provides a cross platform way to define and execute custom commands specific to a codebase.

The less work you have to do when performing repetitive tasks like building, testing, linting, etc, the easier your job becomes. After you've configured it through a Runmefile.sh, a task runner can do most of that mundane work for you—and your team—with basically zero effort.

Cross-platform

runme binary is available in linux, macos, and windows.

runme depends on bash which already built into linux/macos. In windows, runme automatically locates and uses bash that comes with git by default.

Gnu tools like ls, rm, grep, sed, awk... also provided with bash, so you can uses them freely and confidently in the Runmefile.

Tasks listing

Tasks can be listed with runme --help or runme -h.

$ runme --help
USAGE: Runmefile.sh <COMMAND>

COMMANDS:
  build  build project [aliases: b]
  test   test project

runme <task> --help or runme <task> -h will print a help text containing the description of task's flags, options and positional arguments.

Task parameters

Parameters can be accessed using shell variables

# @cmd
run() {
  echo $2 $1 $#
}

$ runme run foo bar
bar foo 2

A more powerful way to define parameters is to use comment tags: @arg, @option and @flag.

# @cmd Download a file
# @alias    d
# @flag     -f --force              Override existing file
# @option   -t --tries <NUM>        Set number of retries to NUM
# @arg      source!                 Url to download from
# @arg      target                  Save file to
download() {
    echo "cmd:                      download"
    echo "flag:   --force           $argc_force"
    echo "option: --tries           $argc_tries"
    echo "arg:    source            $argc_source"
    echo "arg:    target            $argc_target"
}

Download a file

USAGE: Runmefile.sh download [OPTIONS] <SOURCE> [TARGET]

ARGS:
  <SOURCE>  Url to download from
  [TARGET]  Save file to

OPTIONS:
  -f, --force        Override existing file
  -t, --tries <NUM>  Set number of retries to NUM
  -h, --help         Print help information

$ runme download  -f --tries 3 from.txt to.txt
cmd:                      download
flag:   --force           1
option: --tries           3
arg:    source            from.txt
arg:    target            to.txt

Task aliases

# @cmd
# @alias t,tst
test() {
  echo "Test..."
}

$ runme t
Test...

Task dependencies

Dependencies are established by function calling.

# @cmd
bar() { foo;
  echo bar
baz; }

# @cmd
foo() {
  echo foo
}

# @cmd
baz() { 
  echo baz
}

$ runme bar
foo
bar
baz

Task group

Tasks can be semantically grouped with _, -, @, ., :.

# @cmd
test@unit() {}
# @cmd
test@bin() {}

# @cmd
app.build() {}
# @cmd
app.test() {}

Default task

When runme is invoked without a task name, it runs the main function. If the main function does not exist, runme will print help information.

main() { 
  foo
}

# @cmd
foo() {
  echo foo
}

$ runme
foo

Advanced Topics

Completions

Shell completion scripts are available for bash/zsh/powershell.

Customize shell path

You can use environment variable RUNME_SHELL to customize shell path.

RUNME_SHELL="C:\\Program Files\\Git\\bin\\bash.exe"

Customize script name

By default, runme searches for runme script file of the following:

• Runmefile.sh or Runmefile
• runmefile.sh or runmefile
• RUNMEFILE.sh or RUNMEFILE

You can use environment variable RUNME_SCRIPT to custom script name.

RUNME_SCRIPT=taskfile.sh

License

Copyright (c) 2022 runme-developers.

runme is made available under the terms of either the MIT License or the Apache License 2.0, at your option.

See the LICENSE-APACHE and LICENSE-MIT files for license details.