--- title: The dot Command description: The TUI dashboard and CLI that drives the dotfiles system. sidebar: label: Overview order: 1 --- `dot` is the single binary that manages these dotfiles. It is compiled from `dot/` in the repo ([Bun](https://bun.sh) + [Effect](https://effect.website) v4 + [OpenTUI](https://github.com/anomalyco/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. Every command, alias, flag, and example, generated from the CLI registry. How packages are stowed into your home directory. Zsh completions, editing keys, aliases, and small shell helpers. Health checks, benchmarks, and optional timers. Standalone notes CLI, MCP server, and handoff workflow. 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`](https://context.timmo.dev). | | `context stack` | Tech-stack context for a directory (agent context), provided by [`context`](https://context.timmo.dev). | | `dot git-commit` | Guarded commit gateway for scoped, styled commits. | | `dot omarchy` | Open the Omarchy desktop controls menu. | See the full [Command Reference](/dot/commands/) 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](/configuration/private-git/) 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](/configuration/private-dashboard/) 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](/dot/commands/) all read from that one registry. When a command changes, regenerate the reference page and shell completions from `spec.ts`.