Configuration Format

All examples have been validated on macOS 26 (Tahoe).

Scope

The CLI is fully free: every command works across all preference domains, with JSON output, headless apply, filtering, and rollback to any run available to everyone.

Minimal Config

The simplest valid config requires version and domains:

{
  "version": "1.0",
  "domains": {
    "com.apple.dock": {
      "autohide": true,
      "orientation": "left",
      "show-recents": false
    }
  }
}

Full Example (Multiple Domains)

{
  "version": "1.0",
  "os": "26",
  "domains": {
    "com.apple.dock": {
      "autohide": true,
      "orientation": "left",
      "show-process-indicators": false,
      "show-recents": false,
      "tilesize": 48,
      "magnification": true,
      "largesize": 96
    },
    "com.apple.finder": {
      "AppleShowAllExtensions": true,
      "ShowPathbar": true,
      "FXEnableExtensionChangeWarning": false,
      "FXPreferredViewStyle": "Nlsv"
    },
    "NSGlobalDomain": {
      "AppleKeyboardUIMode": 3,
      "com.apple.keyboard.fnState": true,
      "AppleInterfaceStyle": "Dark"
    }
  }
}

Extended Form with Compare Hints

Use extended form for arrays that should ignore order:

{
  "version": "1.0",
  "domains": {
    "com.apple.finder": {
      "FavoriteItems": {
        "value": ["Applications", "Documents", "Downloads"],
        "compare": "unordered",
        "note": "Sidebar items - order doesn't matter"
      }
    }
  }
}

Compare modes (validated in testing):

• default or strict: Exact equality including array order
• unordered: Arrays/dicts compared by content, ignoring order

Special Characters

All Unicode, emojis, and escape sequences are supported:

{
  "version": "1.0",
  "domains": {
    "com.apple.TextEdit": {
      "author": "日本語テスト",
      "emoji-test": "🎉🚀💻",
      "path-with-spaces": "/Users/test/My Documents/file.txt"
    }
  }
}

Large Configs

Configs with 100+ domains are supported with good performance (~73ms per domain):

{
  "version": "1.0",
  "domains": {
    "com.apple.domain1": { "key1": "value1" },
    "com.apple.domain2": { "key2": "value2" },
    ...
    "com.apple.domain100": { "key100": "value100" }
  }
}

Required Fields

Every config must have:

1. "version": "1.0" - Config schema version
2. "domains": { ... } - Map of domain names to key-value pairs

Optional fields:

• "os": "26" - Target macOS version (informational)

Workflow Examples

Export and Apply (Free Tier)

# Export current Apple preferences
macprefs export my-prefs.json

# Review what would change
macprefs plan --config my-prefs.json

# Apply with interactive confirmation
macprefs apply --config my-prefs.json

CI/CD Workflow

# Headless apply for automation
macprefs apply --config my-prefs.json --yes

# JSON output for parsing
macprefs plan --config my-prefs.json --format json

Notes

• Shorthand form: Direct "key": value infers type from JSON
• Extended form: "key": {"value": ..., "compare": "unordered", "note": "..."} for options
• Managed-subset apply: Only listed keys are compared/applied; unlisted keys ignored
• Domain scope: all preference domains are available
• Types: JSON bool → plist integer (0/1), JSON number → plist integer/float, JSON string → plist string

---

Documentation auto-synced from macprefs configuration examples.