Commands

Commands

homebot --help prints the same list. homebot <command> --help (or homebot help <command>) prints that command’s own page: what it does, its options and examples. Each homebot persona subcommand has a page of its own (homebot persona use --help, homebot help persona use). --help never runs the command, whatever else is on the line. Every command that changes something refreshes the inbox afterwards.

homebot unpack runs every step without asking; homebot unpack --dry-run lists them first.

Use homebot persona to list voices and choose or write one. Personas change eligible terminal messages, while stored text and commands keep their original wording.

Use homebot name [word] to show or set this home’s optional command name, and homebot name --off to remove it. homebot always remains available. See Naming your homebot for PATH, conflicts and removal.

Global options

--plain makes homebot speak in its neutral voice for one run, with no persona; HOMEBOT_PLAIN=1 does it for every run. It goes before the command (homebot --plain save) or among the options of a command that takes options (homebot save --plain). next, keys, triage, inventory, export, actions, action and shell take the words after their name as typed, so there --plain goes before the command’s name. homebot help takes it on either side of the command’s name (homebot help --plain link). homebot --help does not list it.

Attention

Moving in

Secrets

Keeping order

Triage keys

homebot triage shows each new thing in ~/.config/* and ~/.* once:

Backing up: homebot remote

Without a remote, nothing leaves the machine, and the inbox says “Not backed up”. homebot remote sets one up:

• g: create a private GitHub repository with gh; l: the same on GitLab with glab. Only offered when that tool is installed and logged in; when it is installed but not logged in, it says to run gh auth login first. It asks for a name (the repo folder’s, home for ~/.home, by default).
• u: paste the URL of a repository you already have.
• Enter: not now.

A new repository’s ssh address is used when ~/.ssh has a key, else its https address (then gh auth setup-git lets git use gh’s login). Then it pushes.

With a remote already set, it checks that git can reach it and pushes what isn’t there yet. When an https remote fails because nobody is logged in and there is an ssh key, it offers the ssh address of the same repository. homebot remote <url> makes that URL the remote. Without a terminal it only explains.

The inbox shows “Not backed up yet” while a remote has never received a push, which is also how a remote git can’t log in to shows up.

Where the repo is found

$HOMEBOT_ROOT → the current directory (walking up to a homebot.yml) → the binary’s location → ~/.home.

Generated command details

The sections below come from the same command tree and help catalog used by the binary. Regenerate them with go run ./tools/gendocs docs.

inbox

Usage: homebot [--all]

Lists what needs you, most urgent first, each with the command that fixes it,
and what the background helper did since you last looked. homebot inbox is
the same command.

next

Usage: homebot next

Runs the fix for the first inbox item, the command shown next to it. When the
fix is a shell command homebot shouldn't run for you, it prints it instead.

unpack

Usage: homebot unpack [profile]

Runs a profile's steps in order, without asking first: package installs
(brew, apt, flatpak…), links, secrets and run: commands. Each step is
printed as it starts. Without a name it uses this machine's profile from
homebot.yml (profiles.hosts, else profiles.default).

Preview the steps with --dry-run. A step that fails stops the run and prints
the --from that resumes after you fix it. Steps that are already done (a
package that is installed, a link that exists) do nothing the second time.

pack

Usage: homebot pack <path>...

Moves a file or folder from $HOME into the repo and puts a link in its place,
so it is tracked from then on. It goes to autolink/common unless --layer says
otherwise. With --private it is sealed under private/ (encrypted with age)
instead. Commit it with homebot save.

link

Usage: homebot link

Links everything under autolink/ (and unlocked secrets under private/) into
$HOME. It never overwrites anything: what is in the way is listed as blocked.
A file identical to the repo's copy is replaced by the link, since nothing is
lost.

–backup moves the blockers aside first, renamed <name>.homebot-backup-<time>,
and then links. homebot cleanup goes through those backups later.

unlink

Usage: homebot unlink

Removes every link homebot made. The files stay in the repo, so the links
come back with the next homebot link, and within the hour from the background
helper (homebot tidy). To keep a file unlinked, take it out of the repo.

cleanup

Usage: homebot cleanup

Goes through the backups homebot link --backup left
(<name>.homebot-backup-<time>) one at a time. Each shows how it differs from
what is linked there now (beside the choices, when fzf is installed), and you
pick:

delete remove the backup; what is linked there now stays
keep leave it; homebot asks again next time
use copy the backup over the repo file, then remove it
merge take some of the backup's lines into the repo file

merge opens lazygit when it is installed. The backup's lines are the green
ones: space takes the line under the cursor, shift+arrows select several, d
drops them, q finishes. Without lazygit it is git add -p: y takes a block, n
skips it, s splits it smaller, e edits it. What you took is written to the
repo file, and the same backup comes back with what is left, so you can
delete it.

keys

Usage: homebot keys init

Creates the age key pair that seals private/. It asks for a passphrase, then
writes private/identity.age (the key, encrypted with that passphrase) and
private/recipients.txt (the public key). Run it once ever; other machines get
the key with the repo and run homebot unlock.

unlock

Usage: homebot unlock

Decrypts the secrets in private/ and links them into $HOME. A secret that
changed both here and in the repo is left alone and listed as a conflict.

lock

Usage: homebot lock

Seals the secrets in private/ that changed since they were last sealed. The
background helper does this on its own before each autosave.

triage

Usage: homebot triage

Asks once about each new thing in the watched folders (~/.config/, ~/.) and
each untracked file in the repo. Each answer is saved right away:

t track it everywhere (moves it into autolink/common, links it back)
o track it on this OS only
i ignore it for good (written to decisions.yml)
s snooze it for 7 days (this machine only)
enter next
q stop

inventory

Usage: homebot inventory

One screen: this machine's profile and whether it changed since the last
unpack, links, secrets, things to triage, the repo and its remote, package
exports and the background helper.

remote

Usage: homebot remote [url]

Without a remote, offers to create a private repository with gh (GitHub) or
glab (GitLab), when one is installed and logged in, or takes a URL you paste.
Then it pushes. With a URL, makes that the remote (origin).

With a remote already set, checks that it can be reached. When an https
remote fails for lack of a login and you have an ssh key, it offers the ssh
address of the same repository.

save

Usage: homebot save

Seals changed secrets, commits the changes to tracked files and package
snapshots, then pulls (rebasing local commits) and pushes. New files aren't
committed: triage decides about them first. The background helper does the
same on its own (autosave in homebot.yml).

export

Usage: homebot export [name...]

Writes what is installed (Brewfile, apt and flatpak lists, vendor apt
repositories…) into manifests/, as configured under exports in homebot.yml.
Without names it runs every export for this OS. The background helper runs
them about once a day.

tidy

Usage: homebot tidy

Runs what the background helper runs on its timer: installs the commit guard
if it's missing, seals secrets, refreshes package exports that are due,
autosaves and syncs (when homebot.yml turns autosave on), fixes links that
are safe to fix, and refreshes the inbox.

setup

Usage: homebot setup

Takes you from nothing to an empty inbox, one question at a time. It checks
for git and gitleaks, clones your home repo or starts a new one in ~/.home,
installs the commit guard and the background helper (a systemd user timer on
Linux, a launchd agent on macOS), and offers to load the shell integration,
back the repo up and commit. Steps already done are skipped, so running it
again is safe. Without a terminal it asks nothing, creates no repo, and says
what is left.

actions

Usage: homebot actions

Lists the actions profile steps can use: the built-in ones (link, unlock,
run) and the scripts in homebot/actions/.

action

Usage: homebot action <name> [args...]

Runs one action with the environment a profile step gets. Everything after
the name goes to the action, so homebot action <name> --help reaches the
action; this page is homebot action --help.

shell

Usage: homebot shell zsh

Prints the zsh integration: the prompt line that says when something needs
you, refreshed in the background. Load it from .zshrc:

eval "$(homebot shell zsh)"

name

Usage: homebot name [word]

Shows the name in homebot.yml and the name that works here. Give a word
to make it a command on this machine, or use --off to remove a link homebot
made. A name may need a new shell before it works.

persona

Usage: homebot persona [command]

List, inspect, create, and choose the voice homebot speaks in.

version

Usage: homebot version

Prints the version of this homebot. homebot --version and homebot -v
print the same.