### Install BetterDisplay CLI

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Use Homebrew to install the command line interface for easier access.

```bash
brew install waydabber/betterdisplay/betterdisplaycli
```

--------------------------------

### Install and Access BetterDisplay CLI

Source: https://context7.com/waydabber/betterdummy/llms.txt

Install the command-line interface via Homebrew or execute the binary directly from the application bundle.

```bash
# Install betterdisplaycli via Homebrew
brew install waydabber/betterdisplay/betterdisplaycli

# Alternative: use the app binary directly
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay help
```

--------------------------------

### Install BetterDisplay via Homebrew

Source: https://github.com/waydabber/betterdummy/blob/landing/README.md

Use this command to install the BetterDisplay application using the Homebrew package manager.

```bash
brew install --cask betterdisplay
```

--------------------------------

### Access help via betterdisplaycli

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Displays help information using the installed betterdisplaycli utility.

```bash
betterdisplaycli help
```

--------------------------------

### Manage Virtual Screens

Source: https://context7.com/waydabber/betterdummy/llms.txt

Create, configure, and manage virtual displays for headless setups or custom resolution requirements.

```bash
# Create a virtual screen with 16:9 aspect ratio
betterdisplaycli create --type=VirtualScreen --aspectWidth=16 --aspectHeight=9 --sizeInch=27

# Create virtual screen with custom resolution list
betterdisplaycli create --type=VirtualScreen --virtualScreenName="My Virtual" --useResolutionList=on --resolutionList="1920x1080,2560x1440,3840x2160"

# Create HiDPI-enabled virtual screen
betterdisplaycli create --type=VirtualScreen --aspectWidth=16 --aspectHeight=9 --virtualScreenHiDPI=on

# Connect/disconnect a virtual screen
betterdisplaycli set --nameLike=Virtual --connected=on
betterdisplaycli set --nameLike=Virtual --connected=off

# Discard a virtual screen
betterdisplaycli discard --nameLike="My Virtual" --type=VirtualScreen
```

--------------------------------

### Example Script for Root Activation

Source: https://github.com/waydabber/betterdummy/wiki/License-management-scripted

A bash script to activate BetterDisplay as a root user, handling user paths and permissions. It checks status, activates, copies activation files, and sets ownership.

```bash
#!/bin/bash

currentuser=$(echo "show State:/Users/ConsoleUser" | scutil | awk '/Name :/ && ! /loginwindow/ { print $3 }')

app="/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay"

$app manageLicense -status
$app manageLicense -activate -email=[INSERT EMAIL ADDRESS HERE] -key=[INSERT LICENSE KEY HERE]

rootpath="/var/root/Library/Application Support/BetterDisplay"
userpath="/Users/$currentuser/Library/Application Support"

if [[ $currentuser == "it" ]]; then exit; fi
#if 'it' is user, then the install isn't meaningful. standard user is target.

cp -pr "$rootpath" "$userpath"
#yes i could have used mv but wanted to keep it!

chown -R "$currentuser":staff "$userpath/BetterDisplay"
su $currentuser
$app manageLicense -status 

```

--------------------------------

### GET pro.betterdisplay.BetterDisplay.response

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Receives the result of a previously sent command from BetterDisplay.

```APIDOC
## GET pro.betterdisplay.BetterDisplay.response

### Description
BetterDisplay sends this notification back to the requester containing the operation result.

### Notification Name
pro.betterdisplay.BetterDisplay.response

### Response Body
- **uuid** (String) - Optional - The request identifier.
- **result** (Boolean) - Optional - True if the operation was successful, false otherwise.
- **payload** (String) - Optional - Returned results or data from the operation.

### Response Example
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "result": true,
  "payload": "success"
}
```

--------------------------------

### Get and set display brightness via HTTP

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Sets brightness and retrieves current, minimum, and maximum values in a single HTTP request.

```bash
curl http://localhost:55777/set/get\?namelike=16p-l\&feature=ddc\&vcp=luminance\&value=30\&min\&max
```

--------------------------------

### Get display brightness via CLI

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Retrieves current and maximum brightness values using the BetterDisplay CLI.

```bash
./BetterDisplay get -namelike=gp27 -feature=ddc -vcp=luminance -value -max
```

--------------------------------

### Access BetterDisplay help via absolute path

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Displays help information by invoking the binary directly from the application bundle.

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

--------------------------------

