Support

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.

Open a GitHub issue

Prefer email? Contact Brett directly at tw@brettterpstra.com.

iOS and iPadOS setup

After installing TerminalWidget on iPhone or iPad:

1. 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.
2. 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.
3. 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.
4. 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.

Diagnosing silent failures

When a launcher button, image, or update fails without an on-widget error:

Mac

1. Open the menu bar app → Info/Debug and scroll to Recent events.
2. Or run terminal-widget log --level warn from a terminal.
3. Or add a widget whose Target name is twdiags to watch the same history on the Desktop.

iPhone and iPad

1. Add a TerminalWidget to the Home Screen and set Edit Widget → Target name to twdiags.
2. Trigger the failing update again (Shortcut, URL scheme, button tap, etc.) and wait for the widget to refresh.
3. Read the event lines on the widget. There is no Info/Debug panel and no terminal-widget log on device.

The diagnostics log is device-local: a twdiags widget on your phone shows iOS events only (Shortcuts/URL updates, CloudKit, button actions, images, reload/timeline pairing). Mac CLI and menu-bar events appear only on Mac.

Full details: CLI → Diagnostics.

Notify-on-change alerts (from --notify, URL notify=1, or Shortcuts) also require notification permission on iOS and iPadOS.