The dot Command

The TUI dashboard and CLI that drives the dotfiles system.

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, 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 Reference

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

Stow Workflow

How packages are stowed into your home directory.

Shell Setup

Zsh completions, editing keys, aliases, and small shell helpers.

System Utilities

Health checks, benchmarks, and optional timers.

Notes & Handoffs

Standalone notes CLI, MCP server, and handoff workflow.

Cleanup

Remove 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, 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`	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.

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.

Dashboard

dot dashboard opens a full-screen dashboard. It combines tracked repo state, GitHub notifications, 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` and notification inbox 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, 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
Live Channels	Exits the dashboard and opens the `timmo.twitch` shell panel
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.