Setup

One page. Copy the commands. Restore the state. Stop.

This is the main rebuild guide. It replaces most of the smaller pages. The only separate pages still worth keeping are the full Homebrew catalog, factory reset steps, and search.

Table of Contents

Install Homebrew

Run this once on a fresh Mac.

Homebrew installer

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install the Default Workstation

This is the default path.

Formulae

brew install bash wget vim uv tig htop tree tmux jq ncurses gh go pandoc jira-cli volta ffmpeg

Casks

brew install --cask iterm2 orbstack google-chrome google-chrome@canary vivaldi duckduckgo visual-studio-code github codex claude antigravity keyboard-maestro rectangle-pro karabiner-elements betterdisplay obsidian logseq mailmate@beta keepassxc spotify slack discord microsoft-edge microsoft-office microsoft-teams onedrive microsoft-outlook microsoft-remote-desktop skim adobe-acrobat-reader pdf-expert shottr kap

Optional Variants

Only use these if the default workstation is too small or too large.

Minimal

Enough to browse, code, and get back into the repo quickly.

brew install bash wget vim uv tig htop tree tmux jq ncurses gh
brew install --cask iterm2 google-chrome google-chrome@canary vivaldi duckduckgo visual-studio-code github codex claude antigravity keyboard-maestro rectangle-pro karabiner-elements betterdisplay obsidian logseq mailmate@beta keepassxc spotify slack discord

Full

Workstation plus the network and support tools.

brew install bash wget vim uv tig htop tree tmux jq ncurses gh go pandoc jira-cli volta ffmpeg telnet rclone ipmitool openssl lftp mtr nmap net-snmp
brew install --cask iterm2 orbstack google-chrome google-chrome@canary vivaldi duckduckgo visual-studio-code github codex claude antigravity keyboard-maestro rectangle-pro karabiner-elements betterdisplay obsidian logseq mailmate@beta keepassxc spotify slack discord microsoft-edge microsoft-office microsoft-teams onedrive microsoft-outlook microsoft-remote-desktop skim adobe-acrobat-reader pdf-expert shottr kap tailscale-app little-snitch rustdesk netspot

macOS Defaults

Use the command when one exists. Otherwise follow the short path.

Tap to Click

defaults write com.apple.AppleMultitouchTrackpad Clicking -bool true
defaults write com.apple.driver.AppleBluetoothMultitouch.trackpad Clicking -bool true
defaults -currentHost write NSGlobalDomain com.apple.mouse.tapBehavior -int 1
defaults write NSGlobalDomain com.apple.mouse.tapBehavior -int 1

Three-Finger Drag

System Settings -> Accessibility -> Pointer Control -> Trackpad Options -> enable "Use trackpad for dragging" and choose "three finger drag"

Dock Autohide Speed

defaults write com.apple.dock autohide-time-modifier -float 0.5
defaults write com.apple.dock autohide-delay -int 0
killall Dock

Launchpad 10x8

defaults write com.apple.dock springboard-columns -int 10
defaults write com.apple.dock springboard-rows -int 8
killall Dock

Leave off

Keep App Expose disabled. Free the Spotlight shortcut if Keyboard Maestro is taking it.

Browser and Profiles

Keep the browser defaults tight so the machine feels right immediately.

  • Set Vivaldi as the macOS default browser.
  • Set DuckDuckGo as the default search engine inside Vivaldi.
  • Restore the Vivaldi profile and confirm workspaces, bookmarks, and extensions are back.
  • Chrome, Chrome Canary, and Edge are installed for compatibility work. They are not the main browser path.
  • Pin the core sites and sign back into the tabs that matter daily.

Terminal

Keep the shell boring and portable.

Minimal plugin list

plugins=(git)

Do not reintroduce

No autojump, no zsh-syntax-highlighting, and no pnpm in the shell bootstrap path.

Look

Use a dark terminal profile with about 20% transparency and keep familiar word-wise editing bindings.

.zshrc — tool environment lines

Add these after the Homebrew PATH block. Order matters: PATH first, then mise activate.

# Volta (Node version manager) — added by Volta installer
export PATH="$HOME/.volta/bin:$PATH"

# Rust
. "$HOME/.cargo/env"

# mise — activate after PATH, before any mise-managed tool
eval "$(mise activate zsh)"

# ~/bin — personal scripts including update-mac
export PATH="$HOME/bin:$PATH"

Coding

Install the tools, sign in, then let sync do the heavy lifting.

  • Install VS Code and enable Settings Sync.
  • Reconnect Codex and Claude.
  • Restore Antigravity only if it is still part of the current loop.
  • Use OrbStack for the local container path instead of Docker Desktop.
  • Keep Node.js version management on Volta.
  • Confirm the code command is back in the shell.

Apps, Exclusions, and Watchlist

The useful part is the decisions, not the marketing copy.

Main app groups

