# 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. Buckle also attempts
to automatically update itself every hour, and also checks the system
clock every 10 minutes towarn the user if their clock is 120 seconds out
of date.


## 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 **`~`**'s. 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
<command>, create a command to generate autocomplete choices for this
named `<command>.complete[.<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.
