CLI reference

This reference reproduces the CLI help from BetterDisplay 5.0.6, imported on 2026-09-29. For setup and worked examples, see the Integration overview and CLI examples. Run betterdisplaycli help for the help belonging to your installed app version.

General overview and syntax

The app supports the following integration methods:

The various integration methods can be separately enabled and disabled under Settings in the application UI.

An integration command might receive one or more operations and zero or more parameters. A parameter might or might not have a value associated with it.

Syntax for command line access:

./BetterDisplay operation [operation] [-parameter[=value]] [-parameter[=value]]

Notes:

You can also use betterdisplaycli for simpler access. Installation via Homebrew:

brew install waydabber/betterdisplay/betterdisplaycli

Examples (both commands set the brightness of a display with the name MyDisplay to 80%):

./BetterDisplay set -name=MyDisplay -brightness=0.8

betterdisplaycli set --name=MyDisplay --brightness=80%

Syntax for custom URL scheme integration:

BetterDisplay://operation[/operation (…)][?parameter[=value]][&parameter[=value]]

Example (raw URL and scripted access using open command with proper escaping):

BetterDisplay://set?name=MyDisplay&brightness=0.8

open BetterDisplay://set\?name=MyDisplay\&brightness=0.8

To safeguard access, a special token can optionally be defined in Settings which must then be present in the URL via a token= parameter. The custom URL scheme integration supports x-callback-url to report back success or error and results. More information: https://x-callback-url.com/specification/

Syntax for HTTP based integration:

http://<hostname>:55777/command/[command/][?parameter[=value]][&parameter[=value]]

Example (raw URL and scripted access using curl command with proper escaping):

http://localhost:55777/set?name=MyDisplay&brightness=0.8

curl http://localhost:55777/set\?name=MyDisplay\&brightness=0.8

The listening port can be customized under Settings. Example uses local access via localhost - use the appropriate hostname with remote calls. To safeguard access, a special token can optionally be defined in Settings which must then be present in the URL via a token= parameter.

With URLs you can use %20 to substitute for space.

Operations

Operations define how a command will be interpreted. Some operations can be combined (for example set or toggle with get to both set and get a value.

Parameters

Parameters affect how an operation is carried out. Some parameters can be mixed with each other. Parameters may or may not have values. Some parameters require additional parameters to function.

Device identification and device listing

Setting or getting values

Parameters invoking an app feature

Parameters specific for various features