How do I update a widget from a script or remote job?

First add a TerminalWidget widget to the Desktop or Home Screen and set Edit Widget → Target name. Then use the included terminal-widget CLI with flags like --target, --text, --progress, --chart, --icon, and --fg, or push the same fields via Shortcuts, AppleScript, or the URL scheme. On Mac, updates apply immediately. On iPhone and iPad, content syncs through iCloud after TerminalWidget has been opened once and notification permission has been allowed (the prompt on first open) so background pulls can wake the app. Full setup: https://terminalwidget.app/integrations#getting-started

Why doesn’t my CLI or Shortcut update show on the widget?

TerminalWidget never auto-places widgets. You must add one yourself, then set its Target name to match --target, the Shortcuts Target field, or URL target=. Names are case-sensitive. Step-by-step guide: https://terminalwidget.app/integrations#getting-started

Can tapping a widget run an action?

Yes. You can assign a tap/click action per widget target — open a URL, open a Mac app, run a Shortcut, run a shell command (macOS), or refresh from a URL. Actions sync with the widget payload over iCloud. On iOS, URL and Shortcut actions are supported; Mac-only app and shell actions fall back to normal open/update behavior.

What can widgets display?

Plain or formatted text, progress (0–100), sparklines and other chart styles, matrix-style integer displays, tables (CSV/TSV/JSON), and local or remote images including edge-to-edge layouts. Colors, fonts, icons, titles, and captions are configurable per update.

Do I need internet or iCloud for sync?

Local Mac updates work without the network. Cross-device sync uses iCloud, so each Mac, iPhone, and iPad should be signed into the same Apple ID with iCloud enabled for TerminalWidget. iOS and iPadOS also need notification permission so widgets can refresh in the background when another device updates a target.

Why do my Mac desktop widgets look dimmed?

macOS can dim Desktop widgets when you are not in Show Desktop mode. To keep them fully visible, open System Settings → Desktop & Dock → Widgets and set Dim widgets on desktop to Never.

Why does my SVG look wrong in the widget (missing text)?

WidgetKit’s SVG renderer is not full WebKit. Diagrams that use text or tspan elements often render correctly in Safari or Sketch but drop or mishandle labels in widgets. Convert text to outlines/paths before passing the SVG to --image — then labels display cleanly. Easiest with Inkscape CLI: inkscape in.svg --export-text-to-path --export-plain-svg --export-filename=out.svg (details on the Widgets page).

Put Terminal Output on Your Desktop

TerminalWidget lets you send output from commands, scripts, APIs, and Shortcuts directly to widgets across macOS, iOS, and iPadOS with rich formatting, progress bars, sparklines, and image support. It is available as a universal app on the App Store for $19.99.

Features

Output text from terminal commands or generate a wide variety of charts and tables from data
Multiple widgets can be targeted individually
Sync across multiple Macs and iOS devices
Display local or remote images, including those generated by APIs
Display images edge-to-edge
Full control over colors, fonts, and icon
Instant updates on macOS, rapid updates on iOS via iCloud
Full CLI included, incorporate into scripts
Shortcuts actions work on Mac and iOS, with AppleScript support and a URL scheme for automation
Display progress bars with any number 0-100
Display charts and graphs by passing serial integer data
Display matrix-style chart of integer values

macOS Widgets

Output any text, image, or chart data to fully customizable widgets
Use shell scripts or AppleScript output on macOS
Interact via Shortcuts or URL scheme on macOS and iOS
Assign actions to widgets to execute on tap/click

Mac + iPhone + iPad

Widgets sync across your Apple devices when iCloud is enabled.
iOS and iPadOS widgets support the same rich text, progress bar, and sparkline payloads.
Use the URL scheme or Shortcuts actions to update widgets from iPhone and iPad.
Existing CLI scripts continue to work the same for Mac workflows.

CLI Example

terminal-widget --target widget1 --text "Build complete" --icon "checkmark.seal.fill" --progress 100 --fg "#22c55e"

Read full CLI documentation

How it compares

TerminalWidget is a native widget surface you drive from tools you already use — not a hosted monitoring product and not another static widget pack.

	TerminalWidget	Typical alternatives
Footprint	Native Mac App Store app with WidgetKit widgets and a small CLI — no Electron shell or always-on web server.	Custom Electron/web dashboards or a self-hosted monitoring stack.
How you update	CLI, Shortcuts, AppleScript, or URL scheme targeting named widgets.	Agents, scrapers, or hand-built UI refresh loops.
Mac + iPhone + iPad	Same widget targets sync over iCloud when enabled.	Separate tools per platform, or your own sync relay.
What you can show	Text, progress, charts/sparklines, tables, and local or remote images.	Whatever you build into a custom dashboard — usually more setup.
Pricing	$19.99 one-time universal App Store purchase.	SaaS seats, infrastructure cost, or ongoing DIY maintenance.

FAQ

How do I update a widget from a script or remote job?: First add a TerminalWidget widget to the Desktop or Home Screen and set Edit Widget → Target name. Then use the included terminal-widget CLI with flags like --target, --text, --progress, --chart, --icon, and --fg, or push the same fields via Shortcuts, AppleScript, or the URL scheme. On Mac, updates apply immediately. On iPhone and iPad, content syncs through iCloud after TerminalWidget has been opened once and notification permission has been allowed (the prompt on first open) so background pulls can wake the app. Full setup: https://terminalwidget.app/integrations#getting-started
Why doesn’t my CLI or Shortcut update show on the widget?: TerminalWidget never auto-places widgets. You must add one yourself, then set its Target name to match --target, the Shortcuts Target field, or URL target=. Names are case-sensitive. Step-by-step guide: https://terminalwidget.app/integrations#getting-started
Can tapping a widget run an action?: Yes. You can assign a tap/click action per widget target — open a URL, open a Mac app, run a Shortcut, run a shell command (macOS), or refresh from a URL. Actions sync with the widget payload over iCloud. On iOS, URL and Shortcut actions are supported; Mac-only app and shell actions fall back to normal open/update behavior.
What can widgets display?: Plain or formatted text, progress (0–100), sparklines and other chart styles, matrix-style integer displays, tables (CSV/TSV/JSON), and local or remote images including edge-to-edge layouts. Colors, fonts, icons, titles, and captions are configurable per update.
Do I need internet or iCloud for sync?: Local Mac updates work without the network. Cross-device sync uses iCloud, so each Mac, iPhone, and iPad should be signed into the same Apple ID with iCloud enabled for TerminalWidget. iOS and iPadOS also need notification permission so widgets can refresh in the background when another device updates a target.
Why do my Mac desktop widgets look dimmed?: macOS can dim Desktop widgets when you are not in Show Desktop mode. To keep them fully visible, open System Settings → Desktop & Dock → Widgets and set Dim widgets on desktop to Never.
Why does my SVG look wrong in the widget (missing text)?: WidgetKit’s SVG renderer is not full WebKit. Diagrams that use text or tspan elements often render correctly in Safari or Sketch but drop or mishandle labels in widgets. Convert text to outlines/paths before passing the SVG to --image — then labels display cleanly. Easiest with Inkscape CLI: inkscape in.svg --export-text-to-path --export-plain-svg --export-filename=out.svg (details on the Widgets page).