App console

BetterDisplay's built-in console lets you try integration commands and read their responses inside the app. It is a convenient place to discover a display's identifiers, inspect available settings and develop a command before using it in a script or shortcut.

Open Show Console

Choose App Menu > Tools > Show Console, or right-click BetterDisplay's menu-bar icon and choose Show Console. You can also assign a Show console keyboard shortcut. The Console interface reference shows the window and explains its input, history, logging and clearing features.

The console processes requests directly inside BetterDisplay. You do not need to install betterdisplaycli or enable an external CLI, HTTP or custom-URL access method to use it. Requested features still need their usual display, controller, permission and license requirements.

Start with help and a read-only request

Type a command after the > prompt and press Return. Do not type the prompt character itself. Begin with:

help

The app shows help for its installed version, including console-specific syntax. To look up just one operation or parameter, narrow the request:

help get
help -brightness

Next, list device identifiers and read one display's brightness:

get -identifiers
get -name="Desk Display" -brightness

Enter each line as a separate request, replacing Desk Display with a name from your own device list. A name containing spaces needs quotes. A request without a device selector can affect every eligible device, so choose the intended display before trying a command that changes anything.

Use CLI recipes in the console

The console accepts the same integration operations and parameters as the CLI. Omit the executable name: where a Terminal example begins with betterdisplaycli or /Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay, start directly with the operation instead.

For example, this Terminal command:

betterdisplaycli set -name="Desk Display" -brightness=50%

becomes this console command:

set -name="Desk Display" -brightness=50%

That request changes the selected display's brightness. To set it and read the resulting value in one request, combine the operations:

set get -name="Desk Display" -brightness=50%

Use the CLI examples for task recipes and the CLI reference for the full operation and parameter list. The built-in help output is the best match for the app version you are actually running.

Console accepts single or double hyphens before parameter names. Whitespace separates arguments; single or double quotes keep text containing spaces together, and a backslash escapes the next character. These parsing rules do not make it a system shell: commands such as curl, defaults or brew, shell pipes, redirection and shell scripts belong in Terminal or an appropriate scripting tool.

Read the response and refine the command

A query prints its returned values above the next prompt. A successful action with no returned payload can simply show a new prompt. Failed. indicates that the operation did not succeed; an additional explanation may follow. Check the selected device, parameter value and feature availability before retrying. Failed. Unclosed quote. means a quoted argument was not closed.

Use Up and Down to recall earlier commands and edit them. Moving past the newest stored command restores the draft you were typing. Consecutive duplicates occupy one history entry, and up to 1,000 commands are retained for the current app session. Copy a finished command into your script or notes if you want to keep it after restarting BetterDisplay.

Only the current prompt is editable. Earlier results can be selected and copied. An operation's response describes the app's handling of the request; for hardware actions, check the actual device state too.

Logging, clearing and closing

The built-in app console is the simplest way to check BetterDisplay's logs. It is separate from Apple's macOS Console app; see Enable macOS Console logging to view the same diagnostic messages in the system log or send them to Terminal.

Enable Logging when you need diagnostic details alongside command responses. It is off by default and its preference is remembered. Incoming log lines preserve the command you are typing. Logs are kept in a bounded in-memory buffer, so older entries can be trimmed; the console is not a permanent log archive.

Two operations are specific to the app console:

The Clear Console trash button also clears output immediately, without a confirmation. Closing the window normally has the same effect as exit. These commands do not print an additional result, and they are not external CLI operations.

For a focused diagnostic report, clear the console, enable Logging, reproduce the relevant behavior and copy the useful portion of the output. Review it for device identifiers and command values before sharing. See the Console interface reference for the detailed logging behavior.

Additional information

This section explains licensing and platform requirements.

Features requiring Pro license

Opening the console, reading help, using history, logging and clearing output do not require Pro. Commands keep the license requirements of the features they request.

Platform compatibility

The console is available on both Apple silicon and Intel Macs. Individual operations can require a particular display, controller, macOS capability or processor architecture.