Configuration Format

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

License Tier Scope

• Free tier: Apple domains only (com.apple.*, NSGlobalDomain)
• Pro tier: JSON output, headless execution, rollback to any run

Note: Third-party domain support is planned for a future release.

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 (Pro Required)

# 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: Apple domains only in v0.1.3 (third-party support planned for future release)
• Types: JSON bool → plist integer (0/1), JSON number → plist integer/float, JSON string → plist string

---

Documentation auto-synced from macprefs configuration examples.