TerminalWidget Integrations

TerminalWidget is a Mac, iPhone, and iPad app that shows text, progress bars, charts, and images in widgets, used by developers and power users to monitor scripts and automations at a glance.

Pick the integration that matches your automation stack. Each option links to detailed documentation and examples.

Getting Started

Before CLI, Shortcuts, AppleScript, or URL scheme updates will show up, add a TerminalWidget widget and give it a Target name (widget ID). Every integration updates widgets by that ID.

1. Add a widget

macOS

1. Right-click the desktop (or open Notification Center / widgets gallery, depending on your macOS version).
2. Choose Edit Widgets, then find TerminalWidget.
3. Add a Small, Medium, or Large widget to the desktop.
4. Open the TerminalWidget menu bar app at least once after install.

If Desktop widgets look washed out when you are not in Show Desktop mode, open System Settings → Desktop & Dock → Widgets and set Dim widgets on desktop to Never.

iPhone / iPad

1. Touch and hold the Home Screen, then tap Edit → Add Widget.
2. Select TerminalWidget and add a size you want.
3. Open the TerminalWidget app at least once after install so iCloud sync can register the device (needed for Mac ↔ iPhone ↔ Watch sync).

2. Set the Target name

1. On the widget, open Edit Widget (right-click / long-press → Edit Widget).
2. Set Target name to an ID you will use in automation — for example widget1, sales, or backup.
3. Leave other options as defaults for now.

Use the same Target name in your scripts and Shortcuts (--target, Target, URL target=, and so on). Different widgets can share one ID (they show the same content) or use unique IDs for separate dashboards.

3. Send a test update

After the Target name is set, send a quick update from any integration — for example:

terminal-widget --target widget1 --text "Hello from TerminalWidget" --icon "checkmark.seal.fill"

If the widget does not change, confirm the Target name matches exactly (case-sensitive) and that TerminalWidget is installed and has been opened once on that device.

4. Sync with iCloud (optional)

Cross-device sync (Mac, iPhone, Apple Watch) uses iCloud and is on by default.

If you only use one device and do not want CloudKit:

• Mac: open the menu bar app → Info/Debug and turn off Sync with iCloud.
• iPhone / iPad: open TerminalWidget → Info/Debug and turn off the same toggle.

Local CLI, Shortcuts, and URL updates keep working on that device. Mac ↔ iPhone ↔ Watch sync stops until you turn the toggle back on. The preference is per device.