Need help with TerminalWidget?
Post an issue on GitHub — the preferred way to request support. Issues are public, so others with the same question can find answers, and they help us track bugs and feature requests.
Prefer email? Contact Brett directly at tw@brettterpstra.com.
iOS and iPadOS setup
After installing TerminalWidget on iPhone or iPad:
- Open the TerminalWidget app at least once. Allow notifications when prompted — iOS only lists TerminalWidget under Settings > Notifications after that prompt. The app uses push to wake for iCloud pulls when another device updates a widget; without permission, widgets may not refresh until you open the app manually.
- Manually add a TerminalWidget widget to the Home Screen, then set Edit Widget → Target name to match the widget ID you update from your Mac, Shortcuts, or URL scheme. Full steps: Integrations → Getting Started.
- If you need to change notification settings later, open Settings > Notifications > TerminalWidget (or Settings > Apps > TerminalWidget). If the app is missing from that list, open TerminalWidget once more and accept the permission prompt.
- Confirm you are signed into iCloud on the device with the same Apple ID used on your Mac.
Single-device use without iCloud: on Mac, open the menu bar app → Info/Debug and turn off Sync with iCloud. On iPhone, open TerminalWidget → Info/Debug and turn off the same toggle. Local CLI, Shortcuts, and URL updates keep working; Mac ↔ iPhone ↔ Watch sync stops until you turn it back on.
If widgets still look stale, open TerminalWidget, tap the menu, choose Refresh, then open Info/Debug and check Last pull under Cloud sync. A successful pull updates that timestamp.
Notify-on-change alerts (from --notify, URL notify=1, or Shortcuts) also require notification permission on iOS and iPadOS.