Power Users Guide

Advanced workflows for getting the most out of macprefs.

Integration with Dotfiles

Recommended: GNU Stow Integration

Use GNU Stow to manage your macprefs config as a symlink alongside other dotfiles:

# Dotfiles structure with stow packages
~/.dotfiles/
├── Brewfile                    # Include: brew "jmcombs/macprefs/macprefs"
├── install.sh                  # Main setup script
├── zsh/                        # Stow package for shell config
│   └── .zshrc
├── git/                        # Stow package for git config
│   └── .gitconfig
└── macprefs/                   # Stow package for macprefs config
    └── .config/
        └── macprefs/
            └── macos-config.json   # Your curated preferences

Brewfile entry:

tap "jmcombs/macprefs"
brew "jmcombs/macprefs/macprefs"    # Fully qualified tap/formula name required

install.sh integration (add after stow deployment):

#!/bin/bash
set -e

# Deploy dotfiles with stow
stow zsh git macprefs

# Apply macOS preferences
MACPREFS_CONFIG="$HOME/.config/macprefs/macos-config.json"

echo "Applying macOS system preferences..."
if command -v macprefs &> /dev/null; then
  if [ -f "$MACPREFS_CONFIG" ]; then
    # Interactive mode - user reviews and confirms each setting
    macprefs apply --config "$MACPREFS_CONFIG"
  else
    echo "Warning: macprefs config not found at $MACPREFS_CONFIG"
  fi
else
  echo "Warning: macprefs not installed. Run: brew install jmcombs/macprefs/macprefs"
fi

# Prompt for reboot (some settings require it)
echo ""
echo "Some macOS preference changes require a reboot to take effect."
read -p "Would you like to reboot now? (y/N): " reboot_choice
if [[ "$reboot_choice" =~ ^[Yy]$ ]]; then
  sudo shutdown -r now
fi

Basic Dotfiles Integration

For simpler setups without stow:

# In your dotfiles repository
~/.dotfiles/
├── .zshrc
├── .gitconfig
├── macprefs.json        # Your curated preferences
└── setup.sh

setup.sh:

#!/bin/bash
set -e

echo "Applying macOS preferences..."
if command -v macprefs &> /dev/null; then
    macprefs apply --config ~/.dotfiles/macprefs.json
else
    echo "macprefs not installed. Run: brew install jmcombs/macprefs/macprefs"
fi

echo "Restarting affected services..."
killall Dock Finder SystemUIServer 2>/dev/null || true

Advanced: Modular Configuration

Split your config for different contexts:

~/.dotfiles/
├── macprefs/
│   ├── base.json         # Core preferences (always applied)
│   ├── personal.json     # Home Mac additions
│   └── work.json         # Work Mac additions
└── setup.sh

Apply based on context:

macprefs apply --config ~/.dotfiles/macprefs/base.json
macprefs apply --config ~/.dotfiles/macprefs/personal.json  # or work.json

---

Partial Configurations

Create focused configs for specific use cases instead of one monolithic file:

dock.json

{
  "version": "1.0",
  "domains": {
    "com.apple.dock": {
      "autohide": true,
      "orientation": "left",
      "tilesize": 48
    }
  }
}

finder.json

{
  "version": "1.0",
  "domains": {
    "com.apple.finder": {
      "AppleShowAllExtensions": true,
      "ShowPathbar": true,
      "FXPreferredViewStyle": "Nlsv"
    }
  }
}

keyboard.json

{
  "version": "1.0",
  "domains": {
    "NSGlobalDomain": {
      "AppleKeyboardUIMode": 3,
      "com.apple.keyboard.fnState": true
    }
  }
}

Apply specific configs as needed:

macprefs apply --config dock.json
macprefs apply --config keyboard.json

Domain Discovery

Find which domain controls a specific preference:

# List all available domains
macprefs list

# List keys in a specific domain
macprefs list --domain com.apple.dock

# Inspect current values for specific keys
macprefs inspect --domains com.apple.dock --keys autohide,tilesize,orientation

Tip

Export your current preferences and search the JSON file to discover which domain/key controls a setting:

macprefs export current.json
grep -r "tilesize" current.json

Comparing State

Before applying, always preview changes:

# Summary view
macprefs plan --config my-prefs.json

# Detailed view of all changes
macprefs plan --config my-prefs.json --verbose

Rollback Strategy

If something goes wrong after applying:

# Rollback to the previous state (Free tier)
macprefs rollback

# Rollback to a specific run (Pro+ only)
macprefs rollback --run-id 2026-01-04T10-30-00

Snapshots are automatically created before each apply and stored in: ~/Library/Application Support/macprefs/runs/

Discovering Keys via defaults

The native defaults command is useful for exploring preferences:

# Read all values for a domain
defaults read com.apple.dock

# Read a specific key
defaults read com.apple.dock autohide

# Export entire domain to stdout
defaults export com.apple.dock -

Community Resources

• macOS Defaults — Curated database of macOS preference keys with descriptions and examples