# TerminalWidget Integrations
> Choose the best integration path for automating TerminalWidget updates.
Source: https://terminalwidget.app/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.
**Required before any update works:** TerminalWidget does not create desktop or Home Screen widgets for you. You must **manually add** a TerminalWidget widget, then set its **Target name** (widget ID). CLI, Shortcuts, AppleScript, and URL updates only reach widgets that share that ID. Follow [Getting Started](#getting-started) below before troubleshooting "nothing changed."
## 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:
```bash
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.
---