CLI examples

Use these examples to build repeatable display setups, bind an adjustment to a key, or combine BetterDisplay with another automation tool. Each section starts with a task and shows how to discover the values your own displays support before changing them.

Before your first command

Set up the companion or application-bundle executable as described in the Integration overview. BetterDisplay must be running with CLI access enabled. Examples use betterdisplaycli; the app executable accepts the same operations and parameters.

Replace Desk Display, Second Display, MyVirtual and other sample names with your own. Quote names containing spaces. Display selectors use the name shown by BetterDisplay, so the built-in screen is normally Built-in Display, not the panel's hardware model name. A command without a device selector can affect every eligible device. Use an exact -name or a stable identifier when that is not your intention.

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

Use -nameLike=Desk for a substring match, -displayWithMouse for the display under the pointer, and the CLI reference for other selectors. A substring can match several displays. set assigns a value; get reads it; toggle inverts a Boolean state; perform invokes an action. Lists and returned identifiers describe your current configuration, not universal values to copy from someone else's Mac.

Brightness and HTTP requests

Set one display to 80%, or change the display under the pointer by ten percentage points:

betterdisplaycli set -name="Desk Display" -brightness=80%
betterdisplaycli set -displayWithMouse -brightness=-10% -offset
betterdisplaycli set -displayWithMouse -brightness=10% -offset

The offset examples are useful in keyboard tools such as Hammerspoon. Omitting -offset requests an absolute value instead. The app chooses the appropriate brightness method; explicit hardware and software parameters are available when you need a particular method.

With HTTP access enabled, the same operations can be sent to the configured port. The first request sets one display; the second deliberately affects all eligible displays:

curl 'http://localhost:55777/set?name=Desk%20Display&brightness=0.8'
curl 'http://localhost:55777/set?brightness=0.8'
curl 'http://localhost:55777/set?displayWithMouse&brightness=-0.1&offset'

Add your token parameter when one is configured. Quoted URLs prevent & and ? from being interpreted by the shell.

Direct DDC and input switching

Direct DDC addresses the monitor's VCP commands, independently of the normalized brightness interface. The following sets luminance to the device value 50; hexadecimal 0x10 and 0x32 are the equivalent VCP code and value:

betterdisplaycli set -name="Desk Display" -feature=ddc -vcp=luminance -value=50
betterdisplaycli set -name="Desk Display" -feature=ddc -vcp=0x10 -value=0x32
betterdisplaycli get -name="Desk Display" -ddc -vcp=luminance -value -max
curl 'http://localhost:55777/set/get?name=Desk%20Display&feature=ddc&vcp=luminance&value=30&min&max'

The read request returns the current and maximum values. The combined HTTP request writes 30, then reads the current, minimum and maximum values; the DDC minimum is represented as zero. Check the monitor's range rather than assuming every VCP uses 0–100.

For a display whose documented input code 15 selects DisplayPort:

betterdisplaycli set -name="Desk Display" -ddc=15 -vcp=inputSelect
curl 'http://localhost:55777/set?name=Desk%20Display&ddc=15&vcp=inputSelect'

Input values vary by monitor. Some LG models use alternate addressing: use -ddcAlt with -vcp=inputSelectAlt and that monitor's supported value. Changing input can remove the image from this Mac. Prefer the configured controller's input selection when available:

betterdisplaycli get -name="Desk Display" -inputSourceList
betterdisplaycli perform -name="Desk Display" -changeInputSource="INPUT_ID"

Replace INPUT_ID with an entry from the list and use -specifier to select the controller if needed. See Input Source and DDC for device requirements.

BetterDisplay's DDC CLI can serve as an alternative to m1ddc, using the connection support available through BetterDisplay, including paths outside m1ddc's scope. It requires the running BetterDisplay app and an enabled, supported DDC controller; it cannot make an incompatible monitor accept commands.

Display modes and HiDPI

Start with the display's mode list, then choose a mode number returned by that list or describe the mode you want:

For the difference between desktop dimensions and rendering detail, see macOS scaling, HiDPI and LoDPI.

