buckle

Buckle is a tool for centralizing and executing developer commands in your path. It's goal is to make it easy to create a toolbelt from disparate commands that all begin with the same prefix. It finds and autocompletes commands beginning with a prefix (such as nd-), and supports help for commands within its namespaces.

An Example

It's easiest to understand this tool with an example. Here’s a simple bash session where we create a toolbelt called ‘sash’ with an ‘echo’ command:

> export PATH=$(pwd):$PATH
> pip install buckle
> alias sash="BUCKLE_TOOLBELT_NAME=sash buckle"
> ln -s $(which echo) sash-echo
> 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 $*

Developer Setup

Run make init to install the tools you need.

Installation

Clone the repo and then run pip install -e <repo>. By cloning it, buckle will auto-update.

To set up autocomplete for a toolbelt called nd, run eval "$(buckle init nd)".

Usage

Run commands with nd <command>. Run nd help to see a list of available commands. Autocomplete and discover commands by trying standard auto completion within the nd namespace.

Creating Toolbelt Commands

Adding a command to buckle is as simple as including it to your path.

Your toolbelt command must start with <toolbelt name>-, such as nd- if your toolbelt is called nd. The following rules also apply:

Namespaces must be separated by ~. e.g.: nd dev migrate should be named nd-dev~migrate
Commands starting with _ aren't shown in autocomplete options.
Commands starting with . are run before every command in its namespace and child namespaces. e.g.: nd-dev~.check. Dot commands are run alphabetically. If a dot command fails to execute successfully, no further dot commands nor the target command will be executed.

Bash Completion

To enable bash completion for the arguments for a command named , create a command to generate autocomplete choices for this named <command>.completion[.<suffix>]. This command is passed the standard bash completion environment variables, COMP_WORDS and COMP_CWORD. If the script ends with a .sh or .bash suffix it will be sourced rather than executed, which is faster and gives it access to the full bash environment without having to rerun the user's login scripts. Autocomplete choices can also be generated by a per-namespace script named nd-<namespace>.completion[.<suffix>]. This script is passed exactly the same values of COMP_WORDS and COMP_CWORD that would be passed to a per-command autocomplete script.

Additional Features

Buckle can also attemps to automatically update itself at regular intervals. It can also checks the system clock every 10 minutes to warn the user if their clock is 120 seconds out of date.

stemarco/buckle