Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Bootstrap flow

Step-by-step diagram of what bootstrap.sh actually does, with the DF_DO_* skip flag for each phase. Steps run in order — failures in any phase abort the rest (except VS Code/Cursor extension installs and a few other clearly-flagged log-warn-but-continue cases).

flowchart TD
    A[curl bootstrap.sh] --> S0["0  scratch links<br/>DF_DO_SCRATCH"]
    S0 --> S01["0.1  ~/dev ~/bones ~/misc<br/>DF_DO_DIRS"]
    S01 --> S05["0.5  clone repo to ~/dotfiles"]
    S05 --> S03["0.3  detect PLAT capability<br/>(always; tunes compiler flags)"]
    S03 --> S1["1  install chezmoi binary<br/>(idempotent)"]
    S1 --> S2["2  chezmoi init --apply --force<br/>(renders home/*.tmpl into ~/)"]
    S2 --> S27["2.7  PATH sanity check<br/>(verifies ARCH_BIN writable, no broken symlinks)"]
    S27 --> S3["3  oh-my-zsh + plugins<br/>DF_DO_ZSH"]
    S3 --> S4["4  Homebrew + Brewfile<br/>DF_DO_PACKAGES"]
    S4 -.macOS.-> S5["5  Colima service<br/>DF_DO_MACOS_SERVICES"]
    S5 -.macOS.-> S55["5.5  defaults write<br/>DF_DO_MACOS_SETTINGS"]
    S55 -.macOS.-> S56["5.6  Quick Actions<br/>DF_DO_MACOS_QUICK_ACTIONS"]
    S4 --> S6
    S56 --> S6
    subgraph S6["6  language runtimes  (each independent)"]
        N["node.sh<br/>DF_DO_NODE"]
        R["rust.sh<br/>DF_DO_RUST"]
        P["python.sh<br/>DF_DO_PYTHON"]
        C["claude.sh<br/>DF_DO_CLAUDE"]
        X["codex.sh<br/>DF_DO_CODEX"]
        V["cursor/vscode.sh<br/>DF_DO_CURSOR / DF_DO_VSCODE"]
        K["cmake.sh<br/>DF_DO_CMAKE"]
    end
    S6 --> S65["6.5  local LLM<br/>DF_DO_LOCAL_LLM"]
    S65 --> S66["6.6  agent memory stack<br/>DF_DO_MEMORY"]
    S66 --> S67["6.7  blender-mcp addon<br/>DF_DO_BLENDER_MCP"]
    S66 --> S7["7  auth.sh walk<br/>DF_DO_AUTH (default 0)"]
    S7 --> S8["8  overlay bootstraps<br/>DF_DO_OVERLAYS"]

Step details