betterdisplaycli get -name="Desk Display" -displayModeList
betterdisplaycli get -name="Desk Display" -displayModeNumber
betterdisplaycli set -name="Desk Display" -displayModeNumber=338
betterdisplaycli set -name="Desk Display" -resolution=1920x1080
betterdisplaycli set -name="Desk Display" -hiDPI=off
betterdisplaycli toggle -name="Desk Display" -hiDPI
betterdisplaycli get -name="Desk Display" -colorDepth
betterdisplaycli set -name="Desk Display" -refreshRate=120Hz
betterdisplaycli set -name="Desk Display" -resolution=1600x1000 -hiDPI=on -colorDepth=10 -refreshRate=120Hz

Here 338 is illustrative: substitute a mode number from your display's list. The combined request finds a matching available mode; it does not create a new resolution or make an unsupported refresh rate available. Review Display Mode for scaling and refresh-rate behavior.

Color profiles and Apple Display Presets

Discover an installed profile URL, read the current selection, assign the desired profile or restore the factory profile:

betterdisplaycli get -installedColorProfileURLs
betterdisplaycli get -name="Desk Display" -colorProfileURL
betterdisplaycli set -name="Desk Display" -colorProfileURL="file:///Users/yourname/Library/ColorSync/Profiles/Custom.icc"
betterdisplaycli perform -name="Desk Display" -colorProfileReset

Use a real URL returned by the profile list. On a display with Apple Display Presets, list the presets before selecting a name:

betterdisplaycli get -name="Built-in Display" -xdrPresetList
betterdisplaycli get -name="Built-in Display" -xdrPreset
betterdisplaycli set -name="Built-in Display" -xdrPreset="HDR Video (P3-ST 2084)"
betterdisplaycli set -name="Built-in Display" -xdrPreset="BetterDisplay XDR"
betterdisplaycli perform -name="Built-in Display" -xdrPresetReset

The two names are examples, including the BetterDisplay XDR upscaling preset where available. They must exist for the selected display. A color profile and an Apple Display Preset are different settings; selecting one is not a substitute for selecting the other.

Create and manage virtual screens

Create a virtual screen with a 12:10 aspect ratio, connect it and give it a new name:

betterdisplaycli create -deviceType=virtualScreen -virtualScreenName=MyVirtual -aspectWidth=12 -aspectHeight=10
betterdisplaycli set -name=MyVirtual -connected=on
betterdisplaycli set -name=MyVirtual -virtualScreenName=TestVirtual

name selects the existing device; virtualScreenName changes its name. The equivalent distinction applies to identification fields such as serial, model and vendor values versus their virtual-screen configuration parameters.

When you no longer need this virtual screen, discard that specific screen:

betterdisplaycli discard -name=TestVirtual

Arrange displays and configure mirroring

Move Second Display relative to Desk Display, or assign coordinates in logical pixels:

betterdisplaycli perform -name="Second Display" -moveTo=bottomLeftCorner -targetName="Desk Display"
betterdisplaycli set -name="Second Display" -placement=1920x0

moveTo accepts edge, alignment and corner positions such as left, rightTop, bottom and bottomLeftCorner; the reference lists all sixteen. The target selector identifies the anchor display. Coordinate placement instead uses the global display-layout space.

Mirror the source to one or more targets, query the state, and turn mirroring off:

betterdisplaycli set -name="Desk Display" -mirror=on -targetName="Second Display"
betterdisplaycli set -name="Desk Display" -mirror=on -targetName="Second Display,Third Display"
betterdisplaycli get -name="Desk Display" -mirror
betterdisplaycli set -name="Desk Display" -mirror=off

The source and target have distinct roles. Check the selected displays before applying an arrangement that changes where windows and the pointer appear.

Protect a display configuration

Protection records and maintains selected aspects of the display configuration. Set up the display as intended first, then enable the relevant protection:

betterdisplaycli set -name="Desk Display" -protectAll=on
betterdisplaycli set -name="Desk Display" -protectResolution=on
betterdisplaycli toggle -name="Desk Display" -protectRefreshRate
betterdisplaycli set -name="Desk Display" -protectHDR=off
betterdisplaycli set -name="Desk Display" -protectAll=off

Individual protection parameters also include protectRotation, protectAsMain, protectSDRProfile and protectHDRProfile. Use set ...=off for a definite off state; toggle depends on the current state. Protection can counteract later mode changes, so review enabled protections when an automated setup does not remain as requested.