### Value Modification Parameters

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Parameters for setting or getting values with ranges and offsets.

```APIDOC
## Value Parameters

### Description
Parameters that affect how values are interpreted or retrieved.

### Parameters
- **value** (any): The value to set or retrieve.
- **offset** (real/percentage): Apply a relative change to a value (e.g., -10%).
- **min** (numeric): Specify lower bound or request minimum value.
- **max** (numeric): Specify upper bound or request maximum value.
```

--------------------------------

### Export and Import Settings

Source: https://context7.com/waydabber/betterdummy/llms.txt

Backup and restore application configurations using the defaults command.

```bash
# Export settings to file
defaults export pro.betterdisplay.BetterDisplay ~/Desktop/BetterDisplay.plist

# Import settings from file (app must not be running)
defaults import pro.betterdisplay.BetterDisplay ~/Desktop/BetterDisplay.plist
```

--------------------------------

### Export and Import Settings

Source: https://context7.com/waydabber/betterdummy/llms.txt

Backup and restore BetterDisplay configuration using the defaults command.

```APIDOC
## Export settings to file
defaults export pro.betterdisplay.BetterDisplay ~/Desktop/BetterDisplay.plist

## Import settings from file (app must not be running)
defaults import pro.betterdisplay.BetterDisplay ~/Desktop/BetterDisplay.plist
```

--------------------------------

### Import App Settings using Terminal (v1.x)

Source: https://github.com/waydabber/betterdummy/wiki/Export-and-import-app-settings

For older versions of the app (v1.x), use this command to import settings from a property list file. Ensure the file is located on your Desktop. Settings from different major versions are not compatible.

```bash
defaults import me.waydabber.BetterDummy ~/Desktop/BetterDisplay.plist
```

--------------------------------

### List BetterDisplay Activations (JSON)

Source: https://github.com/waydabber/betterdummy/wiki/License-management-scripted

Retrieve a JSON list of all current BetterDisplay activations, including activation date, ID, and MAC address. Requires v3.3.1 or newer. The license key can be omitted if the app is already activated.

```bash
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activationsJSON
```

```bash
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activationsJSON -key=<license key>
```

--------------------------------

### List BetterDisplay Activations (Legacy)

Source: https://github.com/waydabber/betterdummy/wiki/License-management-scripted

Retrieve activation information in a legacy structure, retained for compatibility with versions prior to v3.3.1. The license key can be omitted if the app is already activated.

```bash
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activations
```

```bash
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activations -key=<license key>
```

--------------------------------

### Import App Settings using Terminal (v4.0.3+)

Source: https://github.com/waydabber/betterdummy/wiki/Export-and-import-app-settings

Use this command to import BetterDisplay app settings from a specified property list file. This operation will override existing settings, so it's recommended to do this when the app is not running.

```bash
defaults import pro.betterdisplay.BetterDisplay ~/Desktop/BetterDisplay.plist
```

--------------------------------

### Launch BetterDisplay in Verbose Mode

Source: https://github.com/waydabber/betterdummy/wiki/Enable-console-logging

Executes the application from the Terminal with verbose logging enabled, outputting to stdout.

```bash
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay -v
```

--------------------------------

### Configure Display Layout and Mirroring

Source: https://context7.com/waydabber/betterdummy/llms.txt

Controls display arrangement, relative positioning, and mirroring configurations.

```bash
betterdisplaycli set --nameLike=External --placement=1920x0

betterdisplaycli set --nameLike=Secondary --moveTo=right --targetNameLike=Primary

betterdisplaycli set --nameLike=External --main=on

betterdisplaycli set --nameLike=Virtual --mirror=on --targetNameLike=TV

betterdisplaycli set --nameLike=Virtual --mirror=off
```

--------------------------------

### BetterDisplay Integration Methods

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Overview of the syntax and usage for CLI, URL, and HTTP integration methods.

```APIDOC
## BetterDisplay Integration Syntax

### CLI Syntax
`./BetterDisplay operation [operation] [-parameter[=value]]`

### URL Scheme Syntax
`BetterDisplay://operation[/operation][?parameter[=value]][&parameter[=value]]`

### HTTP Syntax
`http://<hostname>:55777/command/[command/][?parameter[=value]][&parameter[=value]]`

