Integration overview

BetterDisplay can take part in your daily automations, respond to other apps and send actions to connected equipment. Start with macOS Shortcuts for ready-made actions, use the command-line interface for more detailed requests, or connect a display's controls and events to your own scripts and services.

Explore subtopics

Separate articles that explore this topic in more detail.

macOS Shortcuts
BetterDisplay's actions let a shortcut change display settings without assembling command-line arguments.
CLI reference
Look up command syntax, operations and parameters in the imported BetterDisplay 5.0.6 CLI help.
CLI examples
Use these examples to build repeatable display setups, bind an adjustment to a key, or combine BetterDisplay with another automation tool.
Control Integration and Events
Control Integration connects BetterDisplay's display controls to equipment or software that accepts scripts, URLs or macOS distributed notifications.
App console
BetterDisplay's built-in console lets you try integration commands and read their responses inside the app.
Enable macOS Console logging
Use macOS Console to follow BetterDisplay's diagnostic messages in the system log.
Third-party app integration
Mac apps can send BetterDisplay requests through DistributedNotificationCenter and receive matching responses.
Advanced terminal preferences
Use the macOS defaults command to change persistent preferences that have no Settings interface.

Choose an integration method

Use macOS Shortcuts for named actions and display pickers. Choose the CLI reference when you need an exact parameter or accepted value, and CLI examples when you want a worked recipe.

Control Integration and Events connects sliders, toggles and events to external actions. Third-party app integration describes the request/response and OSD protocols for developers. Advanced terminal preferences covers saved settings without a Settings interface.

The CLI, HTTP interface, custom URL scheme and distributed-notification interface share the same operations and parameters. Shortcuts provides a selected set of named actions. Control Integration works in the other direction: BetterDisplay sends an action to your equipment or another app when you adjust a control or a configured event occurs.

Enable and configure access

Open Settings > Application > Integration. Enable CLI access and notification based integration is on by default. Enable custom URL scheme access and Enable integrated HTTP server are off by default; enable the method your automation needs. BetterDisplay must be running to process integration requests.

The Integration settings article explains each switch and shows the configuration interface. Under Integration Settings…, you can set a Security token for HTTP and custom-URL requests and choose a Listening HTTP port. An empty port field uses 55777. Check the server's running-status message after enabling HTTP; a saved preference alone does not confirm that the server started.

If you set a token, include it as a token parameter in HTTP and custom-URL requests. The token is stored in the app's preferences and may be included in exported settings. URLs need percent encoding for spaces and other reserved characters; quoting the entire URL protects it from shell interpretation but does not replace URL encoding.

For example, after enabling the corresponding method, these requests set a display named Desk Display to 50% brightness:

open 'BetterDisplay://set?name=Desk%20Display&brightness=50%25'
curl 'http://localhost:55777/set?name=Desk%20Display&brightness=0.5'

Custom URL access also supports x-callback-url for reporting success, errors and results. HTTP can be addressed using the Mac's hostname when it is reachable from the requesting system; use your configured port and token. The CLI reference describes the common request syntax.

Try commands in the app console

Open Show Console to enter integration commands directly in BetterDisplay, without installing a companion tool. The App console article walks through help, display queries and adapting CLI recipes; the Console interface reference covers the window and its logging features.

Enabling Logging in the built-in app console is the simplest way to check BetterDisplay's diagnostic logs. For Apple's separate Console app and verbose Terminal output, see Enable macOS Console logging.

Set up command-line access

You can use the executable already inside the application bundle:

/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay help

For a shorter command, install the small betterdisplaycli companion. Its repository provides manual installation instructions, or install it with Homebrew:

brew install waydabber/betterdisplay/betterdisplaycli
betterdisplaycli help

The companion forwards requests to BetterDisplay; it does not replace the running app or its display controllers. Use CLI examples to identify a display and make your first request. In an automation that does not inherit your Terminal environment, use the full path to the app executable or to your installed companion.

Connect controls, events and feedback

Control Integration and Events explains how to use a script, URL or distributed notification for a display's brightness, volume, custom controls or connection and power events. This per-display configuration is separate from enabling incoming app-wide requests.

For an alternate brightness or volume overlay, enable Dispatch OSD notifications and configure the receiving app. Dispatch does not disable BetterDisplay's own overlays; see Third-party app integration for avoiding duplicate feedback and implementing a receiver.

Scripted license management

For managed deployments, use Scripted license management to activate or deactivate the app, list and remove remote activations, and hide license-management UI. These commands run through the app executable in a separate license-management mode; the article includes user-context guidance for root and MDM scripts.

Feature availability

Enabling an integration method does not unlock the requested feature. The same display, controller, permission, platform and licensing requirements still apply. The linked feature pages explain these requirements, and the CLI reference annotates individual operations. Query lists and current values before assuming that a display supports a particular mode or action.