---
title: Install
description: Prerequisites, bootstrap build, and the ongoing dotfiles workflow.
sidebar:
  order: 2
---

## Prerequisites

On a fresh [Omarchy](https://omarchy.org) machine, install the bootstrap build prerequisites ([git](https://git-scm.com) and [mise](https://mise.jdx.dev)):

```bash
yay -S --needed git mise-bin
```

If you want the private dotfiles overlay, authenticate [`gh`](https://cli.github.com) (the GitHub CLI) before `dot init` so it can clone `dotfiles-private` automatically:

```bash
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):

```bash
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`.

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

For a laptop, select the laptop host:

```bash
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
UWSM, Hyprland, and Ghostty customisations are stowed from the `uwsm/`, `hypr/`, and `ghostty/` packages. If the retired `timmo001/omarchy-uwsm` checkout is present, init removes it before linking the Quattro-compatible environment override.
:::

## 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:

```bash
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](/git/context/).

`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](/dot/commands/) for scoped phase flags and exit codes.