### Parameters
- **name** (string) - Optional - The name of the display or device to target.
- **brightness** (float/percentage) - Optional - The brightness value to set (e.g., 0.8 or 80%).
- **token** (string) - Optional - Security token for URL and HTTP access if configured in Settings.
```

--------------------------------

### Manage Picture-in-Picture and Streaming

Source: https://context7.com/waydabber/betterdummy/llms.txt

Commands to enable PIP windows and configure display streaming between devices with optional filters and transformations.

```bash
betterdisplaycli set --nameLike=External --pip=on

betterdisplaycli set --nameLike=External --pip --originX=70 --originY=70 --width=25 --height=25

betterdisplaycli set --nameLike=Virtual --stream=on --targetNameLike=Main

betterdisplaycli set --nameLike=Source --stream=on --rotateBy=180 --flipHorizontal=on --targetNameLike=TV

betterdisplaycli set --nameLike=Main --stream=on --targetSelf --videoFilters=on

betterdisplaycli set --nameLike=External --pip=off
```

--------------------------------

### License Management CLI

Source: https://context7.com/waydabber/betterdummy/llms.txt

Manage BetterDisplay Pro licenses via command line for enterprise deployment.

```APIDOC
## Check activation status
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -status

## Activate license
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activate -email=user@example.com -key=LICENSE-KEY

## Deactivate license
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -deactivate

## List existing activations
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activationsJSON

## Hide activation UI (for enterprise deployment)
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -hideui
```

--------------------------------

### Control Display via CLI

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Set display brightness using the application binary or the CLI tool.

```bash
./BetterDisplay set -name=MyDisplay -brightness=0.8
```

```bash
betterdisplaycli set --name=MyDisplay --brightness=80%
```

--------------------------------

### Manage BetterDisplay Pro Licenses

Source: https://context7.com/waydabber/betterdummy/llms.txt

Perform license activation, deactivation, and status checks for enterprise deployments.

```bash
# Check activation status
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -status

# Activate license
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activate -email=user@example.com -key=LICENSE-KEY

# Deactivate license
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -deactivate

# List existing activations
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activationsJSON

# Hide activation UI (for enterprise deployment)
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -hideui
```

--------------------------------

### Activate BetterDisplay License

Source: https://github.com/waydabber/betterdummy/wiki/License-management-scripted

Activate your BetterDisplay license using your email address and license key. Prior to v3.x, always use the absolute path to the app binary.

```bash
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activate -email=<email address> -key=<license key>
```

--------------------------------

### Export App Settings using Terminal (v1.x)

Source: https://github.com/waydabber/betterdummy/wiki/Export-and-import-app-settings

For older versions of the app (v1.x), use this command to export settings to a property list file on your Desktop. Note that settings formats are incompatible between major app versions.

```bash
defaults export me.waydabber.BetterDummy ~/Desktop/BetterDisplay.plist
```

--------------------------------

### POST /set

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Sets display properties such as brightness using various integration methods.

```APIDOC
## POST /set

### Description
Sets the brightness of a specific display.

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the display.
- **brightness** (string) - Required - The brightness value (e.g., 0.8).

### Request Example
`http://localhost:55777/set?name=MyDisplay&brightness=0.8`
```

--------------------------------

### Launch BetterDisplay in Verbose Mode with Stderr

Source: https://github.com/waydabber/betterdummy/wiki/Enable-console-logging

Executes the application with verbose logging directed to stderr, useful for separating logs from standard output.

```bash
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay -v2e
```

--------------------------------

### Integrate via HTTP API

Source: https://context7.com/waydabber/betterdummy/llms.txt

Control display settings remotely by sending HTTP requests to the local BetterDisplay server on port 55777.

```bash
# Set brightness via HTTP API
curl "http://localhost:55777/set?name=MyDisplay&brightness=0.8"

# Get current brightness value
curl "http://localhost:55777/get?nameLike=Dell&brightness"

# Set brightness and get the new value with min/max
curl "http://localhost:55777/set/get?nameLike=16p-l&feature=ddc&vcp=luminance&value=30&min&max"

# Toggle HDR mode
curl "http://localhost:55777/toggle?nameLike=LG&hdr"

# Set volume on a display with DDC support
curl "http://localhost:55777/set?name=ExternalMonitor&volume=0.5"
```

--------------------------------

### Manage Display Groups

Source: https://context7.com/waydabber/betterdummy/llms.txt

Enables and synchronizes settings across defined display groups.

```bash
betterdisplaycli set --name="My Group" --type=DisplayGroup --enabled=on

