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/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 — 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 — tell the user to start DisplayBuddy
• Exit code 2 means timeout — the app may be busy, 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