Quick Start

Quick Start: Your First Migration

⚠️ Critical: Never apply a raw export directly to a new Mac. Raw exports contain ephemeral keys (UUIDs, timestamps, cache data) that will cause conflicts. Always curate your configuration first.

Overview: The Safe Migration Workflow

1. Export → Create a raw preferences snapshot (reference only)
2. Curate → Build a clean config with only desired settings (required step)
3. Version Control → Commit the curated config to your dotfiles
4. Apply → Use the curated config on your new Mac

---

Step 1: Export Your Current Preferences (Reference Only)

On your current Mac, export your preferences to use as a reference:

# Export current Apple preferences
macprefs export raw-export.json

Important: This raw export is a reference document only. It contains:

• ✓ Your actual preference values (useful for reference)
• ✗ Ephemeral keys that should never be migrated (UUIDs, timestamps, cache data)
• ✗ Machine-specific settings (window positions, device identifiers)

Do not apply this file directly. Use it to inform your curated configuration.

---

Step 2: Create Your Curated Configuration (Required)

This is the crucial step that ensures a safe migration. You’ll create a clean configuration file containing only the settings you want to migrate.

Option A: Start with the Recommended Template (Easiest)

Copy the Recommended Configuration Template from the First Config guide:

# Create your configuration file
touch my-config.json
# Copy the template from the "Recommended Configuration Template" section below
# Paste into my-config.json and customize

Then customize it:

1. Remove settings you don’t want
2. Adjust values to match your preferences
3. Optionally reference your raw-export.json to find additional settings

Option B: Manual Curation from Raw Export (Advanced)

If you prefer to build from your raw export, follow the Manual Curation Workflow guide for step-by-step guidance on identifying safe vs. ephemeral keys.

---

Step 3: Version Control Your Curated Config

# Add to your dotfiles repository
cd ~/.dotfiles
cp my-config.json macprefs.json
git add macprefs.json
git commit -m "Add curated macOS preferences configuration"
git push

What to commit: Only your curated configuration file, never the raw export.

---

Step 4: Apply on Your New Mac

On your new Mac:

# Install macprefs via Homebrew
brew install jmcombs/macprefs/macprefs

# Clone your dotfiles
git clone https://github.com/you/dotfiles ~/.dotfiles

# Review what will change (dry run)
macprefs plan --config ~/.dotfiles/macprefs.json

# Apply with confirmation (Free tier)
macprefs apply --config ~/.dotfiles/macprefs.json

# Or apply headlessly (Pro tier)
macprefs apply --config ~/.dotfiles/macprefs.json --yes

Note: The plan output shows only settings that differ from the current state. On a fresh macOS installation, ~70-80% of your curated settings will typically need to be changed, while the rest may already match macOS defaults.

---

Step 5: Verify and Reboot

Some macOS preferences require a reboot to take effect (e.g., trackpad settings, Stage Manager). After applying:

# Verify key settings were applied
defaults read com.apple.dock autohide        # Should return 1 if configured
defaults read com.apple.finder ShowPathbar   # Should return 1 if configured

# Reboot to ensure all changes take effect
sudo shutdown -r now

---

Step 6: Rollback if Needed

# Something not right? Rollback immediately
macprefs rollback

# Or check for drift later
macprefs plan --config ~/.dotfiles/macprefs.json

---