September 15, 2022

Today I'm excited to share bbin, a tool that makes it easy to install Babashka scripts and projects on your system PATH.

Here's an example of how to install neil using bbin:

$ bbin install io.github.babashka/neil
{:lib io.github.babashka/neil,
 :coords
 {:git/url "https://github.com/babashka/neil",
  :git/tag "v0.1.45",
  :git/sha "0474d4cb5cfb0207265a4508a0e82ae7a293ab61"}}

$ neil --version
neil 0.1.45

Check out the Scripts and Projects page for even more tools you can install with bbin. Linux, macOS, and Windows are all supported.

Why bbin?

Thanks to its lack of JVM startup time, Babashka provides opportunities for Clojure developers to write CLI tools with a similar user experience as other popular scripting languages like Python, Ruby, or Go. However, these other languages already have their own package managers, whereas Babashka lacks an easy way to distribute code for others to use directly from the command-line.

Existing Babashka projects such as neil have relied on OS-specific package managers like Homebrew and Scoop to put Babashka scripts on the user's PATH. This approach is a lot of work for project maintainers and creates a high barrier of entry for Babashka developers to share their code.

bbin was designed to solve this problem. Since bbin is based around tools.deps conventions, as long as your code is on GitHub (or some other Git repo provider), it's now trivial for anyone to install your code with a short command and use it as a CLI program. In addition to existing tools.deps sources, we can also use HTTP URLs to share scripts outside of a Git repo.

Features

bbin can install scripts and projects from a variety of providers (Filesystem, HTTP, Git, Maven) and artifacts (files, directories, JARs):

$ bbin install io.github.rads/watch
$ bbin install io.github.babashka/neil --latest-sha
$ bbin install org.babashka/http-server --mvn/version 0.1.11
$ bbin install io.github.babashka/bbin --local/root ~/src/bbin --as bbin-dev

bbin can also install a "tool" CLI from a namespace of functions, similar to clj -T. It will even generate a default help message for you based on your docstrings:

$ bbin install io.github.borkdude/quickblog --latest-sha
$ quickblog
Usage: quickblog <command>

  quickblog clean              Removes cache and output directories
  quickblog serve              Runs file-server on `port`.
  quickblog new                Creates new `file` in posts dir.
  quickblog quickblog          Alias for `render`
  quickblog migrate            Migrates from `posts.edn` to post-local metadata
  quickblog render             Renders posts declared in `posts.edn` to `out-dir`.
  quickblog refresh-templates  Updates to latest default templates
  quickblog watch              Watches posts, templates, and assets for changes. Runs file server using

See the CLI docs in the README for information on all available features.

Next Steps

This project was inspired by a proposal on the main Babashka repository for a bb install command. After discussing this further with Michiel, we agreed for now it would be better to keep these features separate from Babashka core.

Regardless of whether this code becomes more integrated with Babashka in the future, I plan to keep maintaining the bbin CLI. This means you can start using bbin today without worrying about things changing in the future.

To help out with this project, the best thing you can do is start using bbin and testing it out for different use cases. If you come up with something cool, be sure to share it on the Scripts and Projects page.

If you find any bugs or have anything else you'd like to comment on, you're welcome to create an issue on the GitHub repo or leave a message on Slack in #babashka-bbin.

Acknowledgements

I'd like to thank these fine folks for helping with testing, feedback, and code contributions: