Ditch your bucket of scripts for a tool belt

If you’re like us at Nextdoor, you have a lot of scripts that do a lot of useful things. Maybe, like us, you have some wiki pages that tells you the full path names of these scripts and the situations and order in which you should run them. You may have also found that you’d rather ask your co-workers how do anything than to try find what you want in that wiki.

If this is your story, it might be time to stop and ask yourself:“Why shouldn’t your set of tools be at least as easy to use as other tools like git, heroku or aws that you use on a daily basis?”

The good news is that you don’t need a centralized tool that does everything in your toolbelt. We decided to embrace decentralization and create a way to run tools as if they were centralized, simply by having them to adhere to a naming convention and reside in the search path. This behavior is enabled for us by a fairly simply open-source tool we call buckle .

buckle performs the following magic:

You place an executable script, somewhere in your executable path, with the name nd-dev~createdb You run this script by typing nd dev createdb .

That’s right, you didn’t even have to type those hyphens and tildes. Maybe you’re not impressed yet, but you can also see what commands are available simply by using autocomplete:

> nd dev<tab><tab>
check createdb django-command help migrate runserver shell taskworker unfrozen

You can also ask for help:

> nd dev help ND Toolbelt Help Showing help for dev The available commands are: dev check Checks and prompts user to update dependencies dev createdb Create a new database. dev django-command Runs a django management command. dev migrate Run migrations on your dev database. dev runserver Run dev webserver. dev shell Starts a django shell. dev taskworker Run dev taskworker.

What’s different about everything above from your average command-line interface (CLI) toolbelt is that is that there is no single nd executable that has all these commands in it. There are a just a bunch of separate scripts.

How do I useit?

Here’s a simple bash session where we create a toolbelt called ‘sash’ with an ‘echo’ command:

> pip install buckle > cat > sash-echo << 'EOF' #!/bin/bash /bin/echo $* EOF > chmod +x sash-echo > export PATH=$(pwd):$PATH > alias sash="BUCKLE_TOOLBELT_NAME=sash buckle" > sash echo "it works" it works

Note that while the above example uses an alias to initialize your toolbelt, you can also create a bash script as your sash executable:

#!/usr/bin/env bash BUCKLE_TOOLBELT_NAME=sash exec buckle $*

By this point, you’ve probably already downloaded buckle from pypi and have redesigned your whole developer environment around it. In case you haven’t, let me tell you about the philosophy of buckle .

The Tao ofBuckle

buckle was designed with the belief that great command-line tools have 3 properties. They are:

memorable

discoverable

extensible

How to be Memorable

Having a single entry point to all of your commands reduces barriers to remembering what to run. In our case, all our commands start with nd . Couple this with autocomplete and pretty soon you can easily find that command you ran again without digging through your bash history, searching your wiki or pinging the whole company on slack. You don’t have strive to remember commands like git, aws or heroku, so why would you want to have to remember the name of each of your own in-house tools?

A bit about autocomplete

buckle delivers autocomplete by allowing you to create a script with the .completion.sh suffix. For example, the nd-django-command script might be coupled with an completion command called nd-dev~django-command.completion.sh . buckle will find this command in your path and feed it the autocomplete arguments, which you might then forward on to django’s autocomplete to generate results.

How to be Discoverable

buckle provides discoverability by offering a built-in help command. The help command simply calls each commands in your namespace with the “ ― help” option and summarizes the output. In our case, we just type nd help and we can see all of the available commands. The help text parser is designed around standard python argparse help but it will try its best to parse more general help messages. Discoverability is also aided by autocomplete, which will show you the list of available commands without you even having to type help .

How to be Extensible

The goal of buckle was to bring a bunch of disparate scripts together. You could achieve a unified namespace simply by renaming all your scripts, or bringing them together into a common tool using argparse subparsers or a library like click . Our feeling was that centralizing stuff wasn’t the right answer. We wanted to give developers maximum flexibility without creating large monolithic tools or even requiring an entry in a common registry of tools. The fact that buckle finds all the available commands from the path is an import piece of that decentralization effort. Since it just searches your path, you can add commands simply by installing an additional python package that inserts those commands in your path.

As you see in the nd dev createdb example, buckle also supports nested namespaces and even multiple concurrent toolbelts. The name of the script is nd-dev~createdb (we use ‘~’ as a namespace separator for commands because it seemed unlikely to be used in a real script).

It’s worth noting that your script doesn’t even need to be named nd-dev~createdb . It could still be called build-my-database or whatever you chose to call it; you would simply put a link to it in your path so that it shows up in the nd dev namespace.

Checking for shared dependencies with “dot-commands”

One additional feature of buckle, is that it has a mechanism for running shared scripts before any one of a set of toolbelt commands. Buckle calls these “dot-commands .” In our example, we might have the command nd-dev~.check-venv . This command would be run before any nd dev commands and could be used to check if you virtual environment is up-to-date before allowing you to run nd dev createdb . Often developers find out about missing dependencies too late in the process and it becomes difficult to identify what went wrong, so “dot-commands” allow you to check and update dependencies without modifying each individual tool to initiate the check itself.

Final Thoughts: UI vs Implementation Now that you understand all that buckle can do, let’s st