Preen Display

CLI

Headless hub

Run Preen from a terminal or a macOS user service without the Mac window.

The preen-hub executable hosts your widgets, paired displays, actions, and data without opening the Mac app. The first standalone version runs on macOS. It does not run the Notch or built-in Mac collectors; scripts and agents push data using the existing CLI and MCP tools.

Start and pair

Build the executables from the repository:

swift build
.build/debug/preen init --no-discovery

Setup starts a background hub, prepares a Hello Preen widget when your library is empty, and displays a pairing QR. Scan it in Preen on your phone while both devices are on the same network. No account is needed.

Running preen init again keeps your existing widgets and pairings. Use preen init --pair or preen pair to add another display. To host the hub in a terminal instead of as a background service, run preen-hub --foreground.

After setup:

.build/debug/preen publish counter.html --name Counter
.build/debug/preen push Counter '{"value":42}'

Scan the terminal QR in Preen on your phone. The command refreshes the code and waits for pairing. Use preen pair --json for the current payload as JSON. Local pairing does not require an account.

The daemon uses ports 8443 and 8444 by default, so use Settings → Turn Preen Off before starting a separate hub on those ports. It stores its own widgets and pairing identity in ~/Library/Application Support/Preen Hub. Existing Mac app pairings and widgets are not migrated automatically.

For an isolated instance, set PREEN_STATE_DIR for your commands and choose --port and --admin-port. If the automatic LAN address is unsuitable, pass --host with an address your phone can reach. This version uses the address in the QR. Packaged installs can also enable Bonjour discovery after macOS allows it.

macOS permissions

preen init requests discovery access from the background hub. If macOS shows a Local Network dialog, approve it there. If access is denied or still pending, setup continues with QR pairing. To revisit the relevant settings:

preen settings network
preen settings background

These open Privacy & Security → Local Network and General → Login Items & Extensions. After allowing discovery access, run preen init again. Basic widget hosting does not require Accessibility, Screen Recording, or Full Disk Access. For source builds, use --no-discovery; raw development binaries do not have the packaged helper’s signed permission identity.

For unattended setup, use preen init --no-wait --no-discovery. This skips the system permission request and prints a QR if you have no paired devices. Add --pair to print a QR for another device on an existing setup. You can enable discovery later by running preen init interactively.

Keep it running

.build/debug/preen service install
.build/debug/preen hub start
.build/debug/preen hub status

The user launch agent starts after you log in to the Mac desktop and restarts after a crash. It does not run before login after a reboot. Logs go to hub.log in the state directory. The service runs the installed executable in place; source builds must retain their build directory.

After brew upgrade preen, run preen hub restart to launch the new version. Preen manages its launch agent; do not also use brew services for the same hub. Run preen service uninstall before brew uninstall preen; Homebrew does not remove Preen’s custom service registration automatically.

.build/debug/preen hub stop
.build/debug/preen service uninstall

Uninstalling the service retains widgets, credentials, and pairings. The Mac app can attach to a compatible running daemon and supplies its own background surfaces helper for the Notch and Mac collectors. See Mac companion.

Manage devices and actions

preen devices
preen devices rename DEVICE-ID "Desk phone"
preen devices bird DEVICE-ID 1
preen devices revoke DEVICE-ID
preen consent
preen consent approve WIDGET-ID
preen consent revoke WIDGET-ID

Consent approval shows the widget’s declared capabilities and asks for confirmation. Approval applies to the exact code and action bundle reviewed. Use --yes only after reviewing that bundle when automating the command.

The daemon’s admin token authorizes these controls. Keep its state directory private and provide the credential only to trusted tools. Device listings omit paired-display session tokens.

Connect an account

preen login
preen relay enable
preen relay status

Open the printed URL in a browser, sign in, and approve the hub. The terminal waits for authorization by polling; it does not need the Mac app. Enabling Private Relay requires the approved account’s active Plus subscription.

preen relay disable
preen logout

Logout removes the daemon’s stored account credential and disables relay.

Use MCP and live status

Point your MCP client at preen-mcp. It automatically reads the running daemon’s endpoint and private token file. For a custom state directory, provide PREEN_STATE_DIR in the MCP server environment. Existing explicit PREEN_URL and PREEN_TOKEN configurations still work.

preen hub events streams complete status snapshots when state changes and immediate widget pulses. Reconnect after interruption to get current state; the stream does not replay historical events.