Productivity includes Keyboard Maestro, Rectangle Pro, Karabiner-Elements, BetterDisplay, Obsidian, Logseq, MailMate beta, KeePassXC, Spotify, Slack, and Discord. Microsoft and PDF apps sit in their own install groups.

Explicit exclusions

App Expose is off. Alfred and Raycast are out. pnpm is out. Dropover, iBar, Whimsical, and Notion are out of the default rebuild.

Replacements and watchlist

KeeWeb was replaced by KeePassXC. MailMate stays on mailmate@beta on Apple Silicon. Kap stays because it still has a clear niche. Logseq stays as the secondary knowledge tool next to Obsidian.

Restore State

This is the part most likely to be forgotten.

  • Sign into Vivaldi and confirm sync brings back workspaces, bookmarks, and extensions.
  • Sign into VS Code and enable Settings Sync.
  • Reconnect Codex, Claude, and Antigravity if they are part of the current workflow.
  • Import or sync Keyboard Maestro macros and reconnect launcher and clipboard shortcuts.
  • Activate Rectangle Pro and restore the expected window movement shortcuts.
  • Reconnect Karabiner-Elements rules if the keyboard layer matters.
  • Restore BetterDisplay presets if external monitor layouts and brightness mappings matter.
  • Reconnect Obsidian vaults and Logseq graphs.
  • Restore MailMate accounts, IMAP settings, and message rules.
  • Sign into Slack, Discord, Teams, Outlook, OneDrive, and Remote Desktop if the work setup needs them.
  • Check Shottr and Kap preferences if output folders or shortcuts matter.

Keep outside this repo

Keyboard Maestro and Rectangle Pro license material should live in a password manager. Keep exports for Keyboard Maestro, browser backups, Logseq graphs, Karabiner profiles, and Little Snitch rules in a separate private backup path.

Backup

Keep this simple unless there is a real gap.

Default answer: if Time Machine to TrueNAS or NFS already gives a full backup and a restore path you trust, there is no need to add Kopia.
  • Use Time Machine with the TrueNAS or NFS destination.
  • Run tmutil latestbackup and confirm the latest snapshot exists.
  • Run tmutil destinationinfo and confirm the destination is the one you expect.
  • Protect the state that Homebrew cannot recreate: Keyboard Maestro exports, Obsidian vaults, Logseq graphs, MailMate settings, dotfiles, SSH material, repo clones, and small preference folders that are annoying to rebuild.
  • Skip caches, node_modules, derived build output, downloaded dependencies, and media you can re-fetch.
  • Add Kopia only if you still need an extra encrypted offsite or repository-style backup layer.

Keep Updated

Copy the updater into ~/bin and run it when the backup path is available.

Install update helper

cp scripts/update-mac.sh ~/bin/update-mac
chmod +x ~/bin/update-mac

Run updates

update-mac

Preview only

update-mac --dry-run

What it does

Opens with a pre-flight summary: macOS version, free disk, the last Time Machine backup and its age, then a grouped, risk-annotated upgrade plan. The plan uses local checks only (no network) to flag !! major version jumps and macOS updates needing a restart, ~ pre-release channels like @beta or @canary, and pinned formulae that will not upgrade; everything else is summarized as routine. Then it checks Time Machine with tmutil latestbackup and tmutil destinationinfo. If backup is not available, it stops before any upgrades. If backup is available, it previews what it can, then asks once per tool with Yes, No, Skip, All, or Quit — choose All to approve that tool and every remaining one without further prompts. It covers Homebrew, npm globals, App Store apps through mas, uv, pipx, Volta, rustup, mise, and macOS software updates when those tools exist.

Preview first

Run update-mac --dry-run to print the summary and show what every tool would do without changing anything. It skips the Time Machine gate because nothing is mutated, making it the safe way to see what an update would touch.

Missing tools

If one of those tools is not installed, the script prints the install command and the upstream docs link instead of failing the whole run.

Run without prompts

Default behavior is interactive. Only use update-mac --yes if you want it to run straight through without stopping at each mutating step.

Greedy casks

Default behavior leaves auto-updating casks alone. Only use update-mac --greedy-casks if you want Homebrew to force them too.

Verify

Use the generated check script and a short manual pass.

Verify workstation

./scripts/verify-setup.sh workstation

Manual pass

Tap to Click and three-finger drag work. Vivaldi opens as default and uses DuckDuckGo. Keyboard Maestro shortcuts fire correctly. VS Code, Codex, Claude, OrbStack, Slack, Discord, and Microsoft apps all launch and sign in correctly. If Time Machine is the backup path, tmutil latestbackup returns the expected snapshot.

Repo maintenance

Only if you changed the repo itself: run python3 scripts/generate_brew_artifacts.py, python3 scripts/build_search_index.py, and python3 scripts/check_docs.py.

Remaining Separate Pages

Everything else collapsed into this page.

Homebrew Factory Reset Search