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 suitable 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 switches an on/off state. perform runs an action. Lists and returned identifiers describe your current configuration, not universal values to copy from someone else's Mac.
Software and combined audio
Configure Software Audio before using its targets. For combinedVolume, also turn on its default-off Combined Volume Control feature and choose the Combined volume method in that same sheet. Generic volume and mute follow the selected providers. Explicit component names address only that component:
betterdisplaycli set -name="Desk Display" -volume=25
betterdisplaycli set -name="Desk Display" -control -specifier=softwareVolume -value=40
betterdisplaycli set -name="Desk Display" -control -specifier=hardwareVolume -value=20
betterdisplaycli set -name="Desk Display" -control -specifier=combinedVolume -value=15
betterdisplaycli set -name="Desk Display" -control -specifier=softwareMute -value=on
betterdisplaycli set -name="Desk Display" -control -specifier=softwareAudioGain -value=-6 -min=-24 -max=12
betterdisplaycli get -name="Desk Display" -control -specifier=softwareAudioGain -min=-24 -max=12
Advanced audio tuning requires Pro, including when configured through commands. Without Pro, its saved values remain readable and editable, but processing uses neutral values. Software volume and mute, Audio Gain and simple Bass and Treble remain free. See Software Audio feature availability for the complete list.
Ranged commands use the CLI's normal scaled range. Supplying -min=-24 -max=12 makes the gain example use its native decibel scale. Other tuning identifiers include softwareAudioBalance, softwareBass, softwareTreble, softwareEQ1kHz, softwareAudioCompressorEnabled and softwareAudioGateEnabled. Simple EQ applies softwareBass and softwareTreble directly; setting both to zero gives neutral EQ without an enable target. The menu’s Use 10-band EQ switch selects the separate ten-band settings. Image adjustment gain remains distinct from audio preamp gain. Commands do not add controllers or grant permission automatically.
Frequency filters use neutral values instead of separate enable targets. With native CLI ranges, set high-pass or notch frequency to 0 to bypass it. Low-pass uses 22000 as its neutral maximum; the menu displays this endpoint as ∞. For example, set a high-pass cutoff and then bypass it:
betterdisplaycli set -name="Desk Display" -control -specifier=softwareAudioHighPassFrequency -value=80 -min=0 -max=1000
betterdisplaycli set -name="Desk Display" -control -specifier=softwareAudioHighPassFrequency -value=0 -min=0 -max=1000
An explicit component edit may leave combined volume in the manual-component state. The next generic main-volume adjustment resumes its configured mapping. A configured route that has failed reports unavailability instead of switching to an unattenuated provider.
Custom menu bar icons
Choose a regular SF Symbol and an optional override for dark menu bar appearance. These settings apply to the whole app and need no display selector:
betterdisplaycli set -appMenuIcon=macpro.gen1
betterdisplaycli set -appMenuIconDark=macpro.gen1.fill
betterdisplaycli get -appMenuIcon
betterdisplaycli get -appMenuIconDark
The read commands return the saved symbol names, even when a status indicator currently takes priority. The dark override follows the menu bar’s appearance, which can differ from the system appearance depending on the wallpaper.
Clear the dark override to use the regular icon in both appearances. Clear the regular symbol to allow display or group matching, if enabled, or the usual BetterDisplay icon wherever the dark override does not apply:
betterdisplaycli set -appMenuIconDark=
betterdisplaycli set -appMenuIcon=
Either setting can also be used through HTTP, for example http://localhost:55777/set?appMenuIconDark=macpro.gen1.fill. See Menu Bar Icon settings for the symbol picker, invalid-name fallback and status-icon priority.
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. Use explicit hardware and software parameters 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 suitable 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.
Apple logo brightness
On supported MacBooks, these commands configure the built-in lid logo without a display selector. appleLogoControl enables the saved custom setting, and appleLogoBrightness uses a 0–1 scale or percentage, matching the Logo Light Strength slider. appleLogoRelativeControl enables Limit with Screen Brightness and defaults to off. With limiting off, the percentage sets a fixed light strength. With limiting on, 0.5 or 50% means half the brightness macOS would select.
betterdisplaycli set -appleLogoControl=on -appleLogoBrightness=10% -appleLogoRelativeControl=off
betterdisplaycli set -appleLogoRelativeControl=on -appleLogoBrightness=50%
betterdisplaycli get -appleLogoBrightness
betterdisplaycli toggle -appleLogoControl
betterdisplaycli set -appleLogoControl=off
Brightness and relative-mode changes do not enable Apple logo control by themselves. Settings can be saved while the lid is closed; custom brightness applies when the built-in display is awake, the lid is open and BetterDisplay is eligible to manage it. Turning Apple logo control off restores system brightness behavior. The persistent macOS logo on/off setting is unchanged. See Apple Logo for lifecycle and recovery behavior.
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. An incompatible monitor may not accept the commands.
Screen rotation
For a connected display with rotation support, choose an absolute angle or add an offset to its current orientation:
betterdisplaycli set -name="Desk Display" -rotation=90
betterdisplaycli set -name="Desk Display" -rotation=90 -offset
betterdisplaycli set -name="Desk Display" -rotation=-90 -offset
betterdisplaycli get -name="Desk Display" -rotation
Absolute angles are 0, 90, 180 and 270. With -offset, you can also use -90, -180 and -270. Relative rotation wraps around a full turn: adding 90 to 270 selects 0, and adding -90 to 0 selects 270.
A successful set request means BetterDisplay accepted the rotation request. It does not confirm that macOS or the display applied the change. Use a separate get request after the display settles to check its reported orientation.
Floating remotes
Use -remote to show, hide or query the floating remotes supplied by a display's configured controllers. Choose the display with the usual selectors and optionally add -specifier to choose a controller:
betterdisplaycli get -name="My TV" -configuredControllerList
betterdisplaycli set -name="My TV" -remote=on -specifier=TizenController
betterdisplaycli set -name="My TV" -remote=off -specifier=TizenController
betterdisplaycli toggle -name="My TV" -remote -specifier=TizenController
betterdisplaycli get -name="My TV" -remote -specifier=TizenController
The selector matches part of the controller type or displayed controller name, ignoring letter case. For example, TizenController identifies the Samsung controller. An unmatched selector does not fall back to another controller. If no eligible controller matches on any selected display, the operation fails.
Omit -specifier to address all remote-capable controllers on each selected display:
betterdisplaycli set -name="My TV" -remote=on
betterdisplaycli toggle -displayWithMouse -remote
betterdisplaycli get -name="My TV" -remote
set with on selects detached presentation and shows the matched remotes; off hides them while retaining that preference. For each display, toggle hides the matched remotes when all are open, otherwise opens the missing ones. get returns on only when all matched floating remotes on that display are open. Multiple eligible displays produce comma-separated results in the usual order. Disconnected displays and controllers without remotes are skipped.
Saved window positions take priority. A new window without a saved position opens on its affected display, even if the app menu is open on another screen. These commands do not require Pro.
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.
List the available refresh rates before selecting one, including unexposed NTSC timings on Apple silicon:
betterdisplaycli get -name="Desk Display" -refreshRateList
betterdisplaycli set -name="Desk Display" -refreshRate=23.976
betterdisplaycli set -name="Desk Display" -refreshRate="23,98 hz"
betterdisplaycli get -name="Desk Display" -refreshRate
Prefer the format shown by refreshRateList: 60Hz for a fixed integer rate, 23.98Hz for a fixed fractional rate, 40-120Hz for a VRR range, 120Hz-VRR for a VRR option specified by its maximum rate, or ProMotion when listed. Labels are case-insensitive, including Hz, VRR and ProMotion: 120hz-vrr and promotion work as well.
Numeric rates are matched to two decimal places, so the two set commands above both select 23.98Hz when available. Whitespace and unit labels are ignored, and decimal commas and Arabic decimal separators are accepted. The unit is optional for numeric rates. Quote values containing spaces. Keep the range or VRR marker when requesting a variable rate: 40-120Hz, 120Hz-VRR and fixed 120Hz identify different options. An unmatched rate returns failure; retaining the existing refresh rate does not count as success.
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. Select each separately when needed.
Color-profile favorites
Save the display’s current installed profile to a favorite slot, then apply that slot when needed:
betterdisplaycli set -name="Desk Display" -saveFavoriteColorProfile=1
betterdisplaycli set -name="Desk Display" -favoriteColorProfile=1
Both parameters accept an integer from 1 to 5 and use the same per-display slots as the Color Profile menu. Saving replaces the selected slot’s assignment without changing the active profile. The selected display must be connected and support color profiles. Applying an empty or unavailable slot fails, and a failed system profile change is reported as failure. Fractional or out-of-range slot values are rejected.
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.
Virtual-screen aspect components and multiplierStep accept parsed values from 1 to 16384. Serial, vendor and model configuration values accept 0 through 4294967295. Parsed custom-list dimensions must be positive and no greater than 16384, but creating modes still uses the active 7680 or 15360 pixel limit. Saving settings does not prove they were applied. If numeric validation rejects the saved configuration, an existing live desktop remains unchanged. See Virtual Screen settings for correction and reconnection.
When you no longer need this virtual screen, discard that specific screen:
betterdisplaycli discard -name=TestVirtual
Associate a virtual screen with a display
Use associated to get or set the relationship between one virtual screen and one physical display. The existing Association Settings determine automatic connection, mirroring, streaming and orientation behavior.
betterdisplaycli set -name="Virtual Ultrawide" -associated=on -targetName="Ultrawide"
betterdisplaycli get -name="Virtual Ultrawide" -associated -targetName="Ultrawide"
betterdisplaycli get -name="Virtual Ultrawide" -associatedDisplays
Select exactly one virtual screen and, for associated, provide a target selector matching exactly one physical display. Remembered disconnected displays are valid targets. targetTagID and targetUUID can replace targetName; tag IDs are useful in scripts because display names can change or match more than one device. Missing, unmatched or ambiguous selectors fail before accompanying connection changes. Setting an association requires Pro; both queries are available without Pro.
The pair query returns on or off. associatedDisplays returns a JSON array sorted by tag ID, including disconnected displays and saved fallback names for unavailable identities. An empty list returns []. For example:
[
{ "tagID": 1234, "name": "Ultrawide" }
]
To switch from virtual-screen mirroring to the physical screen for gaming, remove that association and disconnect the virtual screen in one command. Restore the association afterward:
betterdisplaycli set -name="Virtual Ultrawide" -associated=off -targetName="Ultrawide" -connected=off
betterdisplaycli set -name="Virtual Ultrawide" -associated=on -targetName="Ultrawide"
Association changes run before accompanying connected changes regardless of parameter order. Each set request then schedules the normal configuration pass to apply the saved Association Settings. With Auto-connect virtual screen and Enforce virtual screen mirroring enabled, restoring the association reconnects and restores mirroring when the physical display is available. If it is unplugged, the saved association takes effect when it returns. Removing an association alone keeps the virtual screen's current connection state; other associations remain saved and can still enforce their automatic rules.
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.
Use get to read whether a protection is enabled. The result is on when a setting is protected and off otherwise. HDR protection can be enabled while HDR itself is off. Main-display protection reports on only for the display with the current protection assignment.
betterdisplaycli get -name="Desk Display" -protectResolution
betterdisplaycli get -name="Desk Display" -protectAll
betterdisplaycli toggle -name="Desk Display" -protectAll
For protectAll, on means at least one protection is enabled. Toggling removes all protections when any are enabled, or enables all available protections when none are enabled.
On supported Apple silicon displays, protectSDRColorMode and protectHDRColorMode protect the color mode. Enable each while the display is in the corresponding SDR or HDR state. For example, with the display in SDR:
betterdisplaycli set get -name="Desk Display" -protectSDRColorMode=on
betterdisplaycli toggle get -name="Desk Display" -protectSDRColorMode
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. Leave the specifier out to use 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.
For window priority, use -priority=normal, -priority=topmost or -priority=absolute. These correspond to the PIP priority choices. The legacy value absoluteLockScreen sets absolute and enables Show on Lock Screen; a subsequent get -priority returns absolute, even for an inactive configuration. The same rule applies to -videoFilterWindow and -contentStreamWindow. Other priority values preserve the separate saved lock-screen option, which takes effect at absolute priority; use the window's menu to turn that option off.
Align and size a window
Use alignX and alignY to place the whole window relative to its target screen. For either axis, 0 centers the window. Horizontal values -1 and 1 align its left and right edges. Vertical values -1 and 1 align its top and bottom edges. For example, center a window horizontally at the top of the screen:
betterdisplaycli set -name="Desk Display" -pip -height=40% -alignX=0 -alignY=-1
betterdisplaycli set -name="Desk Display" -pip -alignX=1 -alignY=1
betterdisplaycli get -name="Desk Display" -pip -alignX -alignY
The second command places it at the bottom right. BetterDisplay calculates the final dimensions, including any aspect-ratio correction and title bar, before applying alignment. Coordinates refer to the full screen rectangle and outer window frame. Alignment is spatial and keeps the same meaning in every interface language.
Finite values beyond -1 and 1 continue the same positioning calculation: alignX=1.5 moves a window a quarter of the remaining horizontal space past right alignment. It does not always put half of the window offscreen. macOS can constrain the requested placement.
Width and height are fractions of the target screen dimensions. Values above 1 or 100% allow oversized windows. To cover two equal, horizontally adjacent desktops with a window starting at the left screen's top-left corner, select that screen as the target and allow free proportions:
betterdisplaycli set -name="Desk Display" -pip -targetName="Left Display" -freeAspect=on -width=200% -height=100% -alignX=-1 -alignY=-1
The two desktops need matching logical dimensions and adjacent edges for this rectangle to cover both exactly. On an axis exactly matching the screen size, alignment cannot offset the window, so use an origin command for that offset. For oversized windows, increasing alignment moves in the opposite coordinate direction while still matching the named edges at -1 and 1. macOS window constraints still apply. The same geometry parameters work with -videoFilterWindow, whose proportions are already freely resizable. A geometry command also updates a stopped window's saved placement.
Existing originX and originY commands retain their meaning: they place the window's bottom-left corner at a fraction of the screen width and height. An explicit origin overrides saved alignment on that axis. You can mix originX with alignY, but cannot supply both origin and alignment for the same axis in one command. Non-numeric and non-finite geometry values are rejected.
Moving or resizing a window saves both origins and suitable alignment values. Each axis retains alignment only when the window is smaller than the screen on that axis and the calculated alignment is between -2 and 2, inclusive. Otherwise that saved alignment is removed and the origin is used as fallback. A query returns none for an axis using origin fallback. Explicit alignment outside this persistence range still places the window before saving its actual origin.
Saving through either method preserves the current position. On later restoration or a change of screen geometry, suitable saved alignment keeps the corresponding edges or centers aligned. Full-size, oversized and extreme-offset axes use their saved screen-relative origins. Older configurations acquire alignment automatically when their positions are next saved. See Picture in Picture for the window actions.
Screen streaming
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 reference explains 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.
Audio mute
Mute uses the display’s configured audio controller, including native audio, network controllers and DDC. A controller with a Boolean mute control supports setting, toggling and reading its tracked state:
betterdisplaycli set -name="Desk Display" -mute=on
betterdisplaycli set -name="Desk Display" -mute=off
betterdisplaycli toggle -name="Desk Display" -mute
betterdisplaycli get -name="Desk Display" -mute
If the controller provides only a mute-toggle command, use toggle. Setting an explicit On or Off state and reading the mute state are unavailable for that controller. Configure the display’s audio controller under Device Control; the Audio Device Configuration settings describe audio-device matching and controller-specific mute behavior.
Show an on-screen display
Use perform -osd to display on-screen display (OSD) feedback for an external sound system, a script or another automation. The command presents a value without changing the display or audio setting. Use -specifier to choose the preset and optional appearance settings.
betterdisplaycli perform -osd
betterdisplaycli perform -osd=70%
betterdisplaycli perform -osd=42% -specifier=volume
betterdisplaycli perform -osd -specifier=mute
betterdisplaycli perform -osd=on -specifier=mute
betterdisplaycli perform -osd=off -specifier=mute
The default preset is brightness. Without a supplied value, brightness, volume and mute use the current tracked value or existing fallback when available. Otherwise the preset icon appears without a level. Mute accepts on/off or 1/0 as the state to show.
Without display selectors, brightness uses the configured keyboard brightness targets and volume/mute use the configured keyboard audio targets. If no target is available, the presentation is display-less. Native audio can supply its current value when native fallback is enabled. Explicit selectors such as -name, -tagID and -displayWithMouse select the affected display. The OSD location preference still determines where feedback appears.
betterdisplaycli perform -osd=42% -specifier=volume -displayWithMouse
betterdisplaycli perform -osd=0.7 -name="Desk Display"
betterdisplaycli perform -osd=42 -max=100 -specifier=volume
betterdisplaycli perform -osd -value=42% -specifier=volume
Numeric input defaults to 0...1, so 42% equals 0.42. The standard -min and -max parameters map another finite increasing range onto the level bar. Explicit values must lie within that range. The automatic label shows a percentage when the current-value preference is enabled.
Custom OSD content and appearance
Composite specifiers require a companion built from the current betterdisplaycli source or the executable inside the app bundle. The released v1.0.1 companion truncates parameter values at additional equals signs, so quoted composite options do not reach BetterDisplay intact.
A specifier can start with brightness, volume, mute or custom, followed by comma-separated key=value options. Other registered control target names, such as contrast, can supply their usual icon and tracked value. A specifier containing only named options still defaults to brightness.
betterdisplaycli perform -osd=42% \
-specifier='volume,style=classic,icon=hifispeaker.fill,text="Living room, 42%"'
betterdisplaycli perform -osd \
-specifier='custom,icon=checkmark.circle.fill,text=Connected'
betterdisplaycli perform -osd=-35 -min=-80 -max=0 \
-specifier='volume,text=-35 dB,style=topCenter'
icon supplies a primary SF Symbol name. text supplies literal text in place of the automatic numeric label. title replaces the display/device title where the style shows it. The custom preset can show an icon and text without a value or a selected display.
style accepts underMenu, classic, topRight, topCenter, bottomCenter, underMenuBar, liveActivity, traditionalSystem and forcedSystem. liveActivity requires macOS 27.3 and falls back to underMenu on earlier versions. It is read-only and uses system-managed placement, with optional values and device names below the meter in its expanded view. forcedSystem follows the existing macOS compatibility fallback. The options rounded, adaptive, segmented, shadow, showDeviceName and showValue accept on/off. Names are case-insensitive. These options use the same style-specific behavior as the OSD preferences.
betterdisplaycli perform -osd=60% \
-specifier='volume,style=topCenter,rounded=on,segmented=off,shadow=on'
betterdisplaycli perform -osd=42% \
-specifier='volume,style=topCenter,title=Living room,showDeviceName=on,rounded=on'
Quote the whole composite argument for the shell. Within it, quote values containing commas or quote characters and escape literal quotes or backslashes with a backslash. For example, -specifier='custom,icon=checkmark.circle.fill,text="Receiver says \"Ready\", A=B"' keeps the punctuation in the message. Unknown options, duplicate keys and malformed values fail.
Omitted appearance options use current preferences without changing them. A visible BetterDisplay OSD on the destination receives the new content and retains its style and rounded shape until it hides. Wait for it to disappear before trying a different style. CLI-supplied levels are read-only. Existing visibility preferences and open-menu suppression apply. Traditional and System OSD receive the supported built-in icon and level and ignore custom text and appearance fields. A purely custom preset has no native-system equivalent.
Use perform with osd as the only feature. Relative -offset requests are not supported.
Custom controls
Use a control's CLI designation as specifier. This identifier may differ from the control’s displayed name. 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.
Apply group layout protections
The saved Apply Automatically preference is shared by all groups, Settings, the app menu and CLI. It is also available in Settings > Groups > Overview > Advanced…. With this Pro feature enabled, set -enabled=on/off and toggle -enabled reapply active groups' available layout protections after group activations are recalculated. Other CLI group settings, such as activationPolicy, also reapply protections if they change which groups are active. Get, set or toggle the preference without a group selector:
betterdisplaycli get -autoApplyLayoutProtection
betterdisplaycli set -autoApplyLayoutProtection=on
betterdisplaycli set -autoApplyLayoutProtection=off
betterdisplaycli toggle -autoApplyLayoutProtection
Add get to a set or toggle request to return the resulting on or off value:
betterdisplaycli set get -autoApplyLayoutProtection=on
betterdisplaycli toggle get -autoApplyLayoutProtection
Changing this preference alone does not apply protections. To apply all active groups' enabled positioning and main-display protections now, regardless of the automatic preference, use:
betterdisplaycli perform -applyLayoutProtection
You can also enable a group and explicitly apply protections in one request:
betterdisplaycli set perform -name="Layout 2" -enabled=on -applyLayoutProtection
The group name selects which group is enabled. The apply command is global and is not restricted by device or group selectors. It runs once after all settings changes and group activations, regardless of argument order or whether automatic application is also enabled. Separate CLI requests each have their own application step. Applying respects active groups' eligibility and priority rules; it does not enable a group's disabled layout protection or reconnect a missing display.
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. Screen rotation and saving or applying color-profile favorites require Pro. 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.