The dot Command
The CLI that drives the dotfiles system.
dot is the single CLI that manages these dotfiles. It is compiled from dot/ in the repo (Bun + Effect v4) to a single executable, stowed to ~/.local/bin/dot.
Run dot without arguments to print root help. Maintenance actions are native subcommands (dot update, dot git-diff, dot doctor, …), suitable for interactive use, scripts, and status bars.
Command Reference
Stow Workflow
Shell Setup
System Utilities
Notes & Handoffs
Cleanup
Common commands
| Command | What it does |
|---|---|
dot init |
One-time first-use setup for a fresh machine. |
dot update |
Self-update and relaunch, pull, refresh config, stow, and rebuild. |
dot stow |
Stow refresh only (no git pull). |
dot doctor |
Run dotfiles system health checks. |
dot firewall |
Reconcile managed ufw firewall rules. |
dot git-diff |
Print change state across managed repositories. |
context git |
Branch context for the current repo (agent context), provided by context. |
context stack |
Tech-stack context for a directory (agent context), provided by context. |
dot git-commit |
Guarded commit gateway for scoped, styled commits. |
See the full Command Reference for every subcommand and flag.
Progress and timeouts
Long-running Effect-managed CLI workflows use the same progress wrapper: an interactive spinner, elapsed duration logging, and a timeout that interrupts the running child process group. This covers the main first-use setup phases (dot init), updates, doctor checks, skill update checks/applies/diffs, stow/install/clean, private package publishing, and other bounded maintenance commands.
dot update keeps each phase bounded so a slow remote, stuck hook, or helper process cannot leave the update sitting silently. Individual repository pulls are retried once and skipped after repeated failure or timeout. Every pull phase restores recursive submodules to their committed revisions, including Renovate-managed plugin pins, even when no repository is behind. When a managed repository’s pull moves HEAD, any configured post_update command in Private Git Config runs from that repository root before the update continues; a failure or five-minute timeout stops the update. Full updates run from ordinary shells as well as Herdr panes. Inside Herdr they install Herdr Lazy when it is missing, run herdr-lazy restore after stow and rebuild, link local plugins, and start the title watcher; outside Herdr they skip that session-bound phase. A repository scan, pull phase, stow phase, rebuild, or configured Herdr plugin restore timeout stops the update with failure instead of continuing with a partial result. Successful full and scoped updates finish with a summary of repositories updated and actions completed.
dot init uses the spinner and timeout wrapper for each required setup phase. Its private-overlay pull or clone is a synchronous preflight before that bounded workflow and before the already-initialised check. If a required init phase times out, init stops instead of writing the complete marker. dot doctor keeps its live “running checks” spinner and also times out individual checks, reporting timed-out checks as warnings.
Post-hooks and the final resume refresh are bounded but non-fatal. The refresh restarts status-bar services without auto-opening Twitch streams. If either helper does not return, the step is stopped and the completed update is not turned into a failure.
Source of truth
Command and flag metadata lives in dot/src/cli/spec.ts. Help rendering, shell completions, and the generated Command Reference all read from that one registry. When a command changes, regenerate the reference page and shell completions from spec.ts.