Picture in Picture and screen streaming

Start or stop a Picture in Picture window for the source display:

betterdisplaycli set -name="Desk Display" -pip=on
betterdisplaycli set -name="Desk Display" -pip -targetName="Second Display"
betterdisplaycli set -name="Desk Display" -pip -originX=20% -originY=40%
betterdisplaycli set -name="Desk Display" -pip -width=50% -height=50%
betterdisplaycli set -name="Desk Display" -pip -rotateBy=90 -alpha=80% -showTitlebar=off
betterdisplaycli set -name="Desk Display" -pip -rotateBy=180 -specifier=2
betterdisplaycli set -name="Desk Display" -pip=off

A bare -pip selects PIP configuration for the other supplied parameters. -specifier=2 addresses the second saved PIP configuration; leaving the specifier out uses configuration 1. The position and size examples use normalized percentages. Other PIP options include aspect ratio, horizontal/vertical flipping, cursor visibility, cropping, priority, shadow and automatic startup.

A screen stream sends the source image to a target display:

betterdisplaycli set -name="Desk Display" -stream=on -targetName="Second Display"
betterdisplaycli set -name="Desk Display" -stream -rotateBy=90 -zoom=80% -flipHorizontal=on -verticalLocation=bottom
betterdisplaycli set -name="Desk Display" -stream=off

Streaming options also include direct pixel mapping, horizontal alignment, underscan, crop coordinates and size, cursor visibility and resume behavior. Configure capture permissions and the source/target setup first; the Streaming explain these features.

Stream video filters

Use videoFilter with pip, stream, videoFilterWindow or contentStreamWindow to address that output's video filters. These differ from display-wide image adjustments:

betterdisplaycli set -name="Desk Display" -pip -specifier=2 -videoFilter=brightness -value=0.2
betterdisplaycli toggle -name="Desk Display" -videoFilterWindow -videoFilter=invert
betterdisplaycli set -contentStreamWindow -videoFilter="custom:Film Look" -value=on
betterdisplaycli set -name="Desk Display" -pip -videoFilter="brightness=0.2,contrast=0.5,invert=on,custom:Film Look=on"
betterdisplaycli set -name="Desk Display" -pip -videoFilter="brightness=-10%,contrast=+0.2" -offset

The selected-content window is app-wide, so that example has no display selector. Film Look stands for an existing custom filter with that name. A comma-separated assignment configures multiple filters in one request; -offset treats numeric assignments as changes to current values. Use values appropriate to each filter's range. The reference lists accepted filters and output-specific parameters.

Custom controls

Use a control's CLI designation as specifier; its display label is not necessarily that identifier. For an existing ranged control called customRanged:

betterdisplaycli get -name="Desk Display" -control -specifier=customRanged
betterdisplaycli set -name="Desk Display" -control=30% -specifier=customRanged
betterdisplaycli feed -name="Desk Display" -control=50% -specifier=customRanged

set invokes the configured setter. feed supplies a value learned elsewhere without invoking that setter, which is useful for device-originated feedback. A Boolean control can be queried, set, toggled or fed:

betterdisplaycli get -name="Desk Display" -control -specifier=customToggle
betterdisplaycli toggle -name="Desk Display" -control -specifier=customToggle
betterdisplaycli set -name="Desk Display" -control=off -specifier=customToggle
betterdisplaycli feed -name="Desk Display" -control=on -specifier=customToggle

For a command control, invoke its default parameter or provide an explicit one:

betterdisplaycli perform get -name="Desk Display" -control -specifier=customCommand
betterdisplaycli perform get -name="Desk Display" -control=4 -specifier=customCommand

See Control Integration and Events for creating these controls and configuring readback.

EDID configuration

Read the stored custom EDID, the EDID reported by macOS and the EDID read through I²C:

betterdisplaycli get -name="Desk Display" -customEDID
betterdisplaycli get -name="Desk Display" -osEDID
betterdisplaycli get -name="Desk Display" -i2cEDID

These are different sources and may return different data. On a supported configuration, supply a complete valid base64 EDID to store it, then apply it separately:

