Getting Started

Getting started with Bonnie is designed to be as painless as possible, and this page will outline the steps you'll need to perform to have a fully functional command aliasing setup in your projects!

Installation

If you have cargo (Rust's package manager), you can skip this and install Bonnie with cargo install bonnie. Then run bonnie -v to get the version you're running to make sure everything works. Otherwise, read on.

1. Go to the releases page.
2. Click on the executable file you want for your operating system (Windows, MacOS, Linux, and musl are supported by default). If the executable you want isn't there, you can clone the entire project to your local machine with git clone https://github.com/arctic-hen7/bonnie.git and run cargo build --release && mv target/release/bonnie ./bonnie (you'll need Rust installed, follow this guide for that). This will build Bonnie for your operating system and give you the executable in the root of the project. Then, continue with the steps below!
3. Once you have the executable file, move it to somewhere from which you can easily access it. On Linux, this would probably be /usr/local/bin or similar. This process should be the same as installing any other CLI tool.
4. Now check that you can run Bonnie from your terminal by running bonnie -v, which should print the version of Bonnie that you have! If it doesn't, you may need to retrace your steps!

Bonnie Configuration

Bonnie is configured in bonnie.toml on a per-folder basis. If you haven't used TOML before, it's like a more readable form of JSON or YAML designed more for humans than machines. You can read more about TOML here.

If there's already a bonnie.toml file in the directory where you run Bonnie, it will be parsed and Bonnie will expect you to provide a command to run. If you run bonnie and it tells you you need to provide a command, then there's a valid bonnie.toml in the directory! If not, you can create a new configuration file with bonnie -i. If you have a particular layout of Bonnie configuration that you regularly use, you can put it somewhere and run bonnie -t --template /path/to/your/template/file/here to use it. Note that Bonnie won't check if the template is valid, it will just blindly copy it (that way, you can have unresolved placeholders or whatever else you want).

If you want to use a file other than bonnie.toml to configure Bonnie, you can set the BONNIE_CONF environment variable to a relative or absolute path and Bonnie will try to use that instead.

Your first bonnie.toml

1. Create a new configuration with bonnie -i in some folder.
2. Paste the following code in, ignoring what's already in there.

version = "0.3.2"

[scripts]
test = "echo Test"
foobar = "echo \"Foo and Bar\""

Now try running bonnie test in the same folder. You should see Test printed to the console!

Let's break down what we've just set up. First, we define the version of Bonnie that this file is configured for with the top-level version key. This is mandatory in all Bonnie files after v0.2.0, and it helps to ensure compatibility between configuration files and the different versions of Bonnie people may have on their computers.

Then, we define [scripts]. This is called a table in TOML, which is very similar to an object in JSON. This is also mandatory in all Bonnie files. Then, we define two scripts, test and foobar. They both use the simplest Bonnie syntax possible, just key-value definition. They map an alias to a longer command, in this case test to echo Test. This may not seem too useful yet, but it becomes incredibly powerful when you've got build commands like cargo watch -w ../../../ -x "run --example test" that you're running very often! With Bonnie, you could alias that as example-test and run bonnie example-test to execute that command!

Onward!

This key-value syntax is the easiest way to use Bonnie, and if you just want this, then you've learned how to use Bonnie! However, Bonnie also supports some extremely powerful syntax that can allow you to nest subcommands, interpolate environment variables, and execute commands in a variable order automatically. Keep reading to learn more! From the next document, every page deals with a specific feature of Bonnie, and there'll be a code example at the top with a full explanation thereof and an in-depth discussion of the feature! Enjoy!