Advanced terminal preferences

Some BetterDisplay preferences have no Settings interface. You can change them with macOS's defaults command when you need a specific streaming or activation behavior. These are persistent app preferences, separate from the commands sent to a running app through betterdisplaycli.

Read, change and restore a preference

Quit BetterDisplay before writing a preference, then reopen it so the app loads the saved value. The commands below use the standard app's preferences domain, pro.betterdisplay.BetterDisplay.

To inspect a saved override:

defaults read pro.betterdisplay.BetterDisplay pipShowResizePercent

A missing-key message means there is no explicitly saved value for that key; the app uses its built-in default. To remove only that override and return to the app's default:

defaults delete pro.betterdisplay.BetterDisplay pipShowResizePercent

Substitute the exact key you changed. Keep the key on a defaults delete command: deleting the whole preferences domain would remove unrelated settings too. An explicit value persists across launches and can override a changed default in a future version.

Picture in Picture resize feedback

Hide the percentage information shown while resizing a sufficiently large PIP window:

defaults write pro.betterdisplay.BetterDisplay pipShowResizePercent -bool NO

The default is YES. The preference affects the resize overlay, not the PIP size itself. Use -bool YES to enable it explicitly or delete the key to restore the default.

Automatically move the pointer to the source

Enable pointer auto-warp separately for PIP and full-screen stream targets:

defaults write pro.betterdisplay.BetterDisplay pipAutoWarp -bool YES
defaults write pro.betterdisplay.BetterDisplay screenStreamAutoWarp -bool YES

Both default to NO. When the pointer moves over a supported stream view, BetterDisplay translates its position to the source display and moves it there, so you can interact with the source instead of remaining over its streamed image. The PIP path avoids this while the left mouse button is pressed for dragging. Selected-content windows, video-filter windows and self-streams do not use this hover behavior.

Because the pointer leaves the streamed view, this can feel different from ordinary window interaction. Disable the corresponding key or delete it if you prefer to keep the pointer on the target.

Hide the screen-stream pointer halo

Disable the dashed-circle mouse halo on screen-stream targets:

defaults write pro.betterdisplay.BetterDisplay screenStreamMouseHalo -bool NO

The default is YES. This affects the hover indicator, not the pointer auto-warp preference above or the stream's captured-cursor setting.

Activation with an older license

The following preference changes how the app handles an otherwise valid license whose update eligibility does not cover the current app version:

defaults write pro.betterdisplay.BetterDisplay disallowActivationWithOutdatedLicense -bool NO

The default is YES. With the default behavior, the activation path deactivates an out-of-date license and presents the expiry error. With NO, it retains that activation and presents the expiry-related notification instead. This does not extend the license's update eligibility or replace license verification. See Pro for normal activation and license management.

Temporary system-sleep prevention

Disable the app's temporary system-sleep prevention used around operations such as EDID work:

defaults write pro.betterdisplay.BetterDisplay disablePreventSystemSleep -bool YES

In the current app version this already defaults to YES, so the command usually makes the default explicit. It affects the temporary system-sleep assertion mechanism, not the separate per-display Prevent Display Sleep feature. Delete the key to follow future app defaults instead of pinning this value.

Historical slider-reveal animation setting

Older versions offered this terminal-only opt-in:

defaults write pro.betterdisplay.BetterDisplay sliderRevealAnimation -bool YES

It re-enabled the animation used when app-menu sliders appeared. The current app source no longer reads this key, so it is retained here only to explain existing scripts and migrated settings; it has no documented effect in the current version. To remove an old saved override, quit the app and run:

defaults delete pro.betterdisplay.BetterDisplay sliderRevealAnimation

Additional information

This section explains availability and compatibility for these preferences.

Features requiring Pro license

Writing a preference does not unlock a licensed feature. PIP and screen streaming retain their own feature requirements. The activation preference changes handling of a license state, not the license entitlement.

Platform compatibility

These preferences use the same keys on Apple silicon and Intel Macs. Their effects depend on the associated feature being available. The slider-reveal key is historical and is not implemented in the reviewed app version.