TerminalWidget

TerminalWidget 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.

Add a widget first. URL updates only appear on widgets you place yourself (Desktop or Home Screen) after you set Edit Widget → Target name to match target=. See Integrations → Getting Started.

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) TerminalWidget.
  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 (may include CommonMark-style [label](url) links; see note below)
  • icon: SF Symbol name or GitHub :emoji: shortcode (for example :rocket:)
  • 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; series uses the same slash syntax; pie uses CPU:45 Memory:30 Disk:25 or label:value[:color] tokens)
  • append: append chart columns (same syntax as chart) or text lines to the existing target; incompatible with chart/text in the same URL
  • limit: keep the last N chart columns or text lines (persisted); 0 clears the soft limit
  • chartFormat: sparkline, graph, series/lines/multiline, pie, area, matrix, rangebar, etc. Grouped slash chart values require sparkline/spark/bar. Multi-series lines use series; pie slices use pie.
  • chartKey (or chart-key): legend placement for series and pie: auto, inline/left, bottom, external, or none. Pie on medium/extra-large widgets shows a side legend for auto/inline/left.
  • chartSeriesLabels (or chart-series-labels): comma-separated legend labels for series charts (order matches slash-separated groups).
  • keyTarget (or key-target): second widget target for an external legend (for example cpu-key). Pair with chartKey=external. The key widget inherits fg, bg, gradient, and padding from the chart update.
  • 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.
  • title (or widgetTitle / widget-title): optional top title (chart, text, image, progress); GitHub :emoji: shortcodes expand
  • titleAlignment (or title-alignment / widgetTitleAlignment): left, center, or right (default center when title is set)
  • captionText (or caption-text): custom footer text (implies caption=1; replaces auto min/max or percent captions); :emoji: shortcodes expand
  • 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 at the bottom (any widget type when no footer already shows it)
  • image: local file path or image URL
  • backgroundImage (or background-image): local file path or image URL rendered full-bleed behind text, icons, progress, charts, or tables; mutually exclusive with image
  • 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, custom caption text, and timestamp text; omit to match foreground
  • titleColor (or title-color): title text color; omit to match foreground
  • bg: background color
  • alpha: 0.0...1.0 (applies to foreground, background, text color, caption color, and title color when those are set)
  • table: .csv, .tsv, or .json path
  • grid: none, row, column, both, zebra, zebra-row, zebra-column
  • tableLayout: auto (content-sized; leftover space after the last column), equal, or fill. Pair auto with tableCenter=1 to center the hugged table instead.
  • tableAlign: comma-separated left, center, or right (aliases l/c/r, leading/trailing). Too few values repeat the last column; extras are ignored. Also stored on the tablePayload JSON envelope as tableAlign. Empty tableAlign= clears to the default (all left).
  • tableCenter (aliases table-center, centerTable, center-table): 1/true to center an auto-sized table horizontally; 0/false or empty tableCenter= clears. Ignored for equal and fill. Also stored on the tablePayload JSON envelope as tableCenter.
  • 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

Widget body text may include CommonMark-style [label](url) links. The widget renders them as tappable buttons; non-link taps still use actionKind / actionValue.

Launcher button grids (buttons, borders, button-columns) are not available as URL query parameters. Set them with CLI --json (or another structured JSON update). See Widgets.

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=widget1&text=Build%20queue&title=%F0%9F%93%88%20Throughput&captionText=Updated%20%E2%8F%B0&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
terminalwidget://update?target=widget1&chart=1%204%209%203/2%205%208%204/6%207%205%202&chartFormat=series&chartSeriesLabels=CPU,Memory,Disk&fg=%23f87171,%234ade80,%2360a5fa&bg=%230f172a
terminalwidget://update?target=widget1&chart=CPU:45%20Memory:30%20Disk:25&chartFormat=pie&fg=%23f87171,%234ade80,%2360a5fa&bg=%230f172a
terminalwidget://update?target=cpu&chart=CPU:45%20Memory:30%20Disk:25&chartFormat=pie&chartKey=external&keyTarget=cpu-key&bg=%230f172a&fg=%23e2e8f0
terminalwidget://update?target=widget3&chart=1,4,9,3,8,2,7,5&chartFormat=sparkline&limit=20
terminalwidget://update?target=widget3&append=10,12&limit=20

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
terminalwidget://update?target=widget1&backgroundImage=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1506905925346-21bda4d32df4%3Fauto%3Dformat%26fit%3Dcrop%26w%3D1600%26q%3D80&filter=alpha%3A40&text=Austin%2084

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.csv&grid=zebra&tableLayout=fill
terminalwidget://update?target=widget1&tablePayload=...&tableAlign=left,right,center
terminalwidget://update?target=widget1&tablePayload=...&tableLayout=auto&tableCenter=1
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.