betterdisplaycli set --name="Sync Group" --type=DisplayGroup --synchronization=on
```

--------------------------------

### Trigger Actions via URL Scheme

Source: https://context7.com/waydabber/betterdummy/llms.txt

Automate display tasks by invoking BetterDisplay actions through custom URL schemes.

```bash
# Set brightness using URL scheme
open "BetterDisplay://set?name=MyDisplay&brightness=0.8"

# Toggle display connection
open "BetterDisplay://toggle?nameLike=Dell&connected"

# Enable HDR brightness upscaling
open "BetterDisplay://set?nameLike=XDR&brightnessUpscaling=on"

# With proper escaping in scripts
open BetterDisplay://set\?name=MyDisplay\&brightness=0.8
```

--------------------------------

### Control Display via URL Scheme

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Execute display commands using the custom URL scheme, optionally using the open command for scripts.

```text
BetterDisplay://set?name=MyDisplay&brightness=0.8
```

```bash
open BetterDisplay://set\?name=MyDisplay\&brightness=0.8
```

--------------------------------

### Check BetterDisplay Activation Status

Source: https://github.com/waydabber/betterdummy/wiki/License-management-scripted

Use this command to verify the current license activation status of BetterDisplay. Ensure you use the absolute path to the app binary, especially for versions prior to v3.x.

```bash
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -status
```

--------------------------------

### Send Brightness Command to BetterDisplay (Swift)

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Demonstrates sending a command to BetterDisplay to set the brightness of all connected displays. Requires the `IntegrationNotificationRequestData` struct and uses `DistributedNotificationCenter` to post the notification.

```swift
let integrationNotificationRequestData = IntegrationNotificationRequestData(uuid: UUID().uuidString, commands: ["set"], parameters: ["brightness": "0.8"])
do {
 let encodedIntegrationNotificationRequestData = try JSONEncoder().encode(integrationNotificationRequestData)
 if let encodedIntegrationNotificationRequestDataString = String(data: encodedIntegrationNotificationRequestData, encoding: .utf8) {
  DistributedNotificationCenter.default().postNotificationName("pro.betterdisplay.BetterDisplay.request", object: encodedIntegrationNotificationRequestDataString, userInfo: nil, deliverImmediately: true)
 }
} catch {}
```

--------------------------------

### Identify displays via CLI

Source: https://context7.com/waydabber/betterdummy/llms.txt

Use various parameters with betterdisplaycli to target specific displays for configuration.

```bash
# By display name (exact match)
betterdisplaycli set --name="Dell U2723QE" --brightness=0.8

# By partial name (case-insensitive)
betterdisplaycli set --nameLike=dell --brightness=0.8

# By UUID
betterdisplaycli set --UUID=37D8832A-2D66-02CA-B9F7-8F30A301B230 --brightness=0.8

# By tagID (BetterDisplay internal ID)
betterdisplaycli set --tagID=12345 --brightness=0.8

# By vendor and model
betterdisplaycli set --vendor=4268 --model=53358 --brightness=0.8

# Display with mouse cursor
betterdisplaycli set --displayWithMouse --brightness=0.8

# Display with focused window
betterdisplaycli set --displayWithFocus --brightness=0.8

# Main display
betterdisplaycli set --displayWithMainStatus --brightness=0.8
```

--------------------------------

### System-Wide Settings CLI

Source: https://context7.com/waydabber/betterdummy/llms.txt

Control global display settings like Night Shift, True Tone, Dark Mode, and ambient light.

```APIDOC
## Toggle Night Shift
betterdisplaycli toggle --nightShift

## Set Night Shift value
betterdisplaycli set --nightShiftValue=0.5

## Toggle True Tone
betterdisplaycli toggle --trueTone

## Toggle Dark Mode
betterdisplaycli toggle --darkMode

## Get ambient light level
betterdisplaycli get --ambientLight

## Reconfigure all displays
betterdisplaycli perform --reconfigure
```

--------------------------------

### POST pro.betterdisplay.BetterDisplay.request

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Sends a command request to BetterDisplay via Distributed Notification Center.

```APIDOC
## POST pro.betterdisplay.BetterDisplay.request

### Description
Sends a JSON-encoded notification to BetterDisplay to execute specific commands.

### Notification Name
pro.betterdisplay.BetterDisplay.request

