DRAFT docs: how to build and test locally

src/content/docs/how-to/local.mdx

@@ -1,12 +1,104 @@
 ---
 title: How to build and test locally
-description: A guide in my new Starlight docs site.
+description: This guide shows you how to use the Bluebuild CLI tool to test images in your local development environment before pushing them to GitHub.
 ---
 
+[bluebuild-repo]: https://github.com/blue-build/cli
+[bluebuild-readme-howtouse]: https://github.com/blue-build/cli?tab=readme-ov-file#how-to-use
+[install-via-distrobox]: https://github.com/blue-build/cli?tab=readme-ov-file#distrobox
+[install-via-cargo]: https://github.com/blue-build/cli?tab=readme-ov-file#cargo
+[install-via-podman]: https://github.com/blue-build/cli?tab=readme-ov-file#podmandocker
+[install-via-nixflake]: https://github.com/blue-build/cli?tab=readme-ov-file#nix-flake
+[install-via-posix]: https://github.com/blue-build/cli?tab=readme-ov-file#github-install-script
+[distrobox-export-documentation]: https://distrobox.it/usage/distrobox-export/
+
 :::caution
 This page is a draft, so contents are unfinished or nonexistent.
 :::
 
-https://diataxis.fr/how-to-guides/
+If you want to determine whether your image customizations work before before pushing them to GitHub and waiting for the corresponding GitHub Action, you should test your images on your local development environment before committing your changes.
+
+This guide shows you how to use the [Bluebuild CLI tool][bluebuild-repo] to build images in your local development environment.
+
+## Prerequisites
+
+TODO or TO REMOVE
+
+## Installing BlueBuild CLI
+
+There are several methods available for installing the BlueBuild CLI tool:
+
+- [distrobox][install-via-distrobox]
+- [cargo][install-via-cargo]
+- [podman][install-via-podman]
+- [nixflake][install-via-nixflake]
+- [POSIX shell script][install-via-posix]
+
+### Distrobox
+
+If you installed BlueBuild CLI in a distrobox, the bluebuild command set will not be visible to your host machine by default. You will need to **enter** the distrobox, and either run the commands from inside the distrobox, or **export** the distrobox commands for use outside the distrobox.
+
+Refer to the [distrobox documentation][distrobox-export-documentation] for more information.
+
+#### Running commands from within distrobox
+
+```bash
+[user@host]$ distrobox enter blue-build
+[user@blue-build]$ bluebuild build ./config/recipe.yaml
+```
+
+#### Exporting commands to run outside distrobox
+
+```bash
+[user@blue-build]$ distrobox-export --bin $(which bluebuild)
+[user@blue-build]$ exit
+[user@host]$ bluebuild build ./config/recipe.yaml
+```
+
+The above method will also automatically use any [completions][#completions] you have configured.
+
+## Using BlueBuild CLI
+
+The [repository README][bluebuild-readme-howtouse] has general instructions for using the `bluebuild` CLI tool.
+
+There is also a `help` command:
+
+```bash
+$ bluebuild help
+A CLI tool built for creating Containerfile templates based on the Ublue Community Project
+
+Usage: bluebuild [OPTIONS] <COMMAND>
+
+Commands:
+  build        Build an image from a recipe
+  template     Generate a Containerfile from a recipe
+  upgrade      Upgrade your current OS with the local image saved at `/etc/bluebuild/` [aliases: update]
+  rebase       Rebase your current OS onto the image being built
+  bug-report   Create a pre-populated GitHub issue with information about your configuration
+  completions  Generate shell completions for your shell to stdout
+  help         Print this message or the help of the given subcommand(s)
+
+Options:
+  -v, --verbose...  Increase logging verbosity
+  -q, --quiet...    Decrease logging verbosity
+  -h, --help        Print help
+  -V, --version     Print version
+```
+
+Example use cases for some of the commands follow in the sections below.
+
+### Completions
+
+Terminal autocompletions depend on the shell environment. For Bash:
+
+```bash
+$ bluebuild completions > ~/.local/share/bash-completion/bluebuild
+```
+
+### Build
+
+To complete:
 
--   `bb build --rebase` (or whatever the correct command is)
+```bash
+bluebuild build ./config/recipe.yaml
+```