> ## Documentation Index
> Fetch the complete documentation index at: https://orchard.andrewshawcare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize macOS system settings configured by Orchard

> Learn which macOS defaults Orchard configures out of the box, and how to change values for keyboard, mouse, trackpad, Dock, and screen lock behavior.

Orchard configures macOS system settings using the `defaults write` command, which writes preference values directly to macOS's built-in preferences system. Each setting lives in its module's `install.sh` file — to change a value, you edit the relevant file and re-run provisioning. You don't need to touch System Settings manually.

<Warning>
  After editing any `install.sh` setting, you must apply the change by either running `./provision.sh` from the Orchard root, or running the specific module's `install.sh` directly (for example, `./keyboard/install.sh`). Changes to these files do not take effect automatically.
</Warning>

## Keyboard

`keyboard/install.sh` sets how quickly keys repeat when held down.

```bash keyboard/install.sh theme={null}
#!/bin/bash -euo pipefail

defaults write 'Apple Global Domain' KeyRepeat -int 2
defaults write 'Apple Global Domain' InitialKeyRepeat -int 15
```

| Setting            | Default | Effect                                                                                   |
| ------------------ | ------- | ---------------------------------------------------------------------------------------- |
| `KeyRepeat`        | `2`     | How fast a held key repeats. Lower values repeat faster; the range is roughly 1–15.      |
| `InitialKeyRepeat` | `15`    | How long you must hold a key before it starts repeating. Lower values shorten the delay. |

To slow down key repeat, increase either value. To make your keyboard feel more responsive for navigation, decrease them. The minimum macOS allows via System Settings is `KeyRepeat 2` and `InitialKeyRepeat 15`, but you can set lower values by editing these files directly.

## Mouse

`mouse/install.sh` controls pointer tracking speed for a connected mouse.

```bash mouse/install.sh theme={null}
#!/bin/bash -euo pipefail

defaults write -globalDomain com.apple.mouse.scaling -float 3
```

The `com.apple.mouse.scaling` value is a float where higher numbers move the cursor faster across the screen. A value of `3` is noticeably faster than the macOS default. Decrease it (for example, to `1.5`) for a slower, more precise feel, or increase it beyond `3` for a larger display or high-DPI setup.

## Trackpad

`trackpad/install.sh` sets the trackpad tracking speed and enables tap to click.

```bash trackpad/install.sh theme={null}
#!/bin/bash -euo pipefail

defaults write -globalDomain com.apple.trackpad.scaling -float 3
defaults write com.apple.AppleMultitouchTrackpad Clicking -boolean true
```

| Setting                      | Default | Effect                                                                                          |
| ---------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `com.apple.trackpad.scaling` | `3`     | Pointer speed. Higher values move the cursor farther per unit of finger movement.               |
| `Clicking`                   | `true`  | Enables tap to click, so a light tap registers as a click without pressing the physical button. |

To disable tap to click, set `Clicking` to `false`. To adjust trackpad sensitivity, change the float value — `1.0` is a slower, more controlled feel.

## Dock

`dock/install.sh` configures Dock behavior and removes several default Apple apps from the Dock.

```bash dock/install.sh theme={null}
#!/bin/bash -euo pipefail

defaults write com.apple.dock autohide -boolean true
defaults write com.apple.dock show-recents -boolean false
```

| Setting        | Default | Effect                                                                                                                                   |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `autohide`     | `true`  | The Dock hides automatically and slides in when you move the pointer to the screen edge. Set to `false` to keep the Dock always visible. |
| `show-recents` | `false` | Hides recently used apps from the Dock. Set to `true` to show them.                                                                      |

The file also removes a set of Apple default apps from the Dock (Safari, Messages, Maps, and others) using `dockutil`. To keep any of those apps in your Dock, remove the relevant entry from the `default_dock_applications_to_remove` array in `dock/install.sh`.

## Security and privacy

`security-and-privacy/install.sh` configures the screensaver password lock.

```bash security-and-privacy/install.sh theme={null}
#!/bin/bash -euo pipefail

defaults write com.apple.screensaver askForPassword -bool true
defaults write com.apple.screensaver askForPasswordDelay -int 0
```

| Setting               | Default | Effect                                                                                                                                          |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `askForPassword`      | `true`  | Requires your password to unlock the screen after the screensaver activates. Set to `false` to disable the lock.                                |
| `askForPasswordDelay` | `0`     | How many seconds after the screensaver starts before the password is required. `0` means immediately; increase the value to add a grace period. |

For example, to require the password only after 5 seconds instead of immediately:

```bash theme={null}
defaults write com.apple.screensaver askForPasswordDelay -int 5
```

## Applying your changes

<Steps>
  <Step title="Open the relevant install.sh">
    Navigate to the module directory for the setting you want to change — for example, `keyboard/install.sh` for key repeat settings.
  </Step>

  <Step title="Edit the defaults write value">
    Change the integer or float value in the relevant `defaults write` line. Keep the key name and type flag (`-int`, `-float`, `-boolean`, `-bool`) unchanged.
  </Step>

  <Step title="Apply the change">
    Run the full provisioner to apply all settings:

    ```bash theme={null}
    ./provision.sh
    ```

    Or run just the module you changed for a faster iteration loop:

    ```bash theme={null}
    ./keyboard/install.sh
    ```
  </Step>
</Steps>