### Request Body
- **uuid** (String) - Optional - Unique identifier to match the response.
- **commands** (Array<String>) - Required - List of commands to execute.
- **parameters** (Map<String, String>) - Optional - Key-value pairs for command parameters.

### Request Example
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "commands": ["set"],
  "parameters": {"brightness": "0.8"}
}
```

--------------------------------

### Feature Configuration Parameters

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

A list of available configuration parameters for controlling stream, PIP, and video filter window settings.

```APIDOC
## Configuration Parameters

### Description
These parameters allow for the configuration of stream, PIP, and video filter window features. All parameters listed are Pro features.

### Parameters
- **addConfiguration** (void) - Required - Add an additional configuration. ID is optional.
- **removeConfiguration** (void) - Required - Remove a configuration. ID is required.
- **freeAspect** (bool) - Optional - Free aspect ratio ('on' or 'off').
- **integerScaling** (bool) - Optional - Integer scaling ('on' or 'off').
- **directPixelMapping** (bool) - Optional - Direct (1:1) pixel mapping ('on' or 'off').
- **rotateBy** (enum) - Optional - Rotate image (0, 90, 180, 270).
- **flipHorizontal** (bool) - Optional - Flip horizontally ('on' or 'off').
- **flipVertical** (bool) - Optional - Flip vertically ('on' or 'off').
- **horizontalLocation** (enum) - Optional - Horizontal alignment ('left', 'center', 'right').
- **verticalLocation** (enum) - Optional - Vertical alignment ('top', 'center', 'bottom').
- **cursorShown** (bool) - Optional - Show mouse cursor ('on' or 'off').
- **streamUnderscan** (range) - Optional - Stream underscan value.
- **zoom** (range) - Optional - Zoom level.
- **videoFilters** (bool) - Optional - Enable video filters ('on' or 'off').
- **renderHDR** (bool) - Optional - HDR rendering for video filters ('on' or 'off').
- **alpha** (range) - Optional - Window transparency (percentage).
- **partial** (bool) - Optional - Crop image ('on' or 'off').
- **partialOriginX** (range) - Optional - Crop window origin X (percentage).
- **partialOriginY** (range) - Optional - Crop window origin Y (percentage).
- **partialWidth** (range) - Optional - Crop window width (percentage).
- **partialHeight** (range) - Optional - Crop window height (percentage).
- **resume** (bool) - Optional - Resume stream on connect ('on' or 'off').
- **priority** (enum) - Optional - Window priority ('normal', 'topmost', 'absolute', 'absoluteLockScreen').
- **unmovable** (bool) - Optional - Unmovable window ('on' or 'off').
- **clickthrough** (bool) - Optional - Click-through window ('on' or 'off').
- **showTitlebar** (bool) - Optional - Show window titlebar ('on' or 'off').
- **showShadow** (bool) - Optional - Show window shadow ('on' or 'off').
- **excludePipWindow** (bool) - Optional - Exclude PIP window ('on' or 'off').
- **magnification** (range) - Optional - Magnification level.
- **autoStart** (bool) - Optional - Start automatically ('on' or 'off').
- **originX** (range) - Optional - Window origin X (percentage).
```

--------------------------------

### Manage Display Connections

Source: https://context7.com/waydabber/betterdummy/llms.txt

Programmatic control for connecting or disconnecting displays. Requires Pro features for certain operations.

```bash
betterdisplaycli set --nameLike=External --connected=off

betterdisplaycli set --nameLike=External --connected=on

betterdisplaycli perform --disconnectAllButMain

betterdisplaycli perform --connectAllDisplays

betterdisplaycli perform --swapIdenticalDisplays
```

--------------------------------

### Manage Display Modes and HiDPI

Source: https://context7.com/waydabber/betterdummy/llms.txt

Commands for toggling HiDPI, rotating displays, and retrieving display mode or refresh rate information.

```bash
betterdisplaycli set --nameLike=Monitor --hiDPI=on

betterdisplaycli set --nameLike=Portrait --rotation=90

betterdisplaycli get --nameLike=Dell --displayModeList

betterdisplaycli set --nameLike=Main --favoriteMode=1

