Script: scripts/setup. Sets up the foundational shell environment on a new or existing machine.

What it does:

• Installs Xcode Command Line Tools if not present
• Links everything in dotfiles/ into $HOME as symlinks (with automatic backups of any existing files)
• Links scripts/ and bin/ into ~/bin so tools are on PATH
• Applies macOS system preferences via scripts/defaults.sh
• Sets Zsh as the login shell
• Generates a rollback script at ~/.mrk/defaults-rollback.sh

Table 2.1-1. Managed Dotfiles

File	Purpose
.aliases	Shell aliases
.gitconfig	Git configuration
.hushlogin	Suppresses "Last login" terminal message
.zprofile	Zsh login shell profile
.zshenv	Zsh environment variables
.zshrc	Zsh interactive shell config
Makefile	mrk commands available from ~/

make setup                    # Full Phase 1
make setup --only dotfiles    # Link dotfiles only
make setup --only tools       # Link scripts/bin only
make setup --only defaults    # Apply macOS defaults only
make setup --dry-run          # Preview changes without applying

Script: scripts/brew. Installs Homebrew and all packages listed in the Brewfile.

What it does:

• Installs Homebrew if not present
• Runs brew bundle install from the Brewfile
• Presents interactive prompts for packages that are new
• Uses the mrk-picker TUI or gum for package selection

make brew

Script: scripts/post-install. Configures installed apps. Must be run after Phase 2.

What it does:

• Topgrade: Links assets/topgrade.toml to ~/.config/topgrade.toml
• Browsers: Applies Safari defaults, Chrome/Brave managed policies, Helium defaults
• App defaults: Applies defaults write settings for Audio Hijack, Fission, AlDente, Rogue Amoeba update settings
• Preferences auto-pull: If ~/.mrk/preferences/ is absent and SSH is authenticated, automatically clones mrk-prefs
• Plist imports (15 apps): Non-destructive — skips any app that already has a preferences file
• App Support restore: Restores Loopback and SoundSource configuration files (non-destructive)
• Login items: Registers AlDente, BetterSnapTool, Bitwarden, Chrono Plus, Dropbox, Hammerspoon, Hot, Ice, NordPass, Raycast, SoundSource, Stats

Table 2.3-1. Managed App Preferences

App	Notes
BetterSnapTool	Plist imported
Ice	Plist imported
iTerm2	Plist imported
Raycast	Plist imported
Stats	Plist imported
Loopback	Plist + App Support files
SoundSource	Plist + App Support files
Audio Hijack	Plist imported
Farrago	Plist imported
Piezo	Plist imported
Typora	Plist imported
Hot	Plist imported
Keka	Plist imported
TimeMachineEditor	Plist imported
MacWhisper	Plist imported

make post-install

Two tools cover day-to-day Brewfile management.

bf — interactive TUI for browsing, adding, deleting, moving, and pruning Brewfile entries:

bf                    # Open the Brewfile manager TUI
bf --help             # Show keys and options

Key operations: a add · d delete · m move · g toggle greedy · p prune uninstalled · / search · w write · c commit

Prune mode (p) — fetches brew list, shows all Brewfile entries not currently installed. Space to mark, a to toggle all, enter to delete marked entries.

sync — scan installed packages, diff against the Brewfile, and add anything missing:

sync                  # Interactive — opens mrk-picker TUI to select packages
sync -n               # Dry run — show what would be added, make no changes
sync -c               # Auto-commit the Brewfile after updating

How sync works:

1. Reads the Brewfile to build a list of already-tracked packages
2. Runs brew leaves (top-level formulae) and brew list --cask to see what's installed
3. Computes the diff — packages installed but not yet in the Brewfile
4. Opens mrk-picker TUI: use Space to select, Enter to confirm, q to quit
5. Prompts via gum to choose which Brewfile section each formula goes into
6. Casks are auto-assigned to the existing cask section
7. Inserts each entry alphabetically within its section

After configuring an app, capture and push the preferences.

snapshot-prefs — export all managed app preferences and push to the private repo:

snapshot-prefs

How it works:

1. Exports the preference plist for each managed app using defaults export
2. Commits all changes to ~/.mrk/preferences/ with a timestamped message
3. Pushes to sevmorris/mrk-prefs on GitHub

Snapshots are idempotent — if nothing changed, it reports "No changes to push."

pull-prefs — clone or update preferences from the private repo:

pull-prefs

Clones mrk-prefs into ~/.mrk/preferences/ if it doesn't exist, or fast-forward pulls if it does.

The manual is a hand-authored HTML document at docs/index.html. Edit it directly and commit both it and docs/manual.md (the prose reference).

# Edit the manual
$EDITOR ~/mrk/docs/index.html

# Commit and push
cd ~/mrk
git add docs/index.html docs/manual.md
git commit -m "docs: update manual"
git push

Run these steps on the old machine before transferring.

1. Sync the Brewfile

sync -c

Captures any packages installed since the last sync and commits the updated Brewfile.

2. Snapshot app preferences

snapshot-prefs

Exports and pushes all app preference plists plus Application Support files. Verify "Pushed to git@github.com:sevmorris/mrk-prefs.git" appears in the output.

3. Push any pending mrk changes

cd ~/mrk
git status
git push

4. Verify SSH authentication

ssh -T git@github.com
# Expected: Hi sevmorris! You've successfully authenticated...

The new machine needs your SSH key to auto-pull mrk-prefs during make post-install.

5. Note anything not covered by mrk

• App Store apps (manually reinstall from Purchases)
• Software licenses (export from your license manager)
• Any manual system settings not captured by defaults write
• VPN configurations, certificates, etc.

Prerequisites: macOS 15 or later, active internet connection, GitHub SSH key (or ability to create one).

Step 1 — Clone mrk

If SSH is already set up:

git clone git@github.com:sevmorris/mrk.git ~/mrk

On a fresh machine without SSH configured, clone over HTTPS first:

git clone https://github.com/sevmorris/mrk.git ~/mrk

Step 2 — Phase 1: Shell & Dotfiles

cd ~/mrk
make setup
exec zsh        # Reload shell to pick up dotfiles and ~/bin

Step 3 — (If needed) Add SSH Key to GitHub

If you cloned over HTTPS, add your SSH key now before Phase 3:

ssh-keygen -t ed25519 -C "your-email@example.com"
cat ~/.ssh/id_ed25519.pub | pbcopy
# Add to: github.com → Settings → SSH and GPG keys → New SSH key
ssh -T git@github.com

Step 4 — Phase 2: Homebrew

make brew

Installs Homebrew (if needed) and all packages from the Brewfile.

Step 5 — Phase 3: App Configuration

make post-install

Configures apps, imports personal preferences, and sets up login items. If ~/.mrk/preferences/ was not auto-pulled:

pull-prefs
make post-install   # Re-run to import plists

Step 6 — Verify the Installation

make status     # Check dotfiles, tools, shell, Homebrew, Brewfile packages
make doctor     # Run full diagnostics