Scripted license management

BetterDisplay supports non-interactive license management through its app executable. Use it to activate a managed installation, inspect existing activations, or remove an activation without access to the original Mac; these commands can be incorporated into MDM, Jamf, Kandji or Intune deployment scripts.

Use the app executable

Run manageLicense directly through the installed application. This is a separate launch mode from the display-command interface: it does not require a running BetterDisplay UI or the betterdisplaycli companion. Use one operation per invocation and adjust the application path if necessary.

Replace example email addresses and keys with your purchase details, keeping each argument quoted. Licensing must be enabled for the target user. Purchase and activation still require communication with Paddle.

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

The output includes activation state, email, license key, activation date and ID, and trial information. Treat it as sensitive: redact license details before sharing logs. The displayed activation state alone does not establish whether a license covers a newer major version; consult the upgrade FAQs.

Activate or deactivate this installation

Activate with the purchase email and license key:

/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activate '-email=person@example.com' '-key=YOUR-LICENSE-KEY'

Deactivate the local installation:

/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -deactivate

List existing activations

Use JSON output for scripts; it is available in BetterDisplay 3.3.1 and later:

/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activationsJSON
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activationsJSON '-key=YOUR-LICENSE-KEY'

Omit -key when the local installation already stores the relevant license. Each record contains activation_id, uuid (the activation's device identifier) and activated (the activation date). Treat identifiers as opaque values; do not assume that every uuid is a readable network-adapter MAC address.

The legacy listing remains available for compatibility:

/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activations
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -activations '-key=YOUR-LICENSE-KEY'

Remove an activation on another Mac

Select the intended activation_id from the list and supply the corresponding license key:

/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -deactivate '-activationid=ACTIVATION-ID' '-key=YOUR-LICENSE-KEY'

When the local installation already stores that license, -key can be omitted. Removing a remote activation withdraws Pro access from that installation. Double-check the ID before running the command. Always supply a nonempty key or ensure the local license is present: without either, the command can fall back to deactivating the local installation.

Remove all activations

For a deliberate license reset, the current app also supports:

/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -deactivateall '-key=YOUR-LICENSE-KEY'

This requests removal of every returned activation and also deactivates the local installation when its stored key matches. It only proceeds with a nonempty list of at most nine activations; larger volume-license lists are refused by this operation. Use targeted removal for those lists.

Hide or show license-management UI

For managed installations, you can hide the activation/deactivation interface and displayed license key to reduce accidental changes or casual copying:

/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -hideui
/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay manageLicense -showui

This is a per-user preference. It changes UI visibility, not license entitlement or command-line access, and does not remove sensitive details from -status output.

Activate for the signed-in user from a root script

BetterDisplay keeps activation files under the running user's ~/Library/Application Support/BetterDisplay directory. Activation data can be shared between local users on the same Mac, but copying the whole support directory can also copy unrelated app state. Prefer running the activation in the target user's context.

The following deployment template expects to run as root after a regular user has logged into the Mac's console session. It stops if no suitable session exists, checks that the app is installed, and runs activation in that user's login session with that user's home directory. Configure the purchase details through your management system; the values below are placeholders.

#!/bin/bash
set -euo pipefail

app='/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay'
email='person@example.com'
license='YOUR-LICENSE-KEY'

if [[ $EUID -ne 0 ]]; then
  echo 'Run this deployment script as root.' >&2
  exit 1
fi

current_user=$(/usr/bin/stat -f '%Su' /dev/console)
case "$current_user" in
  ''|root|loginwindow|_mbsetupuser)
    echo 'No regular console user is signed in; defer activation.' >&2
    exit 1
    ;;
esac

[[ -x "$app" ]] || { echo 'BetterDisplay is not installed.' >&2; exit 1; }
user_id=$(/usr/bin/id -u "$current_user")
result=$(/bin/launchctl asuser "$user_id" \
  /usr/bin/sudo -H -u "$current_user" \
  "$app" manageLicense -activate "-email=$email" "-key=$license")
printf '%s\n' "$result"

# This command mode does not provide a reliable success/failure exit code.
if ! /usr/bin/grep -qx 'Activation successful.' <<< "$result"; then
  echo 'Activation was not confirmed; inspect the error output.' >&2
  exit 1
fi

Adapt and test the template for your management platform, login timing and multi-user policy before fleet deployment. Do not enable shell tracing or publish scripts containing real license keys. For a different target account, explicitly select that account and its session rather than assuming the console user is always the intended recipient.

Check results in automation

Activation and deactivation print success messages; failures are written to standard error. Network operations have a timeout of roughly eleven seconds. A zero process exit status alone is not a reliable success signal in this command mode; inspect the operation's result and verify the resulting activation state separately.

Run activation, listing and status checks in separate invocations. Combining flags can make status run before an asynchronous operation completes. The activation dialog's automatic removal of an oldest activation is not guaranteed in this non-interactive workflow; inspect the list and remove an intended unused activation if the limit blocks deployment.

Firewall configuration

Allow HTTPS access to v3.paddleapi.com. Managed environments may need to allow *.paddleapi.com and *.paddle.com for the licensing and checkout services. A successful Sparkle update check tests a different destination and does not establish licensing connectivity.

Additional information

This section summarizes license requirements and platform compatibility.

Features requiring Pro license

These commands do not purchase a license. Activation requires valid purchase details; listing and removal require the corresponding stored or supplied license key. Hiding UI does not unlock Pro features.

Platform compatibility

License management is available on both Apple silicon and Intel Macs. Use an app version compatible with your macOS version; BetterDisplay requires macOS 26.3 or later.