betterdisplaycli get --nameLike=Gaming --refreshRateList
```

--------------------------------

### Export App Settings using Terminal (v4.0.3+)

Source: https://github.com/waydabber/betterdummy/wiki/Export-and-import-app-settings

Use this command to export current BetterDisplay app settings to a property list file on your Desktop. Ensure the app is not running for import operations.

```bash
defaults export pro.betterdisplay.BetterDisplay ~/Desktop/BetterDisplay.plist
```

--------------------------------

### Control Display via HTTP

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Send commands to the BetterDisplay HTTP server using raw URLs or curl.

```text
http://localhost:55777/set?name=MyDisplay&brightness=0.8
```

```bash
curl http://localhost:55777/set\?name=MyDisplay\&brightness=0.8
```

--------------------------------

### Manage System-Wide Display Settings

Source: https://context7.com/waydabber/betterdummy/llms.txt

Control global display features like Night Shift, True Tone, and Dark Mode, or trigger a display reconfiguration.

```bash
# Toggle Night Shift
betterdisplaycli toggle --nightShift

# Set Night Shift value
betterdisplaycli set --nightShiftValue=0.5

# Toggle True Tone
betterdisplaycli toggle --trueTone

# Toggle Dark Mode
betterdisplaycli toggle --darkMode

# Get ambient light level
betterdisplaycli get --ambientLight

# Reconfigure all displays
betterdisplaycli perform --reconfigure
```

--------------------------------

### Window Properties

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Configuration options for controlling window dimensions and position.

```APIDOC
## Window Properties

### Description
These properties allow for the configuration of window size and origin, relative to the target display's dimensions.

### Parameters
#### Query Parameters
- **originY** (percentage) - Optional - Window origin Y (percentage value, relative to the target display size, zero is the bottom of the screen). Used by `pip`, `videoFilterWindow`. A contiguous range of values are accepted. Pro feature.
- **width** (percentage) - Optional - Window width (percentage value, relative to the target display size). Used by `pip`, `videoFilterWindow`. A contiguous range of values are accepted. Pro feature.
- **height** (percentage) - Optional - Window height (percentage value, relative to the target display size). Used by `pip`, `videoFilterWindow`. A contiguous range of values are accepted. Pro feature.
```

--------------------------------

### Configure Display Groups via CLI

Source: https://context7.com/waydabber/betterdummy/llms.txt

Use these commands to modify display group settings such as layout protection and UI scaling.

```bash
# Enable layout protection for a group
betterdisplaycli set --name="Layout Group" --type=DisplayGroup --layoutProtection=on

# Enable UI scale matching
betterdisplaycli set --name="Scale Group" --type=DisplayGroup --uiScaleMatching=on
```

--------------------------------

### Configure Display Protection Settings

Source: https://context7.com/waydabber/betterdummy/llms.txt

Locks specific display configurations to prevent accidental changes. Requires Pro features.

```bash
betterdisplaycli set --nameLike=Main --protectResolution=on

betterdisplaycli set --nameLike=Gaming --protectRefreshRate=on

betterdisplaycli set --nameLike=OLED --protectHDR=on

betterdisplaycli set --nameLike=Display --protectAll=on

betterdisplaycli set --nameLike=Main --protectResolution=off
```

--------------------------------

### Set display brightness via HTTP

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Adjusts display brightness using an HTTP request to the local BetterDisplay server.

```bash
curl http://localhost:55777/set\?namelike=gp27\&feature=ddc\&vcp=luminance\&value=50
```

--------------------------------

### Retrieve Display Information

Source: https://context7.com/waydabber/betterdummy/llms.txt

Fetches technical details including identifiers, DDC capabilities, color profiles, and EDID data.

```bash
betterdisplaycli get --identifiers

betterdisplaycli get --nameLike=Dell --identifier=UUID

betterdisplaycli get --nameLike=Monitor --ddcCapabilities

betterdisplaycli get --nameLike=External --connectionModeList

betterdisplaycli get --installedColorProfileURLs

betterdisplaycli get --nameLike=Monitor --i2cEDID
```

--------------------------------

### Set display brightness via CLI

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Adjusts display brightness using the BetterDisplay CLI binary with hexadecimal values.

```bash
./BetterDisplay set -namelike=gp27 -feature=ddc -vcp=0x10 -value=0x32
```

--------------------------------

### Implement Custom OSD via Swift

Source: https://context7.com/waydabber/betterdummy/llms.txt

Subscribe to OSD notifications to render custom on-screen displays based on BetterDisplay events.

```swift
// OSD notification structure
struct OsdNotification: Codable {
    var displayID: Int?        // Which display should show the OSD
    var systemIconID: Int?     // 1=brightness, 3=volume, 4=mute, 0=no icon
    var customSymbol: String?  // SF Symbol name for custom icon
    var text: String?          // Additional text for OSD
    var lock: Bool?            // Show lock icon
    var controlTarget: String? // Type: combinedBrightness, volume, contrast, etc.
    var value: Double?         // OSD value (0 to maxValue)
    var maxValue: Double?      // Maximum value
    var symbolFadeAfter: Int?  // Fade secondary symbol after ms
    var symbolSizeMultiplier: Double?
    var textFadeAfter: Int?    // Fade text after ms
}

