Displaybuddy

Setting Display Properties

Target a display by name, --uuid, --index (from status output), or --all.

# Brightness (0-100)
displaybuddy set "Display Name" --brightness 80

# Contrast (0-100)
displaybuddy set "Display Name" --contrast 70

# Volume (0-100)
displaybuddy set "Display Name" --volume 30

# Multiple properties at once
displaybuddy set "Display Name" --brightness 80 --contrast 70 --volume 30

# All displays at once
displaybuddy set --all --brightness 50

# Input source (by name or DDC code)
displaybuddy set "Display Name" --input hdmi1
displaybuddy set "Display Name" --input displayport1
displaybuddy set "Display Name" --input usbc
# Valid inputs: displayport1, displayport2, hdmi1-4, thunderbolt, usbc, usbc2

# Rotation
displaybuddy set "Display Name" --rotation 90  # 0, 90, 180, 270

# XDR/Ultra-bright (MacBook Pro only, 0-100)
displaybuddy set "Built-in Display" --xdr-brightness 50

# Control mode
displaybuddy set "Display Name" --control-mode external
# Valid modes: external, internal, software, nativelySupported, samsungSmart

Presets

# List all presets
displaybuddy preset list --json

# Activate a preset
displaybuddy preset activate "Preset Name"

# Activate with delay (seconds)
displaybuddy preset activate "Preset Name" --delay 5

Schedules

# List all schedules
displaybuddy schedule list --json

# Enable/disable a schedule by UUID (or unique prefix)
displaybuddy schedule enable "uuid-string"
displaybuddy schedule disable "uuid-string"

Display Sync

Sync makes all displays follow one source display's brightness, contrast, and volume.

# Check sync status
displaybuddy sync status --json

# Enable sync with a display as source
displaybuddy sync enable "Display Name"

# Disable sync
displaybuddy sync disable

Version

displaybuddy version --json

Response Format

Most commands with --json print the successful payload directly, not a wrapper object.

Examples:

• displaybuddy status --json prints an array of displays
• displaybuddy get "Display Name" --json prints the display object
• displaybuddy get "Display Name" --brightness --json prints the property value payload
• displaybuddy version --json prints a custom object with cliVersion, appVersion, and buildNumber

On failure, the CLI prints Error: ... to stderr and exits non-zero.

Common Patterns

"Dim everything for a movie":

displaybuddy set --all --brightness 30 --contrast 50

"Set up my coding environment":

displaybuddy preset activate "Coding"

"Switch my monitor to HDMI": First run displaybuddy status --json to find the display name, then:

displaybuddy set "Monitor Name" --input hdmi1

"Make all monitors match my main display":

displaybuddy sync enable "Main Display Name"

"Turn brightness up a bit": First get current value with displaybuddy get "Display Name" --brightness --json, then set a value 10-20 higher.

Important Notes

• Display names are case-insensitive
• If the app is not running, commands will fail with exit code 1, so tell the user to start DisplayBuddy
• Exit code 2 means timeout, so the app may be busy and you can try again
• Set commands return the updated display state, so you can verify the change took effect
• Brightness, contrast, and volume are all 0-100 integers
• When the user says "dim" without specifics, reduce brightness by 20-30 from current value
• When the user says "brighten" without specifics, increase brightness by 20-30 from current value