README.md

Tusk

Tusk is a yaml-based task runner. By creating a tusk.yml in the root of a repository, Tusk becomes a custom command line tool with minimal configuration.

Details on the usage and configuration options can be found in the project documentation.

Features

• Customizable: Specify your own tasks and options with support for command-line flags, environment variables, conditional logic, and more.
• Explorable: All the help you need to get started is available straight from the command line. Help documentation is generated dynamically, and support for Bash and Zsh tab completion is available.
• Accessible: Built for usability with a simple YAML configuration, familiar syntax for passing options, Bash-like variable interpolation, and a colorful terminal output.
• Zero Dependencies: All you need is a single binary file to get started on Linux, macOS, or Windows.

Getting Started

Installation

Go

With Go 1.21+ installed:

go install github.com/rliebz/tusk@latest

Homebrew

On macOS, installation is also available through homebrew:

brew install rliebz/tusk/tusk

With Homebrew, tab completion is installed automatically.

Compiled Releases

The latest version can be downloaded from the releases page.

To install automatically:

curl -sL https://git.io/tusk | bash -s -- -b /usr/local/bin latest

To pin to a specific version, replace latest with the tag for that version.

To install to another directory, change the path passed to -b.

Installing Tab Completion

For bash:

tusk --install-completion bash

For fish:

tusk --install-completion fish

For zsh:

tusk --install-completion zsh

Completions can be uninstalled with the --uninstall-completion flag.

Usage

Create a tusk.yml file in the root of a project repository:

tasks:
  greet:
    usage: Say hello to someone
    options:
      name:
        usage: A person to say "Hello" to
        default: World
    run: echo "Hello, ${name}!"

As long as there is a tusk.yml file in the working or any parent directory, tasks can be run:

$ tusk greet --name friend
Running: echo "Hello, friend!"
Hello, friend!

Help messages are dynamically generated based on the YAML configuration:

$ tusk --help
tusk - the modern task runner

Usage:
   tusk [global options] <task> [task options]

Tasks:
   greet  Say hello to someone

Global Options:
   -f, --file <file>  Set file to use as the config file
   -h, --help         Show help and exit
   ...

Individual tasks have help messages as well:

$ tusk greet --help
tusk greet - Say hello to someone

Usage:
   tusk greet [options]

Options:
   --name <value>  A person to say "Hello" to

Additional information on the configuration spec can be found in the project documentation.

For more detailed examples, check out the project's own tusk.yml file.

Contributing

Set-up instructions for a development environment and contribution guidelines can be found in CONTRIBUTING.md.