Zub is a model for setting up shell programs that use subcommands, like somewhat like this git CLI. Building a zub program does not require you to write shell scripts in bash β you can write subcommands in any scripting language you prefer.
Zub started as a fork of qrush/sub, but has diverged enough that a new name and repo felt warranted.
A zub program is run at the command line using this style:
$ [name of program] [subcommand] [(args)]
So, with a zub program called my, and scripts (subcommands) called
date and weather, you would be able to invoke the following:
$ my date
# OR
$ my weather --additional args
First, make the shared zub binary (and zub-scaffold) available on your
PATH. The easiest way is mise, which pulls a
prebuilt binary from the GitHub releases:
mise use -g github:jgdavey/zub
Or grab a release tarball directly (Linux and Mac currently supported)
and drop both binaries on your PATH:
curl -L https://github.com/jgdavey/sub/releases/download/latest/zub-<version>-<target>.tar.gz \
| tar xz && mv zub zub-scaffold ~/.local/bin/
After cloning this repo, run:
cargo install --path .
β¦which puts zub and zub-scaffold in ~/.cargo/bin.
Use the zub-scaffold tool to generate a fresh program tree:
zub-scaffold rush
This creates a rush/ directory containing a zub.yml (with name: rush), a
self-locating bin/rush shim, the completion scripts, an example libexec/who
command, and an empty share directory. There's no source-templating or build
step β your program's identity comes entirely from zub.yml. (Give it a better
name than rush!)
By default the tree is created at <cwd>/<name>. Pass --dir <path> to create
it somewhere else (the program name still comes from the positional argument):
zub-scaffold rush --dir /opt/tools/rush # create the tree at /opt/tools/rush
zub-scaffold -V (or --version) prints its version and exits.
By default zub-scaffold refuses to touch an existing directory. To refresh the
generated files of a program you already have β after upgrading zub, say β run
it with --regenerate from the program's parent directory:
zub-scaffold rush --regenerate # ask before replacing each existing file
zub-scaffold rush --regenerate=clobber # replace them all, no prompts
Regeneration only ever rewrites the files zub-scaffold generates (zub.yml,
bin/rush, the completion scripts, and the example libexec/who); missing ones
are written silently. Your own libexec commands and share contents are never
touched.
Then load your program in your shell. Say your program lives at $HOME/.rush:
For bash users:
echo 'eval "$($HOME/.rush/bin/rush init - bash)"' >> ~/.bash_profile
exec bash
For zsh users:
echo 'eval "$($HOME/.rush/bin/rush init - zsh)"' >> ~/.zshenv
source ~/.zshenv
init derives the PATH entries and completion wiring from your zub.yml, and
defines a shell function that runs zub -C <your config> under the hood.
At its heart, zub is just a way to organize scripts, but the folder structure and optional frontmatter enhance what would be a pile of files by providing discoverability, help, and completions.
Here's some quick examples:
$ rbenv # prints out usage and subcommands
$ rbenv versions # runs the "versions" subcommand
$ rbenv shell 1.9.3-p194 # runs the "shell" subcommand, passing "1.9.3-p194" as an argument
Each subcommand maps to a separate, standalone executable program. Zub programs are laid out like so:
.
βββ zub.yml # declares your program's name (and optional metadata)
βββ bin/<name> # entrypoint shim that hands off to the shared zub binary
βββ completions # bash/zsh completions
βββ libexec # <- where you put all your subcommand scripts/executables
βββ share # <- static data storage
The zub.yml at the root names your program. A single shared zub binary
provides the dispatcher and every built-in command; it learns which program it
is from the config file you point it at, so there's no build step or
source-templating involved in making a program:
name: rush
# optional:
version: 0.1.0
description: A delicious way to organize programs
# where subcommands are collected (defaults to the three entries below):
command_roots:
- $ZUB_ROOT/libexec
- $ZUB_USER_ROOT/libexec
- $ZUB_LOCAL_ROOT/libexecBy default subcommands are collected from three directories: <root>/libexec
(the program itself), ~/.local/<name>/libexec (your own per-user commands),
and .<name>/libexec in the current project (a per-project overlay). Set command_roots to change this β it's an ordered,
lowest-precedence-first list, so a command in a later root overrides the same
name in an earlier one. A bare relative path is resolved against the program
root, and a nonexistent directory is simply skipped. Each entry may use these
pseudo-variables:
| Variable | Expands to |
|---|---|
$ZUB_ROOT |
the program root |
$ZUB_INSTANCE |
the program name |
$PWD |
your current directory, literally |
$ZUB_USER_ROOT |
$HOME/.local/<name> |
$ZUB_LOCAL_ROOT |
the nearest .<name> directory β see below |
$ZUB_LOCAL_ROOT is the local counterpart of $ZUB_ROOT: the .<name>
directory that holds your project's own libexec/share. It's found by walking
up from your current directory (the current directory included) to the first
ancestor that has one, the way git finds .git. So a .rush/libexec at the
top of a project supplies its commands anywhere inside that project, not just in
the one directory that contains it. Because the variable already names the
.<name> directory, you never respell it in a template β $ZUB_LOCAL_ROOT/libexec,
mirroring $ZUB_ROOT/libexec.
The search stops at the first .<name> it finds, so a nearer one shadows a
further one even if it holds no libexec. The walk continues to the filesystem
root, so a ~/.rush/ would also be picked up everywhere under your home
directory β but for per-user commands prefer ~/.local/rush/libexec
($ZUB_USER_ROOT), which applies everywhere and isn't shadowed by a project's
.rush.
$ZUB_USER_ROOT sits between the two: a user command overrides the program's
command of the same name, and a project-local one overrides both. If $HOME is
unset, entries mentioning $ZUB_USER_ROOT are dropped.
If no .<name> is found at all, entries mentioning $ZUB_LOCAL_ROOT are simply
dropped. To get the old exact-match behavior β an overlay that applies only in
the directory holding it β write $PWD/.$ZUB_INSTANCE/libexec instead.
A root that references $PWD or $ZUB_LOCAL_ROOT is treated as
working-directory-local, and its commands are marked (local) in listings.
You run your program through bin/<name>, a tiny generated shim that re-invokes
the shared zub binary with your config:
#!/bin/sh
here="$(cd "$(dirname "$0")/.." && pwd)"
exec zub -C "$here/zub.yml" "$@"The zub binary itself must be on your PATH. The shim derives your program's
root from the location of zub.yml (its parent directory), so you can move the
program tree anywhere and it keeps working. You can also invoke
zub -C /path/to/zub.yml <subcommand> directly, or export ZUB_CONFIG=/path/to/zub.yml
so a bare zub <subcommand> knows which program to run. (An explicit -C always
wins over ZUB_CONFIG.)
zub -V (or --version) prints the zub binary's version and exits.
Each subcommand executable does not necessarily need to be in bash. It can be any program, shell script, or even a symlink. It just needs to run.
Here's an example of adding a new subcommand. Let's say your program is named rush. Run:
touch libexec/who
chmod a+x libexec/who
Now open up your editor, and dump in:
#!/usr/bin/env bash
set -e
whoOf course, this is a simple example... but now rush who should work!
$ rush who
qrush console Sep 14 17:15
You can run any script or program in the libexec directly, as long as it is executable.
You get a few commands that come with every zub program:
commands: Prints out every subcommand available.completions: Helps kick off subcommand autocompletion.help: Document how to use each subcommand.init: Shows how to load your program with autocompletions, based on your shell.new: Generates a new subcommand script (pre-filled with front-matter).source: Prints the source of a subcommand.
These are built into the zub binary. If you ever need to replace one with your
own script, name a libexec command after it and add override: true to that
script's front-matter (see below) β otherwise the built-in always wins.
(Creating a brand new program is handled by the separate zub-scaffold tool, not
a built-in β see "Make your own program" below.)
If you ever need to reference files inside of your program's installation, say to access a file in the share directory, your program exposes the directory path in the environment as ZUB_ROOT.
Here's an example subcommand you could drop into your libexec directory to show this in action: (make sure to correct the name!)
#!/usr/bin/env bash
set -e
echo $ZUB_ROOTYou can also use this environment variable to call other commands
inside of your libexec directly. Composition of this type very much
encourages reuse of small scripts, and keeps scripts doing one thing
simply.
Each subcommand can opt into self-documentation, which allows the subcommand to provide information when rush and rush help [SUBCOMMAND] is run.
This is done with a small block of front-matter at the top of the script: a
run of contiguous lines that begin with your comment character followed by @
(#@ for shell/Ruby/Python, //@ for JavaScript, ;@ for Lisp, --@ for
SQL/Lua). The text after the sigil is plain YAML. The
parser reads the block, stops at the first non-sigil line, and never touches the
rest of your script β so it stays fast no matter how big your command is.
Here's an example from rush who:
#!/usr/bin/env bash
#@ usage: rush who
#@ summary: Check who's logged in
#@ help: |
#@ This will print out when you run `rush help who`.
#@ You can have multiple lines even!
#@
#@ Show off an example indented
#@
#@ And maybe start off another one?
set -e
whoThe recognized keys are summary, usage, help, complete (see
Autocompletion), dynamic_help (see Dynamic
help), eval, and override (unknown keys are ignored, so the
format can grow without breaking older scripts). Because the body is real YAML,
multi-line help uses a | block scalar and indentation is preserved.
The usage and help text may contain $0, which zub expands to the full
command name (e.g. rush who or rush db migrate).
Now, when you run rush, the "summary" will show up:
usage: rush <command> [<args>]
Some useful rush commands are:
commands List all rush commands
who Check who's logged in
And running rush help who will show the "usage" line, and then the "help" block:
Usage: rush who
This will print out when you run `rush help who`.
You can have multiple lines even!
Show off an example indented
And maybe start off another one?
That's not all you get by convention with zub...
By default, rush help <command> prints only the static front-matter β the
usage line, the summary, and the help block. Set dynamic_help: true when
a command's help can't be written ahead of time (it depends on plugins, files,
or the environment). zub prints the static text first, then also runs the
command with --help appended, sending whatever it writes to stdout below the
static help:
#!/usr/bin/env bash
#@ usage: $0 <env>
#@ summary: Deploy to an environment
#@ help: Deploy the app to a named environment.
#@ dynamic_help: true
set -e
if [ "$1" = "--help" ]; then
echo "Environments:" # zub already prints a blank separator
ls "$ZUB_ROOT/share/environments" # discovered at runtime
exit 0
fi
# ...real deploy logic, using "$1" as the environment...rush help deploy then shows both halves:
Usage: rush deploy <env>
Summary: Deploy to an environment
Deploy the app to a named environment.
Environments:
production
staging
The static help block is optional β with dynamic_help: true, a command with
no front-matter at all is still run with --help. As with --complete below,
the --help branch must
Note
zub exports ZUB_ROOT, ZUB_INSTANCE (the program name), and ZUB_CONFIG to
every subcommand, so a script can find its share/ data or re-invoke the
program with zub <other-command> .... When the walk up from your current
directory found a .<name> directory (the $ZUB_LOCAL_ROOT described under
command_roots above), it is exported as ZUB_LOCAL_ROOT too, so a script can
reach project-local data at $ZUB_LOCAL_ROOT/share just as it reaches the
program's own at $ZUB_ROOT/share. The project directory itself is
$(dirname "$ZUB_LOCAL_ROOT"). The variable is unset when no .<name> was
found. Likewise ZUB_USER_ROOT ($HOME/.local/<name>, whether or not it
exists) is exported for per-user data at $ZUB_USER_ROOT/share; it is unset
when $HOME is.
Your program loves autocompletion. It's the mustard, mayo, or whatever topping you'd like that day for your commands. Just like real toppings, you have to opt into them! Zub provides two kinds of autocompletion:
- Automatic autocompletion to find subcommands (What can this program do?)
- Opt-in autocompletion of potential arguments for your subcommands (What can this subcommand do?)
Opting into argument autocompletion takes two things: declare complete: true
in your script's front-matter, and have the script handle a --complete flag.
The complete: true key lets zub know the script participates in completion
without scanning its body; commands that don't declare it fall back to your
shell's default completion (usually filenames).
When the shell asks zub to complete an argument for your command, zub runs your
script with --complete followed by the arguments typed so far:
rush deploy --complete <args-typed-so-far...>
and sets two environment variables describing where the cursor is:
COMP_LASTARGβ the word currently being completed (empty when the cursor is at a fresh argument)COMP_PENULTβ the word just before it (handy for completing the value of a--flag <value>pair)
Your --complete branch prints the candidate words valid at that position, one
per line, then exits. zub forwards them to the shell, which filters them by
what's already typed ($COMP_LASTARG):
#!/usr/bin/env bash
#@ usage: $0 <env> [--region <r>]
#@ summary: Deploy to an environment
#@ complete: true
set -e
if [ "$1" = "--complete" ]; then
case "$COMP_PENULT" in
--region) printf '%s\n' us-east us-west eu ;; # value for --region
*) printf '%s\n' staging production --region ;;
esac
exit 0
fi
# ...real deploy logic, e.g. deploy to "$1"...So rush deploy <Tab> offers staging production --region, while
rush deploy --region <Tab> offers us-east us-west eu.
Important
A command's --complete branch must exit (via exit, exec, or otherwise)
so the rest of the script doesn't run during completion.
Run the init subcommand after you've prepared your program to get it loading
automatically in your shell.
If you'd rather not hand-write a --complete branch and a --help block, a
subcommand can instead be authored as a usage spec.
usage is jdx's CLI-spec tool: you declare your
command's args, flags, and completions once, and it handles parsing, --help,
and shell completion for you. zub recognizes such scripts and stays out of their
way.
A usage-style subcommand looks like a normal script whose shebang invokes
usage and whose spec lives in #USAGE comments at the top:
#!/usr/bin/env -S usage bash
#USAGE about "Greet a person, maybe loudly"
#USAGE flag "-l --loud" help="Shout the greeting"
#USAGE arg "<name>" help="Who to greet"
greeting="Hello, ${usage_name}"
[ "$usage_loud" = "true" ] && greeting="${greeting^^}"
echo "$greeting"At runtime the usage binary (named in the shebang) parses the arguments and
exports a usage_* variable for each one β zub adds nothing here beyond the
ZUB_* env it gives every subcommand. So this style requires usage to be on
your PATH; that's the one extra dependency, and the shebang is what pulls it
in.
zub detects the #USAGE block (versus zub's own #@) and adapts:
- Listings (
rushandrush help) show the spec'sabouttext as the one-line summary β the only field zub reads in-process. rush help <command>runs the command with--helpand letsusagerender the whole help screen, so it reads exactly like the standalone script.- Completion is automatic β no
complete: true, no--completebranch. zub delegates tousage, which completes from the spec.
The zub-only keys (eval, override, dynamic_help) don't apply to usage
commands; everything those would do is the usage binary's job here.
Note
This is entirely opt-in and per-command: a program can freely mix #@ zub
commands and #USAGE usage commands. A command with neither marker just gets
no documentation, exactly as before.
- Provide a script to convert script headers from old to new format
- Bring completion scripts over during scaffold
- Add an example script (bash?) during scaffold
- Handle namespaced commands
- scaffold: overwrite existing
- Set up CI building
- Add dynamic help support (calling
<name> <sub> --helpinstead of front-matter) - scaffold: allow custom root path
- Improve documentation on custom completions
- Optional integration with usage specs
- (possibly) Cache indexed commands (if perf becomes an issue)
- (possibly) static completion in front-matter?
MIT. See LICENSE.