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

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.