If you enjoy this tutorial, consider sponsoring me, Daniel Higginbotham, through GitHub sponsors. As of April 2022 I am spending two days a week working on free Clojure educational materials and open source libraries to make Clojure more beginner-friendly, and appreciate any support!

Please also consider sponsoring Michiel Borkent, aka borkdude, who created babashka. Michiel is doing truly incredible work to transform the Clojure landscape, extending its usefulness and reach in ways that benefit us all. He has a proven track record of delivering useful tools and engaging with the commuity.

From a user perspective, babashka is a scripting runtime for the Clojure programming language. It lets you execute Clojure programs in contexts where you’d typically use bash, ruby, python, and the like. Use cases include build scripts, command line utilities, small web applications, git hooks, AWS Lambda functions, and everywhere you want to use Clojure where fast startup and/or low resource usage matters.

You can run something like the following in a terminal to immediately execute your Clojure program:

If you’re familiar with Clojure, you’ll find this significant because it eliminates the startup time you’d otherwise have to contend with for a JVM-compiled Clojure program, not to mention you don’t have to compile the file. It also uses much less memory than running a jar. Babashka makes it feasible to use Clojure even more than you already do.

If you’re unfamiliar with Clojure, using Babashka is a great way to try out the language. Clojure is a hosted language, meaning that the language is defined independently of the underlying runtime environment. Most Clojure programs are compiled to run on the Java Virtual Machine (JVM) so that they can be run anywhere Java runs. The other main target is JavaScript, allowing Clojure to run in a browser. With Babashka, you can now run Clojure programs where you’d normally run bash scripts. The time you spend investing in Clojure pays dividends as your knowledge transfers to these varied environments.

From an implementation perspective, Babashka is a standalone, natively-compiled binary, meaning that the operating system executes it directly, rather than running in a JVM. When the babashka binary gets compiled, it includes many Clojure namespaces and libraries so that they are usable with native performance. You can check out the full list of built-in namespaces. Babashka can also include other libraries, just like if you’re using deps.edn or Leiningen.

The binary also includes the Small Clojure Interpreter (SCI) to interpret the Clojure you write and additional libraries you include on the fly. Its implementation of Clojure is nearly at parity with JVM Clojure, and it improves daily thanks to Michiel Borkent's ceaseless work. It’s built with GraalVM. This guide is focused on becoming productive with Babashka and doesn’t cover the implementation in depth, but you can learn more about it by reading this article on the GraalVM blog.

I won’t go into the benefits of Clojure itself because there are plenty of materials on that elsewhere.

Beyond the fact that it’s Clojure, Babashka brings a few features that make it stand apart from contenders:

First-class support for multi-threaded programming. Clojure makes multi-threaded programming simple and easy to write and reason about. With Babashka, you can write straightforward scripts that e.g. fetch and process data from multiple databases in parallel.

Real testing. You can unit test your Babashka code just as you would any other Clojure project. How do you even test bash?

Real project organization. Clojure namespaces are a sane way to organize your project’s functions and build reusable libraries.

Cross-platform compatibility. It’s nice not having to worry that an OS X-developed script is broken in your continuous integration pipeline.

Interactive Development. Following the lisp tradition, Babashka provides a read-eval-print loop (REPL) that gives you that good good bottom-up fast-feedback feeling. Script development is inherently a fast; Babashka makes it a faster.

Built-in tools for defining your script’s interface. One reason to write a shell script is to provide a concise, understandable interface for a complicated process. For example, you might write a build script that includes build and deploy commands that you call like

Babashka comes with tools that gives you a consistent way of defining such commands, and for parsing command-line arguments into Clojure data structures. Take that, bash!

A rich set of libraries. Babashka comes with helper utilities for doing typical shell script grunt work like interacting with processes or mucking about with the filesystem. It also has support for the following without needing extra dependencies:

