Rootbeer

Appearance

mac ​

The mac module manages common macOS preferences from Lua: Dock, Finder, input, hot corners, hostname, Touch ID for sudo, and lower-level defaults writes.

lua
local mac = require("rootbeer.mac")

Configure macOS ​

lua
mac.dock({
    autohide = true,
    tile_size = 48,
    position = "bottom",
    show_recents = false,
    minimize_effect = "scale",
})

mac.finder({
    show_extensions = true,
    show_hidden = true,
    show_path_bar = true,
    default_view = "list",
    search_scope = "current",
})

mac.hot_corners({
    top_right = "notification_center",
    bottom_left = "lock_screen",
})

mac.input({
    tap_to_click = true,
    key_repeat_rate = 2,
    initial_key_repeat = 15,
})

mac.hostname({ name = "my-mac" })
mac.touch_id_sudo()

Write Custom Defaults ​

For preferences that don't have a helper yet, use mac.defaults() directly:

lua
mac.defaults({
    { domain = "com.apple.LaunchServices", key = "LSQuarantine", type = "bool", value = false },
    { domain = "NSGlobalDomain", key = "NSAutomaticSpellingCorrectionEnabled", type = "bool", value = false },
})

API Reference ​

mac.defaults(entries) ​

Writes macOS defaults entries. Each entry runs defaults write domain key -type value.

Parameters

entriesmac.DefaultEntry[]

mac.dock(cfg) ​

Configures the macOS Dock and restarts it to apply changes.

Parameters — cfg: mac.DockConfig

autohidebooleanoptional
Auto-hide the Dock. Defaults to false.
autohide_delaynumberoptional
Delay before showing the Dock (seconds). Only applies when autohide is true.
large_sizenumberoptional
Magnified icon size in pixels. Only applies when magnification is true.
magnificationbooleanoptional
Enable icon magnification on hover.
minimize_effect"genie"|"scale"|"suck"optional
Window minimize animation.
minimize_to_appbooleanoptional
Minimize windows into their app icon.
position"bottom"|"left"|"right"optional
Screen edge for the Dock.
show_recentsbooleanoptional
Show recent applications section.
tile_sizenumberoptional
Icon size in pixels (16–128).

mac.finder(cfg) ​

Configures macOS Finder and restarts it to apply changes.

Parameters — cfg: mac.FinderConfig

default_view"column"|"gallery"|"icon"|"list"optional
Default Finder view style.
search_scope"current"|"mac"|"previous"optional
Default search scope.
show_extensionsbooleanoptional
Always show file extensions.
show_hiddenbooleanoptional
Show hidden files.
show_path_barbooleanoptional
Show the path bar at the bottom.
show_status_barbooleanoptional
Show the status bar at the bottom.

mac.hostname(cfg) ​

Sets the macOS hostname via scutil. Sets ComputerName, HostName, and LocalHostName. Requires sudo to take effect.

Parameters — cfg: mac.HostnameConfig

namestring
The hostname to set (used for ComputerName, HostName, and LocalHostName).

mac.hot_corners(cfg) ​

Configures macOS hot corners.

Parameters — cfg: mac.HotCorner

bottom_left"disabled" | "mission_control" | "app_windows" | "desktop" | "start_screensaver" | "disable_screensaver" | "notification_center" | "launchpad" | "quick_note" | "lock_screen" | "display_sleep"optional
Action for bottom-left corner.
bottom_right"disabled" | "mission_control" | "app_windows" | "desktop" | "start_screensaver" | "disable_screensaver" | "notification_center" | "launchpad" | "quick_note" | "lock_screen" | "display_sleep"optional
Action for bottom-right corner.
top_left"disabled" | "mission_control" | "app_windows" | "desktop" | "start_screensaver" | "disable_screensaver" | "notification_center" | "launchpad" | "quick_note" | "lock_screen" | "display_sleep"optional
Action for top-left corner.
top_right"disabled" | "mission_control" | "app_windows" | "desktop" | "start_screensaver" | "disable_screensaver" | "notification_center" | "launchpad" | "quick_note" | "lock_screen" | "display_sleep"optional
Action for top-right corner.

mac.input(cfg) ​

Configures macOS input preferences (keyboard and trackpad).

Parameters — cfg: mac.InputConfig

initial_key_repeatnumberoptional
Delay before key repeat starts (lower = shorter, default is 25).
key_repeat_ratenumberoptional
Key repeat rate (lower = faster, default is 6).
natural_scrollingbooleanoptional
Natural (content tracks finger) scrolling direction.
tap_to_clickbooleanoptional
Enable tap-to-click on trackpad.

mac.touch_id_sudo() ​

Enables Touch ID for sudo by writing /etc/pam.d/sudo_local. This is the Apple-recommended method that persists across macOS updates. Requires sudo to take effect.

mac.DefaultEntry ​

domainstring
The defaults domain (e.g. "com.apple.dock", "NSGlobalDomain").
keystring
The preference key.
type"bool"|"float"|"int"|"string"
The value type.
valueboolean|string|number
The value to set.