// Subscribe to OSD notifications
DistributedNotificationCenter.default().addObserver(
    forName: NSNotification.Name("pro.betterdisplay.BetterDisplay.osd"),
    object: nil,
    queue: .main
) { notification in
    guard let notificationString = notification.object as? String,
          let osdData = try? JSONDecoder().decode(
              OsdNotification.self,
              from: Data(notificationString.utf8)
          ) else { return }

    // Display custom OSD based on notification data
    showCustomOSD(
        displayID: osdData.displayID,
        value: osdData.value,
        maxValue: osdData.maxValue,
        controlType: osdData.controlTarget
    )
}
```

--------------------------------

### Display Group Settings

Source: https://context7.com/waydabber/betterdummy/llms.txt

Commands to configure layout protection and UI scale matching for display groups.

```APIDOC
## Enable layout protection for a group
betterdisplaycli set --name="Layout Group" --type=DisplayGroup --layoutProtection=on

## Enable UI scale matching
betterdisplaycli set --name="Scale Group" --type=DisplayGroup --uiScaleMatching=on
```

--------------------------------

### App Intents Support (macOS Shortcuts)

Source: https://github.com/waydabber/betterdummy/wiki/Integration-features,-CLI

Information on how BetterDummy integrates with macOS Shortcuts app via App Intents.

```APIDOC
## App Intents Support (macOS Shortcuts)

### Description
BetterDummy supports the macOS Shortcuts app through the App Intents framework. However, not all functionalities are exposed as App Intents. For advanced operations, using the Command Line Interface (CLI) from within the Shortcuts app is recommended.
```

--------------------------------

### Configure XDR/HDR Brightness Upscaling

Source: https://context7.com/waydabber/betterdummy/llms.txt

Controls for enabling software or native brightness upscaling and managing HDR states on compatible displays.

```bash
betterdisplaycli set --nameLike=XDR --brightnessUpscaling=on

betterdisplaycli set --nameLike=MacBook --nativeBrightnessUpscaling=on

betterdisplaycli set --nameLike=LG --hdr=on

betterdisplaycli toggle --nameLike=OLED --hdr

betterdisplaycli get --nameLike=Monitor --hdr
```

--------------------------------

### Integrate BetterDisplay with Swift

Source: https://context7.com/waydabber/betterdummy/llms.txt

Send commands and receive responses from BetterDisplay using DistributedNotificationCenter.

```swift
// Request structure for sending commands to BetterDisplay
struct IntegrationNotificationRequestData: Codable {
    var uuid: String?
    var commands: [String] = []
    var parameters: [String: String?] = [:]
}

// Send brightness command to BetterDisplay
let requestData = IntegrationNotificationRequestData(
    uuid: UUID().uuidString,
    commands: ["set"],
    parameters: ["brightness": "0.8"]
)

if let encodedData = try? JSONEncoder().encode(requestData),
   let dataString = String(data: encodedData, encoding: .utf8) {
    DistributedNotificationCenter.default().postNotificationName(
        NSNotification.Name("pro.betterdisplay.BetterDisplay.request"),
        object: dataString,
        userInfo: nil,
        deliverImmediately: true
    )
}

// Response structure for receiving results from BetterDisplay
struct IntegrationNotificationResponseData: Codable {
    var uuid: String?
    var result: Bool?
    var payload: String?
}

// Listen for responses
DistributedNotificationCenter.default().addObserver(
    forName: NSNotification.Name("pro.betterdisplay.BetterDisplay.response"),
    object: nil,
    queue: .main
) { notification in
    guard let responseString = notification.object as? String,
          let responseData = try? JSONDecoder().decode(
              IntegrationNotificationResponseData.self,
              from: Data(responseString.utf8)
          ) else { return }
    print("Result: \(responseData.result ?? false)")
    print("Payload: \(responseData.payload ?? "")")
}
```