And of course, you can add Clojure libraries as dependencies to accomplish even more. Clojure is a gateway drug to other programming paradigms, so if you ever wanted to do e.g. logic programming from the command line, now’s your chance!

Good error messages. Babashka’s error handling is the friendliest of all Clojure implementations, directing you precisely to where an error occurred.

Installing with brew is brew install borkdude/brew/babashka.

For other systems, see Babashka’s complete installation instructions.

Here’s what’s going on: bb interprets the Clojure code you’ve written, executing it on the fly. prn prints to stdout, which is why "Hello, inner world!" is returned in your terminal.

Notice that the quotes are maintained when the value is printed. bb will print the stringified representation of your data structure. If you updated hello.clj to read

Then ["It’s" "me," "your" "wacky" "subconscious!"] would get printed, and "Hello, inner world!" would not. You must use a printing function on a form for it to be sent to stdout

If you want to print a string without the surrounding quotes, you can use

As for the lack of namespace: this is part of what makes Babashka useful as a scripting tool. When you’re in a scripting state of mind, you want to start hacking on ideas immediately; you don’t want to have to deal with boilerplate just to get started. Babashka has your babacka.

You can define a namespace (we’ll look at that more when we get into project organization), but if you don’t then Babashka uses the user namespace by default. Try updating your file to read:

Running it will print "Hello from user, inner world!". This might be surprising because there’s a mismatch between filename (hello.clj) and namespace name. In other Clojure implementations, the current namespace strictly corresponds to the source file’s filename, but Babashka relaxes that a little bit in this specific context. It provides a scripting experience that’s more in line with what you’d expect from using other scripting languages.

You might want to include a namespace declaration because you want to require some namespaces. With JVM Clojure and Clojurescript, you typically require namespaces like this:

