sub

KO | EN

gitlite — search

#javascript #typescript #golang #deep-learning #linux #docker #macos #java #windows #awesome-list #pytorch #security #mcp #open-source

(★ 24)

Shell scripts with superpowers 🦸‍♂️

sub Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Sub

![GitHub top language](https://img.shields.io/github/languages/top/juanibiapina/sub)
![GitHub branch check runs](https://img.shields.io/github/check-runs/juanibiapina/sub/master)
![GitHub Release](https://img.shields.io/github/v/release/juanibiapina/sub)
![GitHub License](https://img.shields.io/github/license/juanibiapina/sub)

Scripts with superpowers.

`sub` is a tool for organizing scripts into a unified command-line interface.
It allows the dynamic creation of a CLI from a directory (and subdirectories)
of scripts with support for documentation, argument validation, and
completions.

## Table of Contents

* [Key features](#key-features)
* [Demo](#demo)
* [Installation](#installation)
* [Setup](#setup)
  * [Examples](#examples)
  * [As an alias](#as-an-alias)
  * [As an executable](#as-an-executable)
* [Usage](#usage)
* [Documenting commands](#documenting-commands)
* [Validating arguments](#validating-arguments)
* [Parsing arguments](#parsing-arguments)
* [Raw arguments](#raw-arguments)
* [Completions](#completions)
* [Nested subcommands](#nested-subcommands)
* [Aliases](#aliases)
* [Sharing code between scripts](#sharing-code-between-scripts)
* [Caching](#caching)
* [Migrating to Sub 2.x](#migrating-to-sub-2x)
  * [change --bin to --executable](#change---bin-to---executable)
  * [Usage comments](#usage-comments)
  * [Help, commands and completions](#help-commands-and-completions)
* [Inspiration](#inspiration)

## Key features

- **Display help:** Display usage and documentation for scripts.
- **Validate arguments:** Validate arguments to scripts based on documentation.
- **Parse arguments:** Automatically parse arguments to scripts so `getopts` is not needed.
- **Nested subcommands:** Supports nested directories for hierarchical command structures.
- **Aliases:** Supports aliases for subcommands.
- **Completions:** Supports auto completion of subcommands.
- **Cross-platform:** Works on Linux and macOS.

## Demo

[![asciicast](https://asciinema.org/a/664235.svg)](https://asciinema.org/a/664235)

## Installation

<details>
<summary>Homebrew</summary>

```sh
brew install juanibiapina/tap/sub
```
</details>

<details>
<summary>Nix with Flakes (install the `sub` binary)</summary>

Add sub to your flake inputs:

```nix
{
  inputs = {
    sub = {
      url = "github:juanibiapina/sub";
      inputs.nixpkgs.follows = "nixpkgs"; # Optional
    };
  };

# ...
}
```

Then add it to your packages:

```nix
{
  environment.systemPackages = with pkgs; [
    inputs.sub.packages."${pkgs.system}".sub
    # ...
  ];
}
```
</details>

<details>
<summary>Nix with Flakes (including setup)</summary>

This repository is a flake that exports a function
`lib.${system}.mkSubDerivation`. This function creates a package for your cli
that uses `sub` as the entry point and already includes the [Setup](#setup).

For an example on how to use it, check out https://github.com/ggazzi/dev-cli-utils

Thanks [@ggazzi](https://github.com/ggazzi) for writing this module.
</details>

## Setup

This section explains how to set up a CLI called `hat` using `sub`.

### Examples

For a simple example, check out a [hello
world](https://github.com/juanibiapina/sub/tree/master/examples/hello) project.

For a complete example with lots of features, check out the
[complete](https://github.com/juanibiapina/sub/tree/master/examples/complete)
example project.

### As an alias

The quickest way to get started with `sub` is to define an alias for your CLI
in your shell:

```sh
alias hat='sub --name hat --absolute /path/to/cli/root --'
```

Where `/path/to/cli/root` contains a `libexec` directory with executable
scripts, for example:

```
.
└── libexec
    ├── user-script1
    ├── user-script2
    └── user-script3
```

### As an executable

A more reliable way is to use an executable script as the entry point. Given
the following directory structure:

```
.
├── bin
│   └── hat
└── libexec
    ├── user-script1
    ├── user-script2
    └── user-script3
```

The entry point in `bin/hat` is then:

```sh
#!/usr/bin/env bash

sub --name hat --executable "${BASH_SOURCE[0]}" --relative ".." -- "$@"
```

The `--executable` argument tells `sub` where the CLI entry point is located.
This will almost always be `${BASH_SOURCE[0]}`. The `--relative` argument tells
`sub` how to find the root of the CLI starting from the CLI entry point. In the
line above, just replace `hat` with the name of your CLI.

## Usage

Once you have set up your CLI (we called it `hat`), you can get help by running:

```sh
$ hat --help
```
```
Usage: hat [OPTIONS] [commands_with_args]...

Arguments:
  [commands_with_args]...

Options:
      --usage                  Print usage
  -h, --help                   Print help
      --completions            Print completions
      --commands               Print subcommands
      --extension <extension>  Filter subcommands by extension

Available subcommands:
    user-script1
    user-script2
    user-script3
```

To invoke a subcommand, use:

```
$ hat user-script1
```

To get help for a command, use the built in `--help` flag:

```sh
hat --help <commandname>
```
or
```sh
hat <commandname> --help
```

## Documenting commands

In order to display help information, `sub` looks for special comments in the
corresponding script. A fully documented `hello` script could look like this:

```sh
#!/usr/bin/env bash
#
# Summary: Say hello
#
# Usage: {cmd} <name> [--spanish]
#
# Say hello to a user by name.
#
# With the --spanish flag, the greeting will be in Spanish.

set -e

declare -A args="($_HAT_ARGS)"

if [[ "${args[spanish]}" == "true" ]]; then
  echo "¡Hola, ${args[name]}!"
else
  echo "Hello, ${args[name]}!"
fi
```

`sub` looks for special comments in a comment block in the beginning of the
file. The special comments are:

- `Summary:` A short description of the script.
- `Usage:` A description of the arguments the script accepts. Note that the
  Usage comment, when present, has specific syntactic rules and is used to
  parse command line arguments. See [Validating arguments](#validating-arguments)
  and [Parsing arguments](#parsing-arguments) for more information.
- `Options:` A description of the options the script accepts. This is used to
  display help information and generate completions. See
  [Completions](#completions) for more details.
- Extended documentation: Any other comment lines in this initial block will be
  considered part of the extended documentation.

## Validating arguments

`sub` automatically validates arguments to scripts based on the `Usage`
comment when it is present. The syntax for the `Usage` comment is:

```
# Usage: {cmd} <positional> [optional] [-u] [--long] [--value=VALUE] [--exclusive]! [rest]...
```

- `{cmd}`: This special token represents the name of the command and is always required.
- `<positional>`: A required positional argument.
- `[optional]`: An optional positional argument.
- `[-u]`: An optional short flag.
- `[--long]`: An optional long flag.
- `[--value=VALUE]`: An optional long flag that takes a value.
- `[--exclusive]!`: An optional long flag that cannot be used with other flags.
- `[rest]...`: A rest argument that consumes all remaining arguments.

Short and long flags can also be made required by omitting the brackets.

When invoking a script with invalid arguments, `sub` will display an error. For
example, invoking the `hello` script from the previous section with invalid
arguments:

```sh
$ hat hello
```

```
error: the following required arguments were not provided:
  <name>

Usage: hat hello --spanish <name>

For more information, try '--help'.
```

## Parsing arguments

When arguments to a script are valid, `sub` sets an environment variable called
`_HAT_ARGS` (where `HAT` is the capitalized name of your CLI). This variable
holds the parsed arguments as a list of key value pairs. The value of this
variable is a string that can be evaluated to an associative array in bash
scripts:

```sh
declare -A args="($_HAT_ARGS)"
```

Which can then be used to access argument values:

```sh
echo "${args[positional]}"

if [[ "${args[long]}" == "true" ]]; then
  # ...
fi
```

Every key and value in the variable is single quoted, so any argument value is
safe to read this way. Quotes, `$`, backticks, newlines and globs are passed
through literally and are never expanded or executed by the shell.

Two things to keep in mind:

- The idiom requires **bash 5.1 or later**. On bash 4.x it silently produces an
  empty array, bash 5.0 errors, and zsh cannot use it at all.
- Arguments that accept multiple values (`[rest]...`, and the default `args`
  when a script has no `Usage` comment) are joined with a single space, so
  element boundaries are lost. Use `"$@"` when boundaries matter.

## Raw arguments

Scripts always receive the original command line arguments unchanged, in the
original order, as `"$@"`. `sub` runs the script directly, without a shell, and
never rewrites argument values. Argument validation from the `Usage` comment
still happens first, so a script only runs when its arguments are valid.

## Completions

sub automatically provides completions for subcommand names.

To enable completions for positional arguments in the `Usage` comment, add an
`Options:` comment with a list of arguments. An option must have the format:
`name (completion_type): description`. Completion type is optional.
The following completion types are supported:

- `` `command` ``: Runs a command to generate completions. The command should print
  completions to stdout:

```sh
# Usage: {cmd} <file>
# Options:
#   file (`ls -1`): File or directory

# script logic
# ...
```

- `script`: Invokes the current script to generate completions. This allows for
  more complex completions:

```sh
# Usage: {cmd} <name>
# Options:
#   name (script): A name

# check if we're being requested completions
if [[ "$_HAT_COMPLETE" == "true" ]]; then
  if [[ "$_HAT_COMPLETE_ARG" == "name" ]]; then
    echo "Alice"
    echo "Bob"
    echo "Charlie"
    # note that you can have any logic here to generate completions
  fi

# make sure to exit when generating completions to prevent the script from running
  exit 0
fi

# read arguments
declare -A args="($_HAT_ARGS)"

# say hello
echo "Hello, ${args[name]}!"
```

## Nested subcommands

`sub` supports nested directories for hierarchical command structures. For
example, given the following directory structure:

```
.
└── libexec
    └── nested
        ├── README
        └── user-script2
```

`user-script2` can be invoked with:

```sh
$ hat nested user-script2
```

Directories can be nested arbitrarily deep.

A `README` file can be placed in a directory to provide a description of the
subcommands in that directory. The `README` file should be formatted like a
script, with a special comment block at the beginning:

```sh
# Summary: A collection of user scripts
#
# This directory contains scripts that do magic.
# This help can be as long as you want.
# The Usage comment is ignored in README files.
```

## Aliases

To define an alias, simply create a symlink. For example, in the `libexec`
directory:

```sh
ln -s user-script1 us1
```

Aliases can also point to scripts in subdirectories:
```sh
ln -s nested/user-script2 us2
```

The full power of symlinks can be used to create complex command structures.

## Sharing code between scripts

When invoking subcommands, `sub` sets an environment variable called
`_HAT_ROOT` (where `HAT` is the capitalized name of your CLI. This variable
holds the path to the root of your CLI. It can be used, for instance, for
sourcing shared scripts from a `lib` directory next to `libexec`:

```sh
source "$_CLINAME_ROOT/lib/shared.sh"
```

## Caching

When invoking subcommands, `sub` sets an environment variable called
`_HAT_CACHE` (where `HAT` is the capitalized name of your CLI. This variable
points to an XDG compliant cache directory that can be used for storing
temporary files shared between subcommands.

## Migrating to Sub 2.x

### change --bin to --executable

The `--bin` argument was renamed to `--executable` to better reflect its purpose.

### Usage comments

Sub 2.x introduces automatic validation and parsing of command line arguments
based on special Usage comments in scripts. If you previously used arbitrary
Usage comments in sub 1.x for the purpose of documenting, you can run `sub`
with the `--validate` flag to check if your scripts are compatible with the new
version.

Example:
```
$ sub --name hat --absolute /path/to/cli/root -- --validate
```

### Help, commands and completions

If you used the `help`, `commands` or `completions` subcommands, they are now
`--help`, `--commands` and `--completions` flags respectively.

## Inspiration

- [sub from basecamp](https://github.com/basecamp/sub)
- [sd](https://github.com/cv/sd)

sub

sub Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

sub

sub Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README