macOS Defaults <Badge type="warning" text="experimental" />

mise can declare macOS user defaults (preferences) in the [bootstrap.macos.defaults] section of mise.toml and apply them with mise bootstrap macos-defaults apply:

toml

[bootstrap.macos.dock]
autohide = true
orientation = "left"
tilesize = 48
show_recents = false

[bootstrap.macos.finder]
show_all_files = true
show_pathbar = true
preferred_view_style = "list"

[bootstrap.macos.keyboard]
key_repeat = 2
initial_key_repeat = 15
press_and_hold = false

[bootstrap.macos.trackpad]
tap_to_click = true

[bootstrap.macos.defaults]
"com.apple.finder" = { AppleShowAllFiles = true }

The curated sections compile to raw defaults entries. Use [bootstrap.macos.defaults] for preferences not covered by the friendly sections. Within the same config file, raw defaults override the raw (domain, key) generated by a friendly setting. Across config files, normal global to local precedence still applies, so a local friendly setting can override a global raw default for the same pair.

Friendly sections

[bootstrap.macos.dock] supports:

Key	Raw default
`autohide`	`com.apple.dock.autohide`
`orientation`	`com.apple.dock.orientation`
`tilesize`	`com.apple.dock.tilesize`
`magnification`	`com.apple.dock.magnification`
`largesize`	`com.apple.dock.largesize`
`show_recents`	`com.apple.dock.show-recents`
`mru_spaces`	`com.apple.dock.mru-spaces`

orientation must be bottom, left, or right.

[bootstrap.macos.finder] supports:

Key	Raw default
`show_all_files`	`com.apple.finder.AppleShowAllFiles`
`show_pathbar`	`com.apple.finder.ShowPathbar`
`show_status_bar`	`com.apple.finder.ShowStatusBar`
`show_extensions_warning`	`com.apple.finder.FXEnableExtensionChangeWarning`
`preferred_view_style`	`com.apple.finder.FXPreferredViewStyle`

preferred_view_style must be icon, list, column, or gallery.

[bootstrap.macos.keyboard] supports:

Key	Raw default
`key_repeat`	`NSGlobalDomain.KeyRepeat`
`initial_key_repeat`	`NSGlobalDomain.InitialKeyRepeat`
`press_and_hold`	`NSGlobalDomain.ApplePressAndHoldEnabled`
`fn_state`	`NSGlobalDomain.com.apple.keyboard.fnState`

[bootstrap.macos.trackpad] supports:

Key	Raw defaults
`tap_to_click`	`com.apple.AppleMultitouchTrackpad.Clicking`, `com.apple.driver.AppleBluetoothMultitouch.trackpad.Clicking`
`three_finger_drag`	`com.apple.AppleMultitouchTrackpad.TrackpadThreeFingerDrag`, `com.apple.driver.AppleBluetoothMultitouch.trackpad.TrackpadThreeFingerDrag`

Unknown friendly keys, invalid enum values, and unsupported value types warn and are ignored.

Raw defaults

Each key under [bootstrap.macos.defaults] is a preferences domain. Quote domains containing dots. Values map to the matching defaults write type:

TOML value	written as	example
boolean	`-bool true/false`	`autohide = true`
integer	`-int <n>`	`tilesize = 48`
float	`-float <n>`	`scale = 1.5`
string	`-string <s>`	`orientation = "left"`

Other plist shapes (arrays, dicts, dates, data) are not supported; entries using them parse fine but are skipped with a warning, so configs written for newer mise versions still work.

Semantics

[bootstrap.macos.defaults] follows the same rules as [bootstrap.packages]:

Declarative and additive — (domain, key) pairs merge across the config hierarchy (global → project) as a union; a more local config overrides the value of a pair the global config declared but cannot remove it. mise never deletes a default.
OS-filtered — on anything other than macOS the section is inert: mise bootstrap macos-defaults status and mise doctor list the entries as skipped (so nothing is silently invisible) and mise bootstrap macos-defaults apply ignores them, so a shared config authored for both Linux and macOS just works.
Manual application only — mise never writes defaults implicitly; only mise bootstrap macos-defaults apply does, after the usual confirmation prompt.
Strictly typed — an existing value only counts as in sync when both the value and the plist type match: an integer 1 does not satisfy a configured true. mise bootstrap macos-defaults apply converges it to the typed value.

User defaults are per-user, so unlike system packages no sudo is ever involved. Host-scoped preferences (defaults -currentHost) and sudo defaults system domains are not supported.

Commands

mise bootstrap macos-defaults status            # shows defaults drift
mise bootstrap macos-defaults status --missing  # exit 1 if anything is unset or differs

mise bootstrap macos-defaults apply           # writes unset/differing defaults
mise bootstrap macos-defaults apply --dry-run # print the `defaults write` commands
mise bootstrap macos-defaults apply --yes     # skip the confirmation prompt

mise bootstrap macos-defaults status reports each entry as set (matches), differs (a value exists but doesn't match — the current value is shown), or unset. mise doctor summarizes the same drift.

App restarts

Some applications only pick up changed defaults after a relaunch — mise prints a reminder after writing. The usual suspects:

killall Dock
killall Finder
killall SystemUIServer

mise deliberately does not kill applications itself.

Finding keys

To discover a setting's domain and key, change it in System Settings and diff the output of defaults read before and after, or read a domain directly:

defaults read com.apple.dock
defaults read-type com.apple.dock tilesize