displaybuddy

name	displaybuddy
description	Control external monitors and MacBook displays. Adjust brightness, contrast, volume, input source, rotation, apply presets, manage schedules, and sync displays. Use when the user asks to change monitor settings, dim or brighten screens, switch inputs, activate display presets, or manage multi-monitor setups.
allowed-tools	Bash(displaybuddy *)

DisplayBuddy Monitor Control

You control monitors using the displaybuddy CLI. The DisplayBuddy app must be running for commands to work.

Workflow

Always start by discovering what displays are connected:

displaybuddy status --json

This returns a compact overview of all displays with their current values. Use the display names from this output in subsequent commands and never guess display names.

Commands Reference

All commands support --json for structured output. Always use --json when you need to parse results.

Display Discovery

# Compact overview table (start here)
displaybuddy status --json

# Full details for all displays
displaybuddy list --json

# Full details for one display
displaybuddy get "Display Name" --json

# Single property
displaybuddy get "Display Name" --brightness --json

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