betterdisplaycli set -name="Desk Display" -customEDID="COMPLETE_BASE64_EDID"
betterdisplaycli perform -name="Desk Display" -applyCustomEDID
betterdisplaycli get -name="Desk Display" -autoApplyCustomEDID
betterdisplaycli set -name="Desk Display" -autoApplyCustomEDID=on

COMPLETE_BASE64_EDID is a placeholder, not usable EDID data. To stop automatic application, restore factory EDID and clear the stored custom value:

betterdisplaycli set -name="Desk Display" -autoApplyCustomEDID=off
betterdisplaycli perform -name="Desk Display" -applyFactoryEDID
betterdisplaycli set -name="Desk Display" -customEDID

Connection color modes

On supported natively connected displays on Apple silicon, connection modes describe the negotiated bit depth, RGB/YCbCr encoding, chroma subsampling and range. They differ from ordinary logical display-mode selection.

betterdisplaycli get -name="Desk Display" -connectionMode
betterdisplaycli get -name="Desk Display" -connectionModeList
betterdisplaycli get -name="Desk Display" -preferredConnectionMode
betterdisplaycli set -name="Desk Display" -connectionMode="bpc:8+range:full+encoding:rgb"

Use a compatible mode number returned by connectionModeList, or describe the desired combination as above. Omitted components retain their current values, and the descriptive form requires a suitable compatible mode. The system's preferred mode is the one macOS selects for the current resolution, refresh rate and SDR/HDR configuration.

get -connectionModeListAll exposes the wider low-level list, including modes incompatible with the current configuration. Selecting arbitrary numbers from that list can disrupt the image; prefer the compatible list and review Color Mode before changing the connection.

Display groups

Find a group's name and stable tag ID, then distinguish whether it is enabled from whether its activation conditions are currently met:

betterdisplaycli get -type=displayGroup -identifiers
betterdisplaycli get -name="Desk Group" -identifier=tagID
betterdisplaycli get -tagID=123 -identifier=name
betterdisplaycli set -name="Desk Group" -enabled=on
betterdisplaycli get -name="Desk Group" -enabled
betterdisplaycli get -name="Desk Group" -active
betterdisplaycli toggle -name="Desk Group" -enabled
betterdisplaycli set -name="Desk Group" -enabled=off

Replace 123 with the returned tag ID. Choose an activation policy and configure the group's features:

betterdisplaycli set -name="Desk Group" -activationPolicy=allMembersPresent
betterdisplaycli get -name="Desk Group" -activationPolicy
betterdisplaycli set -name="Desk Group" -synchronization=on
betterdisplaycli set -name="Desk Group" -layoutProtection=off
betterdisplaycli toggle -name="Desk Group" -uiScaleMatching
betterdisplaycli get -name="Desk Group" -uiScaleMatching

Other policies are anyMembersPresent, anyTwoMembersPresent and anySyncSourceWithTargetMembersPresent. Enabling a group does not by itself satisfy its membership policy. Create its membership and relationships in Display Groups before automating its state.

Sidecar connections

List available Sidecar devices and use a returned name or UUID:

betterdisplaycli get -sidecarList
betterdisplaycli set -sidecarConnected=on -specifier="My iPad"
betterdisplaycli get -sidecarConnected -specifier="My iPad"
betterdisplaycli toggle -sidecarConnected -specifier="My iPad"
betterdisplaycli set -sidecarConnected=off -specifier="My iPad"

Use the device's UUID as the specifier when names collide. These commands request a Sidecar connection; the Mac and iPad must meet Sidecar's own availability and connection requirements.

Additional information

This section explains how licensing and compatibility affect these examples.

Features requiring Pro license

Requests retain their underlying feature requirements. Examples involving virtual-screen configuration, Picture in Picture and streaming, custom controls, configuration protection, display groups, EDID overrides and advanced image or display adjustments can require Pro. The CLI reference annotates individual parameters; the linked feature pages describe applicable free alternatives and controller-specific conditions.

Platform compatibility

The CLI works on both Apple silicon and Intel Macs. DDC, Apple Display Presets, supported modes and input selection depend on the device and controller. Connection color-mode operations and custom EDID application require supported Apple silicon display paths. Streaming requires the relevant capture permissions, and Sidecar requires a compatible Mac/iPad setup.