macOS defaults

Turn a Mac's system settings into idempotent defaults code, so a machine's preferences are reproducible, reviewable, and drift is visible. The golden rule is verification-first: prove a setting took by re-reading it — never trust that a defaults write did what you meant.

Route to a workflow

The scripts (call these, don't re-derive them)

The mechanical commands live in scripts/ as tested helpers — call them by name instead of hand-writing defaults read loops or a parse-and-compare each session:

See scripts/README.md for the full toolbox, a worked example, and conventions.

Discovery (always run first)

sw_vers                                                   # macOS version (some keys are version-specific)
ls ~/.config/devenv/macos.sh 2>/dev/null                  # is there already a declared script?
scripts/defaults_read.py                                  # sample live values across the curated set
scripts/defaults_read.py --find <term>                    # locate a setting's domain/key by keyword

• A domain is an app's pref bundle id (com.apple.dock, com.apple.finder, NSGlobalDomain for system-wide). A key is one setting inside it. defaults read <domain> <key> prints one value.
• Don't know a setting's domain/key? scripts/defaults_read.py --find <term>, or diff defaults read before/after toggling it in System Settings — see reference/verification.md.

Core principles

1. Verify by re-reading. After defaults write, defaults read <domain> <key> and confirm it equals the intended value. A silent write can no-op or coerce the type.
2. Read reality before you declare it. setup reads current values so the script reflects the machine, not a guess.
3. Idempotent by construction. The script is pure defaults write lines — re-running is a no-op. optimize confirms live == declared; a second upgrade (apply) changes nothing.
4. Some settings need a restart. killall Dock Finder SystemUIServer picks up most; a few need logout/reboot and won't reflect until then. Flag those explicitly.
5. Track the script. It's a dotfile — version it via the dotfiles skill (chezmoi) so prefs are reproducible across machines.

Settings

Read ~/.config/devenv/config.toml before prompting; if a [macos-defaults] section exists, use it as defaults (precedence: explicit answer this session > config.toml > ask). Had to ask? Offer to save the answer back. Managed by the devenv skill. Keys honored:

• script — path to the declarative defaults script (e.g. ~/.config/devenv/macos.sh).

Safety

• Some domains need sudo (system-wide /Library prefs, login window). Confirm first; never run sudo defaults write without the user's go-ahead.
• Back up prior values with defaults read <domain> <key> before writing, so a change is reversible.
• Do NOT touch security/privacy settings — FileVault, Gatekeeper, the firewall, TCC — without explicit confirmation. Never disable a security feature silently.
• Some settings require logout or restart to take effect; say so rather than claiming success.
• defaults write is mutating and is deliberately not pre-approved here — the skill reads freely but asks before it writes.