Betterdisplay

BetterDisplay Workflow

Sync BetterDisplay settings with dotfiles.

Helpers

quit-app

osascript -e 'quit app "BetterDisplay"' 2>/dev/null || true
sleep 1

import-from-dotfiles

Requires app to be quit first.

defaults import pro.betterdisplay.BetterDisplay ~/projects/jasonkuhrt/dotfiles/betterdisplay/settings.plist

export-to-dotfiles

Requires app to be quit first.

defaults export pro.betterdisplay.BetterDisplay ~/projects/jasonkuhrt/dotfiles/betterdisplay/settings.plist

launch-app

pgrep -x "BetterDisplay" || open -a "BetterDisplay"

Flow

1. Show welcome

Display this:

/betterdisplay - Sync display settings with dotfiles

┌─────────────────────────────────────────────────┐
│  [sync if needed] → [configure] → [export]      │
│                                                 │
│  1. Import from dotfiles (if changed elsewhere) │
│  2. Open app for you to configure               │
│  3. Export your changes back to dotfiles        │
└─────────────────────────────────────────────────┘

2. Check sync status

DOTFILES_PLIST=~/projects/jasonkuhrt/dotfiles/betterdisplay/settings.plist
if [ ! -f "$DOTFILES_PLIST" ]; then
    echo "first-time"
else
    defaults export pro.betterdisplay.BetterDisplay /tmp/bd-current.plist 2>/dev/null || true
    if diff -q "$DOTFILES_PLIST" /tmp/bd-current.plist >/dev/null 2>&1; then
        echo "in-sync"
    else
        echo "needs-import"
    fi
fi

• first-time → tell user "First-time setup", skip to step 4
• in-sync → tell user "Settings in sync", skip to step 4
• needs-import → tell user "Importing changes from dotfiles...", continue

3. Import from dotfiles

• quit-app
• import-from-dotfiles

4. launch-app

5. Show config instructions

BetterDisplay is open. Configure it:

REQUIRED (first-time):
  Settings → Displays → "Default display identification method" → "Match vendor, model"

RESOLUTION FAVORITES:
  Menu bar → Studio Display → resolution dropdown → right-click → "Add to Favorites"
  Suggested: 2880×1620, 3200×1800, 3840×2160

UNLOCK MORE RESOLUTIONS (Pro feature, requires reboot):
  1. Settings (gear) → Displays → click "Studio Display" row
  2. Enable "Edit the default system configuration of this display model"
  3. Enable "Enable flexible scaling"
  4. Click Apply (admin password required)
  5. Reboot
  → After reboot: 3200×1800, 3840×2160, and slider available

OTHER PRO FEATURES:
  • Layout Protection: Settings → Displays → "Protect resolution"
    (prevents macOS resetting your choice)
  • XDR Brightness: Menu bar → Studio Display → XDR slider
    (boost to 1600 nits)

TROUBLESHOOTING:
  • Safe mode: Hold SHIFT while launching
  • Reset: Settings → Application → "Reset App Settings"

6. Prompt user (AskUserQuestion: "Done" / "Cancel")

• Cancel → exit

7. Export to dotfiles

• quit-app
• export-to-dotfiles

8. Prompt: commit? (AskUserQuestion: "Yes" / "No")

• Yes → git -C ~/projects/jasonkuhrt/dotfiles add betterdisplay/settings.plist && git -C ~/projects/jasonkuhrt/dotfiles commit -m "feat(betterdisplay): update settings"

Paths

• Dotfiles: ~/projects/jasonkuhrt/dotfiles/betterdisplay/settings.plist
• macOS prefs: ~/Library/Preferences/pro.betterdisplay.BetterDisplay.plist