macos-settings

The macos-settings resource manages common macOS system preferences using the built-in defaults command. It covers mouse, keyboard, trackpad, and Dock settings — everything you need to reproduce your preferred system configuration on a new Mac.

Parameters

All sections and their sub-keys are optional. You only need to declare the settings you want to manage.

`mouse`

Parameter	Type	Default	Description
`naturalScrolling`	boolean	`true`	Scroll content in the natural direction (content follows finger). When `false`, uses the traditional scroll direction.
`acceleration`	boolean	`true`	Enable mouse acceleration. When `false`, the cursor moves at a fixed speed regardless of how fast the mouse is moved.
`speed`	number (0–3)	`1.5`	Mouse tracking speed. Higher values make the cursor move farther per physical movement.

`keyboard`

Parameter	Type	Default	Description
`keyRepeat`	integer	`6`	Rate of key repeat while a key is held. Lower = faster (1 is fastest; 120 effectively disables repeat).
`initialKeyRepeat`	integer	`68`	Delay before key repeat begins (in ticks). Lower = shorter delay (10 minimum).
`pressAndHold`	boolean	`true`	When `true`, holding a key shows the accent character picker. When `false`, the key repeats instead.
`fnKeysAsStandardKeys`	boolean	`false`	When `true`, the F1–F12 keys act as standard function keys; press Fn to trigger special actions (brightness, volume, etc.).
`keyboardNavigation`	boolean	`false`	When `true`, enables Tab-based focus navigation in system dialogs (equivalent to "Keyboard navigation" in System Settings).

`trackpad`

Parameter	Type	Default	Description
`speed`	number (0–3)	`1.5`	Trackpad tracking speed. Higher values make the cursor move farther per swipe distance.

`dock`

Parameter	Type	Default	Description
`position`	`"left"` \| `"bottom"` \| `"right"`	`"bottom"`	Position of the Dock on screen.
`iconSize`	integer (16–128)	`48`	Dock icon size in pixels.
`autohide`	boolean	`false`	Automatically hide and show the Dock when the cursor moves near the screen edge.
`hoverDelay`	number	`0.2`	Seconds to wait before the Dock appears when hovering near the screen edge. Set to `0` for instant reveal.
`animationSpeed`	number	`0.5`	Duration in seconds of the Dock slide-in/out animation. Set to `0` to disable the animation entirely.
`showRecents`	boolean	`true`	Show recently opened apps in a dedicated section of the Dock.
`minimizeEffect`	`"genie"` \| `"scale"` \| `"suck"`	`"genie"`	Window minimize animation style.

macOS defaults mapping

The table below shows the underlying defaults key used for each friendly parameter name.

Section	Parameter	Domain	Key
mouse	`naturalScrolling`	`NSGlobalDomain`	`com.apple.swipescrolldirection`
mouse	`acceleration`	`NSGlobalDomain`	`com.apple.mouse.linear` (inverted)
mouse	`speed`	`NSGlobalDomain`	`com.apple.mouse.scaling`
keyboard	`keyRepeat`	`NSGlobalDomain`	`KeyRepeat`
keyboard	`initialKeyRepeat`	`NSGlobalDomain`	`InitialKeyRepeat`
keyboard	`pressAndHold`	`NSGlobalDomain`	`ApplePressAndHoldEnabled`
keyboard	`fnKeysAsStandardKeys`	`NSGlobalDomain`	`com.apple.keyboard.fnState`
keyboard	`keyboardNavigation`	`NSGlobalDomain`	`AppleKeyboardUIMode` (0/2)
trackpad	`speed`	`NSGlobalDomain`	`com.apple.trackpad.scaling`
dock	`position`	`com.apple.dock`	`orientation`
dock	`iconSize`	`com.apple.dock`	`tilesize`
dock	`autohide`	`com.apple.dock`	`autohide`
dock	`hoverDelay`	`com.apple.dock`	`autohide-delay`
dock	`animationSpeed`	`com.apple.dock`	`autohide-time-modifier`
dock	`showRecents`	`com.apple.dock`	`show-recents`
dock	`minimizeEffect`	`com.apple.dock`	`mineffect`

Example usage

Common macOS preferences

codify.jsonc

[
  {
    "type": "macos-settings",
    "os": ["macOS"],
    "mouse": {
      "naturalScrolling": true
    },
    "keyboard": {
      "keyRepeat": 2,
      "initialKeyRepeat": 15,
      "pressAndHold": false
    },
    "dock": {
      "position": "left",
      "iconSize": 36,
      "autohide": true,
      "showRecents": false
    }
  }
]

Non-Apple keyboard setup

codify.jsonc

[
  {
    "type": "macos-settings",
    "os": ["macOS"],
    "mouse": {
      "naturalScrolling": false,
      "acceleration": false
    },
    "keyboard": {
      "fnKeysAsStandardKeys": true
    }
  }
]

Trackpad speed only

codify.jsonc

[
  {
    "type": "macos-settings",
    "os": ["macOS"],
    "trackpad": {
      "speed": 2.5
    }
  }
]

Notes

This resource is macOS only and has no effect on Linux.
No software installation is required — defaults is a built-in macOS command.
Dock settings take effect immediately (the Dock is automatically restarted). Other settings typically take effect the next time you open an application or after logging out.
When the resource is removed from your configuration, all managed settings are reset to their macOS system defaults using defaults delete.
Changes to fnKeysAsStandardKeys may require a full system restart to take effect.
The keyRepeat and initialKeyRepeat values use macOS internal tick units, not milliseconds. Smaller values produce faster key repeat.

macos-settings

On this page