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. You can include these commands in 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.

Print activation status

/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). Use each identifier exactly as returned. 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 when the list contains one to nine activations. The operation refuses larger volume-license lists. 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 hides the interface while keeping license access and command-line access unchanged. Sensitive details remain in -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 does not confirm success in this command mode. Inspect the operation’s result and check the activation state separately.

Run activation, listing and status checks in separate invocations. Combining flags can make status run before an asynchronous operation completes. Do not rely on the activation dialog’s automatic removal of the oldest activation in this scripted workflow. If the activation limit blocks deployment, inspect the list and remove an unused activation.

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.

Related pages

• Activation errors FAQ covers incorrect entries, network access and Paddle errors when activating a license that covers the app version.
• Getting a Pro license covers purchases, transfers and troubleshooting.
• Pro pane explains the graphical license-management interface.
• Integration overview covers display automation and other integration methods.

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. The current BetterDisplay release requires macOS 26.3 or later.