The dot Command

dot is the single binary that manages these dotfiles. It is compiled from dot/ in the repo (Bun + Effect v4 + OpenTUI) to a single executable, stowed to ~/.local/bin/dot.

It has two faces:

A TUI dashboard: run dot with no arguments to open the interactive menu, with git diff/log views, GitHub workflow runs, the notification inbox, and Omarchy menus.
A native CLI: core maintenance actions are also subcommands (dot update, dot git-diff --raw, dot doctor, …), suitable for scripts and status bars.

Command ReferenceEvery command, alias, flag, and example, generated from the CLI registry.

Stow WorkflowHow packages are stowed into your home directory.

Shell SetupZsh completions, editing keys, aliases, and small shell helpers.

System UtilitiesHealth checks, benchmarks, and optional timers.

Notes & HandoffsStandalone notes CLI, MCP server, and handoff workflow.

CleanupRemove stowed links and reverse setup side effects.

Common commands

Command	What it does
`dot dashboard`	Open the dot dashboard.
`dot init`	One-time first-use setup for a fresh machine.
`dot update`	Self-update and relaunch, pull, reconcile packages/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`	Diff / repo watcher view across managed repos.
`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.
`dot omarchy`	Open the Omarchy desktop controls menu.

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. A repository scan, pull phase, stow phase, or rebuild timeout stops the update with failure instead of continuing with a partial result.

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. If either helper does not return, the step is stopped and the completed update is not turned into a failure.

Dashboard

dot dashboard opens a full-screen dashboard. It combines tracked repo state, GitHub notifications, workflow runs, and optional bounded source commands for Twitch, environment, todo, and calendar cards. Cards are intentionally readable and always present; Enter opens an existing deeper TUI view, or suspends dot while another TUI runs, when a card has one.

Layout

Cards are grouped into four sections:

Section	Cards	Source
Overview	Events in the next hour (when configured), Updates, Live Channels	Private `calendar`/`twitch` sources; in-process repo diff state
Git	Git Diff, Git Notifications	In-process `DotDiff`, notification inbox, and workflow-run services
Todos	My Tasks, Work Tasks	Private `todo_*` sources
Environment	Temperature, CO2, VOC	Private `temperature`/`co2`/`voc` sources

The summary header at the top highlights attention signals (dirty worktrees, behind core repos, important notifications, workflow failures, environment warnings).

Keyboard

Key	Action
Arrow keys / Tab	Move between cards
Enter	Open the linked view or run the card action
`r`	Refresh all dashboard sources
Esc / Backspace	Return to the main menu

Enter actions

Card	Enter behaviour
Updates	Runs `dot update` when core repos are behind (exits the dashboard)
Git Diff	Opens the `dot git-diff` TUI
Git Notifications	Opens the `dot git-notifications` TUI (includes workflow failure counts)
Live Channels	Runs `twitch-menu channels` (suspends the dashboard)
Todo cards	Runs the configured Home Assistant todo TUI (suspends)
Environment cards	Runs `open_command` from `dot-dashboard.yml` when set (silent)

Optional source cards read from dot-dashboard.yml in the private overlay. Each source runs a one-shot --bar-json command on refresh (eight-second timeout, 60-second auto-refresh). Without that file, git and update cards still work from in-process services. See Private Dashboard Config for the schema and supported source IDs.

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.