Install

Prerequisites, bootstrap build, and the ongoing dotfiles workflow.

Prerequisites

On a fresh Omarchy machine, install the bootstrap build prerequisites (git and mise):

yay -S --needed git mise-bin

If you want the private dotfiles overlay, authenticate gh (the GitHub CLI) before dot init so it can clone dotfiles-private automatically:

gh auth status || gh auth login

Clone and build

Clone the public dotfiles first, then build the dot binary before it is on your PATH. Trust and install the pinned toolchain with mise, then run the build task (it installs dependencies first, and mise run provides Bun without needing shell activation yet):

git clone --recurse-submodules git@github.com:timmo001/dotfiles.git ~/.config/dotfiles

cd ~/.config/dotfiles
mise trust
mise install
mise run dot:build

First-use setup

dot init runs the one-time first-use setup: it bootstraps private dotfiles when allowed, selects the Hypr host, installs and adopts config, installs stowed mise tools, verifies and registers the signed timmo package repository, sets up packages and machine hooks, and syncs agents. It logs to ~/.local/state/dot/init.log by default. The private-overlay pull or clone runs first as an unbounded preflight; the setup phases that follow use the same spinner and timeout handling as dot update.

~/.config/dotfiles/scripts/.local/bin/dot init --noninteractive

For a laptop, select the laptop host:

dot init --host laptop --noninteractive

Or run dot init in an interactive shell to be prompted.

--noninteractive skips only the Hypr host questionnaire; elevation and package tools may still prompt. --confirm remains accepted for compatibility but does not suppress prompts. Private overlay preflight is controlled by DOT_ALLOW_PRIVATE: auto skips without GitHub authentication and tolerates an existing-overlay pull failure, but a failed attempted clone is fatal; always requires the overlay to update or clone successfully; never skips it.

Ongoing workflow

After init completes, restart your shell so dot is on PATH, then reboot so the Omarchy session picks up OMARCHY_HOST. Run doctor after the reboot to verify the setup, and use update for ongoing maintenance:

dot doctor    # health checks
dot update    # self-update and relaunch, then pull, stow, and rebuild
dot git-diff  # review changes across managed repos
context git   # branch context for the current repo (from the context-git package)

context git and context stack come from the context-git AUR package installed during init. They are used by OpenCode plugins and agent harnesses for repository context; see Context Integration.

dot update is the everyday command and works from an ordinary shell or a Herdr pane. It pulls the public dotfiles, installs Bun dependencies, rebuilds and relaunches on the new binary, then scans and pulls tracked repositories. Every pull phase also restores recursive submodules to the exact revisions committed by the public dotfiles repository, including Renovate-managed plugin pins, even when no repository needs pulling. The remaining full-update phases trust mise configs, regenerate completions, sync MCP configs, stow the committed skills snapshot, rebuild, sync agents, backfill the init marker, and refresh resume-managed services. Inside Herdr, it also installs Herdr Lazy when needed, restores the declared plugins from its lockfile, links local plugins, and starts the title watcher. Outside Herdr, it skips that session-bound phase. It never fetches mutable upstream skill content. Package setup stays in dot init, while dot doctor reports package health. See the Command Reference for scoped phase flags and exit codes.