The bothy command
bothy is the half of Bothy you can have before you have a checkout. It
installs one, and after that it is a dispatcher: a small shell script that finds
your checkout and hands most of what you type to that checkout's justfile.
Knowing which half you are in matters, because it is the difference between a command that works anywhere and one that needs to find a box first.
Two kinds of subcommand#
Native. Implemented in scripts/bothy itself, and the reason the script
exists at all.
| Command | What it does |
|---|---|
bothy init [dir] |
check prerequisites, clone, install just, record where the checkout is, and bring it up. Default directory is ~/bothy. |
bothy download |
pre-fetch every image and dependency, so a later up needs no network |
bothy upgrade |
move to the newest green release and apply it, preserving your data (through the host updater when it is installed) |
bothy self-update |
replace the bothy on your PATH with the checkout's copy |
bothy version |
what this checkout is - version, commit, whether it is modified, and where it lives |
bothy doctor --pre |
check prerequisites before a checkout exists |
bothy help |
the usage text |
Dispatched. Everything else is handed straight to just inside your
checkout. bothy up is just up run in the right directory:
up down doctor verify backup logs <svc> ps urls psql
files-check portability bootstrap nukeThree of these have friendlier names, and both spellings work:
| You type | It runs |
|---|---|
bothy status |
just ps |
bothy diagnostics |
just doctor |
bothy check |
just verify |
Anything not in either list is refused by name, with the usage text - a dispatcher that passed unknown words through would be a way to run arbitrary recipes by typo.
How it finds your checkout#
Every dispatched command has to cd somewhere first. Three sources, in order,
and the first one that names a real Bothy checkout wins:
$BOTHY_HOME, an explicit override. This is the one to set for a second checkout, or in CI. If it is set and is not a Bothy checkout, the command fails there rather than falling through - an override that is silently ignored is worse than one that stops.- The path recorded by
init, in~/.config/bothy/config(or$XDG_CONFIG_HOME/bothy/config). One line:BOTHY_HOME=/path/to/checkout. - Walking up from the current directory. Standing anywhere inside a
checkout,
bothyfinds it.
With none of the three, the command stops and says to run bothy init or set
BOTHY_HOME. It does not guess.
What init actually does#
In order, and it stops at the first thing it cannot do:
- Prerequisites.
docker,git,curl,python3,openssl, anddocker composeas a working subcommand. Missing ones are listed by name. - Clone, unless the directory is already a Bothy checkout - in which case it is reused. A directory that exists, is not empty, and is not a checkout is refused rather than written into.
just, if it is not already there, into~/.local/binvia its official installer, pinned to that directory rather than run as root. If~/.local/binis not on yourPATH,initsays so; nothing later will.- Record the path in the config file above.
.envand secrets, then bring the stack up.
bothy doctor --pre is step 1 on its own, and it is the only subcommand that
works with no checkout anywhere - which is the point of it. Run it before you
clone anything.
upgrade and self-update are different things#
This is the single most confusing thing about the CLI and it is worth being blunt about:
bothy upgradeupdates the box. With the host updater installed it runs the same plan and executor as Settings > Updates (a green release tag, built first, rolled back on failure); without it, it pulls the checkout and re-applies it. Upgrading has both.bothy self-updateupdates this script. It copiesscripts/bothyfrom the checkout over thebothyon yourPATH.
They are separate because the bothy you run is a copy. The installer puts
scripts/bothy into ~/.local/bin/bothy; upgrade pulls the repository. So
after an upgrade the checkout has a new CLI and the one you are running is
whatever was current the day you installed - which matters for a dispatcher,
because it resolves subcommands against a justfile it may no longer match.
self-update overwrites the file this process was started from, resolved
through symlinks, rather than an assumed ~/.local/bin/bothy: overwriting a
path you did not choose is worse than refusing. If you are already running the
checkout's copy it says so and does nothing.
See Upgrading for what upgrade does to your data.
Reading bothy version#
bothy versionprints the version, the short commit, whether the working tree is modified, and
the checkout path. The (modified) marker is the useful one: it is what
distinguishes two boxes claiming the same version, and the first thing to check
when a box behaves unlike its version number says it should.
When to use just instead#
Nothing about bothy is required. Inside a checkout, just up and bothy up
are the same command, and just --list shows every recipe including the ones
the dispatch table does not name. The CLI earns its place in exactly two
situations: before the checkout exists, and when you are not standing in it.
Next#
- Upgrading - what
upgradetouches, and what it deliberately does not - Installing Bothy - the longer version of
init, and the manual path