Terminal Widget

Terminal Widget URL Scheme

Download on the Mac App Store Download on the App Store

Use the terminalwidget:// URL scheme to trigger widget updates from Shortcuts, LaunchBar, Alfred, Raycast, browser bookmarks, and any app that can open URLs.

Base Format

terminalwidget://update?target=widget1&text=Hello%20World
  • Scheme: terminalwidget://
  • Action path: update
  • Parameters: URL query items (key=value)

Values should be URL-encoded ( => %20, # => %23, & => %26).

Widget taps use a separate dispatch endpoint:

terminalwidget://action?target=widget1

You usually do not need to open that URL yourself. Set actionKind and actionValue on the update endpoint, and the widget extension will use the action endpoint when the saved action is supported on the current platform.

How It Works

  1. macOS receives the URL and launches (or wakes) Terminal Widget.
  2. The URL is parsed into the same payload used by the CLI and AppleScript layers.
  3. The target widget state is written to shared preferences/App Group storage.
  4. Widget refresh notifications are posted.

If a parameter is invalid, that field is ignored while valid fields still apply.

Common Parameters

  • target: widget target name (widget1, widget2, or custom target)
  • text: text line
  • icon: SF Symbol name or emoji alias
  • progress: integer 0-100
  • chart: chart data (4,8,15,16,23,42 or 4 8 15 16 23 42; grouped sparkline/bar uses slash-separated series such as 0 1 5 2/1 2 5 3; rangebar uses 1-3,2-3,1-4)
  • chartFormat: sparkline, graph, area, matrix, rangebar, etc. Grouped slash chart values require sparkline/spark/bar.
  • chartBarStyle (or chart-bar-style): set to glass for bar-style chart modes and for progressFormat=circle rings; omit the parameter to keep the target’s existing chart bar style (omission does not turn glass off). Include chartBarStyle / chart-bar-style with a non-glass value (or solid) to return to the default solid bars.
  • fg: comma-separated foreground colors use the first for text/icons and the full list for grouped sparkline series colors.
  • caption: 1/true to show chart min/max caption (or progress percent caption when used with progress)
  • labelY: 1/true to show the five-tick y-axis for numeric charts
  • timestamp (or chartTimestamp / chart-timestamp): 1/true to show the last update time in the caption area
  • image: local file path or image URL
  • filter: filter chain (sepia:35,blur:8)
  • padding: numeric value, fill, or 0
  • theme: system, light, or dark
  • fg: foreground color (#RRGGBB, rgb(...), rgba(...))
  • textColor (or text-color): main widget text / table default cell color; omit to match foreground
  • captionColor (or caption-color): captions and timestamp text; omit to match foreground
  • bg: background color
  • alpha: 0.0...1.0 (applies to foreground, background, text color, and caption color when those are set)
  • table: .csv, .tsv, or .json path
  • grid: none, row, column, both, zebra, zebra-row, zebra-column
  • tableLayout: auto or equal
  • zebraOpacity: decimal 0.0...1.0 or percent-style 0...100
  • notify: 1/true / 0/false — persist notify-on-change in the payload (each device notifies locally after it applies a changed display state)
  • notifyOnce: 1/true — one-shot notify for this URL only if display content changes (does not persist)
  • actionKind: widget tap/click action kind: open-url, open-app, run-shortcut, or run-command
  • actionValue: value for actionKind: URL, macOS bundle identifier, Shortcut name, or shell command
  • clearAction: 1/true — remove the saved widget tap/click action

Action support is platform-specific. macOS supports all four action kinds. iOS supports URL and Shortcut actions; synced macOS-only app and shell actions fall back to the normal widget open/update behavior.

Example URLs

Text + Icon

terminalwidget://update?target=widget1&text=Build%20Complete&icon=checkmark.circle.fill
terminalwidget://update?target=widget2&text=Deploy%20%F0%9F%9A%80&icon=%3Arocket%3A

Progress

terminalwidget://update?target=widget1&text=Syncing&progress=42
terminalwidget://update?target=widget1&text=Transfer%20Queue&progress=63&progressFormat=gradient-vertical&gradientFrom=%234fd1ff&gradientWidth=32&caption=1

Charts

terminalwidget://update?target=widget3&chart=4,8,15,16,23,42&chartFormat=peak
terminalwidget://update?target=widget3&chart=5,12,8,21,13,34&chartFormat=graph&annotate=1&caption=true
terminalwidget://update?target=widget3&chart=1,4,9,3&chartFormat=sparkline&labelY=1&timestamp=1
terminalwidget://update?target=widget1&progress=50&caption=1&timestamp=1
terminalwidget://update?target=widget3&chart=1,4,9,3,8,2,7,5&chartFormat=matrix&padding=0
terminalwidget://update?target=widget3&chart=1-3,2-3,1-4&chartFormat=rangebar

Images + Filters

terminalwidget://update?target=widget2&image=https%3A%2F%2Fpicsum.photos%2F640%2F360&padding=fill
terminalwidget://update?target=widget2&image=https%3A%2F%2Fpicsum.photos%2F640%2F640&filter=sepia%3A25%2Cblur%3A8
terminalwidget://update?target=widget2&image=%2FUsers%2Fyou%2FPictures%2Fstatus.png&padding=12

Tables

terminalwidget://update?target=widget1&table=%2FUsers%2Fyou%2Fstatus.csv&grid=zebra&tableLayout=auto&zebraOpacity=60
terminalwidget://update?target=widget1&table=%2FUsers%2Fyou%2Fstatus.tsv&grid=both&tableLayout=equal
terminalwidget://update?target=widget1&table=%2FUsers%2Fyou%2Fstatus.json&grid=none

Colors + Theme

terminalwidget://update?target=widget2&theme=dark&fg=%23ffffff&bg=%23111417
terminalwidget://update?target=widget2&text=Light%20Mode%20Test&icon=sun.horizon&theme=light
terminalwidget://update?target=widget2&text=Alpha%20Override&fg=%23ffcc00&bg=%230f172a&alpha=0.85

Combined Payloads

terminalwidget://update?target=widget1&text=CPU%2062%25&icon=cpu.fill&chart=58,61,66,62,64,62&chartFormat=strip
terminalwidget://update?target=widget1&text=Night%20Audit&icon=moon.stars.fill&progress=91&theme=dark&fg=%23dbeafe&bg=%230b1220

Notify on change

terminalwidget://update?target=widget1&text=Service%20OK&notify=1
terminalwidget://update?target=widget1&text=Deploy%20done&notifyOnce=1

Widget tap actions

terminalwidget://update?target=widget1&text=Open%20dashboard&icon=arrow.up.right.square&actionKind=open-url&actionValue=https%3A%2F%2Fexample.com%2Fdashboard
terminalwidget://update?target=widget1&text=Run%20Backup&icon=externaldrive.fill&actionKind=run-shortcut&actionValue=Start%20Backup
terminalwidget://update?target=widget1&text=Open%20Transmission&icon=arrow.up.right.square&actionKind=open-app&actionValue=org.m0k.transmission
terminalwidget://update?target=widget1&text=Run%20script&icon=terminal&actionKind=run-command&actionValue=say%20Done
terminalwidget://update?target=widget1&clearAction=1

Opening the dispatch endpoint runs the action currently saved for the target:

terminalwidget://action?target=widget1

Building URLs in Scripts

When generating URLs from scripts, always URL-encode dynamic values:

TARGET="widget1"
TEXT="$(python3 -c 'import urllib.parse; print(urllib.parse.quote("Build complete #42"))')"
open "terminalwidget://update?target=${TARGET}&text=${TEXT}&icon=checkmark.circle.fill"

Shortcuts Tip

In Shortcuts, use URL Encode on text values before building the URL string, then call Open URLs.

For native Shortcuts actions (which avoid manual URL encoding), see Shortcuts Documentation.