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
With the Preen CLI installed, start your hub and add a display:
preen init --no-discovery
preen setup
init presents keyboard menus: first agree to the Terms of Use and acknowledge
Privacy Policy (both can be opened in your browser), then choose Local Network
or Remote. Use the arrow keys and Enter, or a number followed by Enter. Terms
acceptance is saved with its version and date. Cancelling before agreement does
not start a hub.
Local Network needs no account. Packaged builds request macOS network permission
directly. Remote offers account sign-in and a link to plans, and requires Preen
Plus before it can be enabled. init ends by inviting you to run preen setup;
it does not create a widget or display a pairing code.
setup offers two display types:
- Web browser: sign in with Plus, create a browser display on your account page, then select it in the terminal to pair and open it. Each browser display supports one viewing device at a time.
- iPhone or iPad: prepares Hello Preen if the library is empty, then shows a rotating pairing QR inside a house. It refreshes in place and restores your terminal when pairing finishes or you press Ctrl-C. Smaller windows show a compact QR or ask you to resize. Scan it in Preen on your phone. Local pairing needs both devices on the same network.
Run preen setup again to add another display. Existing widgets, data, and pairings
are preserved. preen pair remains a direct shortcut to phone pairing. To host the
hub in a terminal, run preen-hub --foreground.
After setup:
preen publish counter.html --name Counter
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. Use --no-discovery to skip the discovery permission request.
For unattended local initialization, explicitly accept the terms and select the connection:
preen init --accept-terms --connection local --no-discovery
preen setup ios --no-wait
The second command creates a starter widget only for an empty library and prints
one pairing QR. --accept-terms agrees to the Terms of Use and acknowledges the
Privacy Policy linked by preen init --help. Remote and browser account setup
remain interactive. Run preen init again to change your connection choice;
choosing Local Network disables Private Relay, and choosing Remote removes the
LAN address from new pairing codes after remote access is enabled.
Keep it running
preen service install
preen hub start
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;
keep the executable installed while the service is registered.
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.
preen hub stop
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.
Manage it from another machine
With relay enabled, the hub can be managed remotely through the relay, without opening a port. Mint a token here and use it elsewhere:
preen tokens create "Laptop" --scope push # shown once
On the other machine, run preen connect <hub-id> --token …, with the
hubId that preen relay status prints. See
remote hubs.
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.