StepScriptWhatIdempotent?
0install/scratch.shSymlink heavy $HOME dirs to $DF_SCRATCH/.paths/. No-op if DF_SCRATCH unset.Yes
0.1install/dirs.shCreate ~/dev, ~/bones, ~/misc (or $DF_DIRS).Yes
0.5inlinegit clone if first run; git pull --ff-only in update/upgrade modes.Yes
0.3inlineRe-detect PLAT against the just-cloned repo’s install/plat/ dir. Upgrades the PLAT value if a higher CPU level matches now (e.g. v3 → v4).Yes
1install/chezmoi.shDownload chezmoi to $ARCH_BIN/chezmoi. Skipped if file already executable.Yes
2(inline)chezmoi init --apply --force --exclude=scripts. Renders home/*.tmpl into ~/. --exclude=scripts skips run_onchange_*.sh.tmpl (bootstrap calls install scripts directly).Yes
2.7inlineSanity-check that $ARCH_BIN, $CARGO_HOME, $RUSTUP_HOME, $NVM_DIR parents exist and aren’t broken symlinks. Aborts if anything’s wrong.Yes
3install/zsh.shClone or update oh-my-zsh + plugins.Yes
4install/homebrew.sh (macOS) or install/linux-packages.shInstall Homebrew, run brew bundle install --file=Brewfile, optionally brew upgrade and brew upgrade --cask --greedy.Yes
5install/macos-services.shRegister Colima as a launchd service; symlink Docker plugins. macOS only.Yes
5.5install/macos-settings.shdefaults write for Dock, Finder, keyboard, trackpad, Safari, iTerm2, screen lock. Power management requires sudo (silently skipped if cache expired).Yes
5.6install/macos-quick-actions.shDeploy *.workflow bundles to ~/Library/Services/; flush pbs.Yes
6variousSee language-runtime table below. Each script is independent; failures cascade only via die (not log_warn).Yes
6.5install/local-llm.sh + install/opencode.shCreate $LOCAL_PLAT/.cache/huggingface; verify ollama/mlx-lm/mlx-openai-server/opencode binaries.Yes
6.6install/memory.shAgent memory stack: cass binary (checksum-verified GitHub release) + session-history index, ~/kb knowledge repo, qmd collections/embeddings, memory daemons.Yes
6.7install/blender-mcp.shDownload addon.py into Blender’s user addons; enable headlessly. Skipped if Blender not installed.Yes
7install/auth.shWalk every service, prompt [k]eep / [u]pdate / [d]elete per service. Default off — set DF_DO_AUTH=1 to enable.Yes
8overlay scriptsRun bash $DF_ROOT/dotfiles-*/bootstrap.sh "$DF_MODE" for each overlay.Per overlay

Step 6 in detail

Sub-stepScriptWhatNotes
6ainstall/node.shInstall nvm to $NVM_DIR; install/upgrade Node v25; install npm.txt packages globally.Lazy-loaded in interactive shells.
6binstall/rust.shInstall rustup (Homebrew on macOS, sh.rustup.rs on Linux); install/update stable toolchain; cargo binstall every entry in cargo.txt.rustup self-update is --no-self-update except in upgrade mode.
6cinstall/python.shInstall uv to $ARCH_BIN; uv tool install every entry in pip.txt (each gets isolated venv).# macos-only and # python=X.Y markers parsed from comments.
6dinstall/claude.shDownload Claude Code binary to $ARCH_BIN/claude if version differs; install plugins; register MCP servers (with auth=gh resolution); deploy overlay skills.Atomic write via temp file + mv -f.
6einstall/codex.sh upgradeSync managed Codex config (config.toml, hooks.json, df-chezmoi-guard) + healthcheck (binary comes from the pinned @openai/codex in npm.txt).Healthcheck dies on config drift.
6finstall/cursor.shSymlink Cursor settings; install extensions from cursor-extensions.txt.Extension failures are warnings, not fatal.
6ginstall/vscode.shInstall extensions from vscode-extensions.txt.Same warning-not-fatal pattern.
6hinstall/cmake.shCopy toolchain files (llvm-21/22.cmake, gcc-13/15.cmake, _brew.cmake) from repo to $LOCAL_PLAT/cmake/toolchains/.Always overwrites — keeps deployed copies in sync with repo.

Modes

ModeWhat changes
install (default)Full idempotent setup. DF_DO_SCRATCH=1 (run scratch step).
updateSame steps, but: git pull --ff-only in step 0.5, DF_DO_SCRATCH=0 (assume scratch is already set up), tools self-update where they support it.
upgradeSame as update, plus: DF_BREW_UPGRADE=1 (greedy cask refresh), rustup self-update, nvm install 25 --reinstall-packages-from=25 --latest-npm, npm install -g <pkg>@latest per package, uv self update + uv tool upgrade --all, oh-my-zsh git pull, VS Code/Cursor extension --force reinstall. Claude Code and Codex CLI always re-download to latest regardless of mode.

Reading the source

The canonical source is bootstrap.sh itself — header comment block has the full flag table, then numbered ### N. ### step markers. To trace what a single step actually does, jump to install/<step>.sh. Each install script sources _lib.sh for path variables and logging helpers.