cli-tools is a complement to Babashka used to create tools
with sub-commands, much like Babashka tasks. It is effectively
a layer on top of org.clojure/tools.cli.
cli-tools is more verbose than babashka-cli and more opinionated.
At the core, you define local symbols and instructions for how those symbols map to command line options
or positional arguments; cli-tools takes care of the majority of command line parsing and validation
for you.
cli-tools is intended to create three types of command lines tools:
- A simple tool simply parses its command line arguments and executes some code using those arguments (think:
lsorcat) - A common tool is composed of multiple commands, across multiple namespaces. The first command line argument
will select the specific sub-command to execute. (think:
git) - A complex tool organizes some commands into command groups that share an initial name (think
kubectl)
For tools with multiple commands, cli-tools automatically adds
a built-in help command to list out what commands are available, and
can even perform basic searches for commands.
For complex tools, what cli-tools offers is discoverability. You define the switches, options, and arguments for each command, and each command gets a --help switch to print
out the command's summary. The help command
that can list out all the commands available, neatly organized, and can even do a simple
search for you. There's even (experimental) support for zsh completions for your tool and all of its categories, commands, and options.
This kind of discoverability is a big improvement over shell aliases, and one-off shell scripts that leave you guessing what they do and what arguments need to be passed in.
cli-tools also offers great feedback, using indentation, color, and careful attention
to detail, to provide tool users with consistent, readable, and friendly error messages, command summaries, and so forth.
cli-tools can work with Babashka, or with Clojure, but the near instantaneous startup time of Babashka is compelling
for the kind of low-ceremony tools that cli-tools is intended for.
Although cli-tools can be used to build shared tools, it is also fully intended for developers to create a personal
toolkit of commands specific to their individual workflows, as an alternative to a collection of shell aliases and one-off shell scripts.
Below is an example of the author's personal toolkit, flow:
A complete and open-source example is dialog-tool, which also shows how to organize a tool so that it can be installed as a Homebrew formula.
Note that dialog-tool uses a slightly earlier version of cli-tools.
Documentation starts with the overview.
cli-tools is compatible with Clojure 1.11 and above, and w/ Babashka.
io.github.hlship/cli-tools is (c) 2022-present Howard M. Lewis Ship.
It is released under the terms of the Apache Software License, 2.0.