Install

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 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, syncs Omarchy repos, selects the Hypr host, installs and adopts config, installs stowed mise tools, 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.

Note

If stock Omarchy directories already exist at ~/.config/bootstrap, ~/.config/waybar, or ~/.config/uwsm, dot init backs them up with a .dot-init-backup-* suffix before cloning the managed repos. Hyprland and Ghostty config are stowed from the hypr/ and ghostty/ packages instead.

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, reconcile, 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. It pulls the public dotfiles, installs Bun dependencies, rebuilds and relaunches on the new binary, then scans and pulls tracked repositories. The remaining full-update phases trust mise configs, regenerate completions, install missing public packages, sync MCP configs, stow, rebuild, sync agents, backfill the init marker, and refresh resume-managed services. See the Command Reference for scoped phase flags and exit codes.