It’s considered bad form to require namespaces by putting (require '[clojure.string :as str]) in your source code.

That’s not the case with Babashka. You’ll see (require …​) used liberally in other examples, and it’s OK for you to do that too.

What if you want to execute your script by typing something like ./hello instead of bb hello.clj? You just need to rename your file, add a shebang, and chmod +x that bad boy. Update hello.clj to read:

Then run this in your terminal:

First you rename the file, then you call chmod +x on it to make it executable. Then you actually execute it, saying hi to your own inner world which is kind of adorable.

Here’s what you learned in this section:

The babashka.cli docs do a good job of explaining how to use the library to meet all your command line parsing needs. Rather than going over every option, I’ll just focus on what we need to build our dream journal. To parse options, we require the babashka.cli namespace and we define a CLI spec:

A CLI spec is a map where each key is a keyword, and each value is an option spec. This key is the long name of your option; :entry corresponds to the flag --entry on the command line.

The option spec is a map you can use to further config the option. :alias lets you specify a short name for you options, so that you can use e.g. -e instead of --entry at the command line. :desc is used to create a summary for your interface, and :require is used to enforce the presence of an option. :coerce is used to transform the option’s value into some other data type.

We can experiment with this CLI spec in a REPL. There are many options for starting a Babashka REPL, and the most straightforward is simply typing bb repl at the command line. If you want to use CIDER, first add the file bb.edn and put an empty map, {}, in it. Then you can use cider-jack-in. After that, you can paste in the code from the snippet above, then paste in this snippet:

Note that cli/parse-opts returns a map with the parsed options, which will make it easy to use the options later.

Leaving out a required flag throws an exception:

cli/parse-opts is a great tool for building an interface for simple scripts! You can communicate that interface to the outside world with cli/format-opts. This function will take an option spec and return a string that you can print to aid people in using your program. Behold:

babashka.cli goes beyond option parsing to also giving you a way to dispatch subcommands, which is exactly what we want to get ./journal add --entry "…​" working. Here’s the final version of journal:

Try it out with the following at your terminal:

The function cli/dispatch at the bottom takes a dispatch table as its first argument. cli/dispatch figures out which of the arguments you passed in at the command line correspond to commands, and then calls the corresponding :fn. If you type ./journal add …​, it will dispatch the add-entry function. If you just type ./journal with no arguments, then the help function gets dispatched.

The dispatched function receives a map as its argument, and that map contains the :opts key. This is a map of parsed command line options, and we use it to build our dream journal entry in the add-entry function.

And that, my friends, is how you build an interface for your script!

One way to organize our dream journal project would be to create the following file structure:

Already, you can see that this looks both similar to typical Clojure project file structures, and a bit different. We’re placing our namespaces in the src/journal directory, which lines up with what you’d see in JVM or ClojureScript projects. What’s different in our Babashka project is that we’re still using ./journal to serve as the executable entry point for our program, rather than the convention of using ./src/journal/core.clj or something like that. This might feel a little weird but it’s valid and it’s still Clojure.

And like other Clojure environments, you need to tell Babashka to look in the src directory when you require namespaces. You do that by creating the file bb.edn in the same directory as journal and putting this in it:

bb.edn is similar to a deps.edn file in that one of its responsibilities is telling Babashka how to construct your classpath. The classpath is the set of the directories that Babashka should look in when you require namespaces, and by adding "src" to it you can use (require '[journal.add]) in your project. Babashka will be able to find the corresponding file.

Note that there is nothing special about the "src" directory. You could use "my-code" or even "." if you wanted, and you can add more than one path. "src" is just the convention preferred by discerning Clojurians the world over.

With this in place, we’ll now update journal so that it looks like this:

Now the file is only responsible for parsing command line arguments and dispatching to the correct function. The add functionality has been moved to another namespace.

You can see on line 4 that we’re requiring a new namespace, journal.add. The file corresponding to this namespace is ./src/journal/add.clj. Here’s what that looks like:

Look, it’s a namespace declaration! And that namespace declaration has a (:require …​) form. We know that when you write Babashka scripts, you can forego declaring a namespace if all your code is in one file, like in the original version of journal. However, once you start splitting your code into multiple files, the normal rules of Clojure project organization apply:

To finish our tour of our new project organization, here’s ./src/journal/utils.clj:

If you call ./journal add -e "visited by the tooth fairy, except he was a balding 45-year-old man with a potbelly from Brooklyn", it should still work.

Now lets create a the journal.list namespace. Open the file src/journal/list.clj and put this in it:

This doesn’t format the timestamp, but other than that it lists our entries in reverse-chronologial order, just like we want. Yay!

To finish up, we need to add journal.list/list-entries to our dispatch table in the journal file. That file should now look like this:

Let’s look at what that means in more concrete terms. Suppose you want to encrypt your dream journal. You find out about stash, "a command line program for storing text data in encrypted form." This is exactly what you need! Except it’s written in Haskell, and furthermore it has a terminal user interface (TUI) rather than a command-line interface.

That is, when you run stash from the command line it "draws" an ascii interface in your terminal, and you must provide additional input to store text. You can’t store text directly from the command line with something like

If that were possible, then you could use stash from within your Bashka project by using the babashka.process/shell function, like this:

bp/shell is lets you take advantage of a program’s command-line interface; but again, stash doesn’t provide that.

However, stash provides a pod interface, so we can use it like this in a Clojure file:

Let’s start at the last line, (stash/set 20221210092035 "dream entry"). This is the point of pods: they expose an external process’s commands as Clojure functions. They allow these processes to have a Clojure interface so that you can interact with them by writing Clojure code, as opposed to having to shell out or make HTTP calls or something like that.

In the next section I’ll explain the rest of the snippet above.

Where does the stash/set function come from? Both the namespace pod.rorokimdim.stash and the functions in it are dynamically generated by the call (pods/load-pod 'rorokimdim/stash "0.3.1").

For this to be possible, the external program has to be written to support the pod protocol. "Protocol" here does not refer to a Clojure protocol, it refers to a standard for exchanging information. Your Clojure application and the external application need to have some way to communicate with each other given that they don’t live in the same process and they could even be written in different languages.

By implementing the pod protocol, a program becomes a pod. In doing so, it gains the ability to tell the client Clojure application what namespaces and functions it has available. When the client application calls those functions, it encodes data and sends it to the pod as a message. The pod will be written such that it can listen to those messages, decode them, execute the desired command internally, and send a response message to the client.

The pod protocol is documented in the pod GitHub repo.

You can give Babashka a Clojure expression and it will evaluate it and print the result:

Personally I haven’t used this much myself, but it’s there if you need it!

If we wanted to call our journal.add/add-entry function directly, we could do this:

When you use bb -x, you can specify the fully-qualified name of a function and Babashka will call it. It will parse command-line arguments using babashka.cli into a Clojure value and pass that to the specified function. See the -x section of the Babashka docs for more information.

You can also use bb -m some-namespace/some-function to call a function. The difference between this and bb -x is that with bb -m, each command line argument is passed unparsed to the Clojure function. For example:

When using bb -m, you can just pass in a namespace and Babashka will call the -main function for that namespace. Like, if we wanted our journal.add namespace to work with this flavor of invocation, we would write it like this:

And we could do this:

Note that for bb -x or bb -m to work, you must set up your bb.edn file so that the namespace you’re invoking is reachable on the classpath.

First, let’s look at a very basic task definition. Tasks are defined in your bb.edn file. Update yours to look like this:

Tasks are defined using a map under the :tasks keyword. Each key of the map names a task, and it should be a symbol. Each value should be a Clojure expression. In this example, the welcome names a task and the associated expression is (println "welcome to your dream journal").

When you call bb welcome, it looks up the welcome key under :tasks and evaluates the associated expression. Note that you must explicitly print values if you want them to be sent to stdout; this wouldn’t print anything:

Let’s say you wanted to create a task to delete your journal entries. Here’s what that would looke like:

If you run bb clear it will delete your entries.edn file. This works because shell is automatically referred in namespaces, just clojure.core functions are.

If you wanted to delete your file in a cross-platform-friendly way, you could use the babashka.fs/delete-if-exists function. To do that, you must require the babashka.fs namespace. You might assume that you could update your bb.edn to look like this and it would work, but it wouldn’t:

Instead, to require namespaces you must do so like this:

We still want to be able to call bb add and bb list. We have what we need to implement bb list; we can just update bb.edn to look like this:

In the previous task examples I excluded the :paths key because it wasn’t needed, but we need to bring it back so that Babashka can find journal.list on the classpath. journal.list/list-entries takes one argument that gets ignored, so we can just pass in nil and it works.

journal.add/add-entries, however, takes a Clojure map with an :entries key. Thus we need some way of parsing the command line arguments into that map and then passing that to journal.add/add-entries. Babashka provides the exec function for this. Update your bb.edn like so, and everything should work:

Now we can call this, and it should work:

The key here is the exec function. With (exec 'journal.add/add-entry), it’s as if you called this on the command line:

exec will parse command line arguments in the same way as bb -x does and pass the result to the designated function, which is journal.add/add-entry in this example.

Babashka’s task system has even more capabilities, which I’m not going to cover in detail but which you can read about in the Task runner section of the Babashka docs.

I do want to highlight two very useful features: task dependencies and parallel task execution.

Babashka let’s you define task dependencies, meaning that you can define task-a to depend on task-b such that if you run bb task-a, internally task-b will be executed if needed. This is useful for creating compilation scripts. If you were building a web app, for example, you might have separate tasks for compiling a backend jar file and frontend javascript file. You could have the tasks build-backend, build-frontend, and then have a build task that depended on the other two. If you were to call bb build, Babashka would be able to determine which of the other two tasks needed to be run and only run them when necessary.

Parallel task execution will have Babashka running multiple tasks at the same time. In our build example, bb build could run build-backend and build-frontend at the same time, which could be a real time saver.