# macOS Defaults

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` or as part of
[`mise bootstrap`](/bootstrap.html):

```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]`](/bootstrap/packages/):

- **Declarative and additive** — (domain, key) pairs merge across the
  [config hierarchy](/configuration.html) (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

```sh
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, and top-level `mise bootstrap` includes the
same reminder in its final follow-up summary. The usual suspects:

```sh
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:

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