Terminal Widget

Terminal Widget AppleScript

Download on the Mac App Store Download on the App Store

Use Terminal Widget’s AppleScript dictionary to update widgets from Script Editor, AppleScript apps, and automation tools.

Usage

tell application "TerminalWidget"
render widget target "widget1" text "Hello from AppleScript" icon "terminal.fill"
end tell

Commands

  • render widget Full update command with named parameters (text, icon, chart, progress, image, table, theme, colors, layout, and formatting options)
  • render text Convenience command for text updates
  • render chart Convenience command for chart updates
  • render progress Convenience command for progress updates
  • render image Convenience command for image updates
  • render table Convenience command for table updates

Examples

tell application "TerminalWidget"
render widget target "widget1" text "Deploy done" icon "checkmark.circle.fill" ¬
notify true
render chart target "widget1" chart "1 2 3 4 5" chart format "smooth" ¬
annotation true caption true timestamp true
render chart target "widget1" chart "0 1 5 2/1 2 5 3" chart format "bar" ¬
foreground "#cc0000,#00cc00,#0000cc" annotation true
render chart target "widget1" chart "1-3 2-3 1-4" chart format "rangebar"
render progress target "widget1" progress 72 ¬
progress format "circle" chart bar style "glass" caption true
render progress target "widget1" progress 72 ¬
progress format "gradient-horizontal" ¬
gradient from "#38bdf8" gradient to "#0ea5e9" gradient width 24 ¬
caption true timestamp true
render text target "widget1" text "Build passed" icon "checkmark.circle.fill"
render image (POSIX file "/tmp/status.png") target "widget1" ¬
filter "sepia:65,blur:8" full width true
render image "/tmp/status.png" target "widget1" padding "12"
render widget image (POSIX file "/tmp/status.png") target "widget1"
end tell

Dictionary

Explore the dictionary in Script Editor with File->Open Dictionary (⇧⌘O). Select TerminalWidget from the dictionary selection window.

render widget v : Apply a full widget update using CLI-style options.

  • [target text] : Widget target identifier.
  • [text text] : Widget text content.
  • [icon text] : SF Symbol or emoji icon.
  • [theme text] : Theme: system, light, or dark.
  • [font text] : Font family name.
  • [font size real] : Font size in points.
  • [foreground text] : Foreground color. Comma-separated values use the first for text/icons and the full list for grouped sparkline series colors.
  • [background text] : Background color value.
  • [alpha real] : Global alpha from 0 to 1.
  • [padding text] : Padding value or fill.
  • [chart text] : Chart data: space-separated numbers, slash-separated grouped sparkline/bar series (for example 0 1 5 2/1 2 5 3, up to four series), rangebar low-high pairs, or JSON (flat array or nested numeric series).
  • [chart format text] : Chart format name.
  • [bar radius integer] : Sparkline bar corner radius percentage (0–100).
  • [chart bar style text] : solid (default) or glass for sparkline/bar, waveform, rangebar, matrix, delta charts, and circle progress rings.
  • [annotation boolean] / [annotate boolean] : Enable chart annotation.
  • [title text] : Optional title at the top of chart, text, image, or progress widgets (:emoji: shortcodes expand).
  • [title alignment text] : Title alignment: left, center (default when title is set), or right.
  • [title color text] : Title color (hex/rgb/rgba); defaults to foreground.
  • [caption text text] : Custom footer below content (implies caption; replaces auto min/max or percent). :emoji: shortcodes expand (for example :white_check_mark: → ✅).
  • [caption boolean] : Show [min/max] or [n%] caption when applicable.
  • [label y boolean] : Show y-axis labels on numeric charts.
  • [timestamp boolean] : Show last update time at the bottom (any widget type when no footer already shows it).
  • [progress integer] : Progress percentage 0–100.
  • [progress format text] : Progress style (bar, matrix, dots, stack, circle, watch, gradient-horizontal, gradient-vertical).
  • [gradient from text] : Gradient start color.
  • [gradient to text] : Gradient end color.
  • [gradient width integer] : Gradient width in pixels.
  • [image text] : Path or URL to image.
  • [filter text] : Image filter specification.
  • [table text] : Table content payload.
  • [header boolean] : Show table header row.
  • [grid text] : Table grid style.
  • [table layout text] : Table layout mode.
  • [zebra opacity real] : Zebra striping opacity from 0 to 1.
  • [status coloring boolean] : Enable semantic table status coloring.
  • [notify boolean] : Persist notify-on-change for this target (local notification when display content changes).
  • [notify once boolean] : Notify only for this command when display content changes (does not change persisted setting).
  • [action kind text] : Widget tap/click action kind: open-url, open-app, run-shortcut, or run-command.
  • [action value text] : URL, bundle identifier, Shortcut name, or shell command for the action.
  • [clear action boolean] : Remove the persisted widget tap/click action.

render text v : Convenience wrapper for text updates.

  • [target text] : Widget target identifier.
  • [text text] : Widget text content.
  • [icon text] : SF Symbol or emoji icon.
  • [theme text] : Theme: system, light, or dark.
  • [title text] : Optional title at the top (:emoji: shortcodes expand).
  • [title alignment text] : Title alignment: left, center, or right.
  • [title color text] : Title color (hex/rgb/rgba); defaults to foreground.
  • [caption text text] : Custom footer below content (:emoji: shortcodes expand).
  • [timestamp boolean] : Show last update time at the bottom.
  • [notify boolean] : Persist notify-on-change for this target.
  • [notify once boolean] : One-shot notify for this command only.

render chart v : Convenience wrapper for chart updates.

  • [target text] : Widget target identifier.
  • [chart text] : Chart data (slash-separated series for grouped sparkline/bar, or JSON).
  • [chart format text] : Chart format name, such as sparkline, graph, matrix, or rangebar.
  • [bar radius integer] : Sparkline bar corner radius percentage (0–100).
  • [chart bar style text] : solid or glass for compatible bar chart modes.
  • [annotation boolean] / [annotate boolean] : Enable chart annotation.
  • [title text] : Optional title at the top (:emoji: shortcodes expand).
  • [title alignment text] : Title alignment: left, center, or right.
  • [title color text] : Title color (hex/rgb/rgba); defaults to foreground.
  • [caption text text] : Custom footer text (:emoji: shortcodes expand).
  • [caption boolean] : Show [min/max] caption below the chart.
  • [label y boolean] : Show y-axis labels on numeric charts.
  • [timestamp boolean] : Show last update time below the caption (with or without caption).
  • [notify boolean] : Persist notify-on-change for this target.
  • [notify once boolean] : One-shot notify for this command only.

render progress v : Convenience wrapper for progress updates.

  • [target text] : Widget target identifier.
  • [progress integer] : Progress percentage from 0 to 100.
  • [title text] : Optional title at the top (:emoji: shortcodes expand).
  • [title alignment text] : Title alignment: left, center, or right.
  • [title color text] : Title color (hex/rgb/rgba); defaults to foreground.
  • [caption text text] : Custom footer text (:emoji: shortcodes expand).
  • [caption boolean] : Show [n%] with bar/matrix/etc. progress styles when applicable.
  • [timestamp boolean] : Show last update time in the caption area.
  • [progress format text] : Progress style (bar, matrix, dots, stack, circle, watch, gradient-horizontal, gradient-vertical).
  • [chart bar style text] : glass for a glossy circle ring when progress format is circle (aliases: chart bar style, chart-bar-style).
  • [gradient from text] : Gradient start color.
  • [gradient to text] : Gradient end color.
  • [gradient width integer] : Gradient width in pixels.
  • [foreground text] : Foreground color (ring color for circle progress).
  • [background text] : Background color value.
  • [notify boolean] : Persist notify-on-change for this target.
  • [notify once boolean] : One-shot notify for this command only.

render image v : Convenience wrapper for image updates.

  • [target text] : Widget target identifier.
  • [image text] : Path or URL to image.
  • [filter text] : Image filter specification.
  • [title text] : Optional title at the top (:emoji: shortcodes expand).
  • [title alignment text] : Title alignment: left, center, or right.
  • [title color text] : Title color (hex/rgb/rgba); defaults to foreground.
  • [caption text text] : Custom footer text (:emoji: shortcodes expand).
  • [timestamp boolean] : Show last update time at the bottom.
  • [full width boolean] : Enable full-width content layout.
  • [padding text] : Padding value or fill.
  • [notify boolean] : Persist notify-on-change for this target.
  • [notify once boolean] : One-shot notify for this command only.

render table v : Convenience wrapper for table updates.

  • [target text] : Widget target identifier.
  • [table text] : Table content payload.
  • [notify boolean] : Persist notify-on-change for this target.
  • [notify once boolean] : One-shot notify for this command only.

Notes

  • Grouped sparkline/bar charts use slash-separated segments in chart (for example 0 1 5 2/1 2 5 3) with chart format sparkline, spark, or bar. Pair with comma-separated foreground for per-series colors.
  • chart bar style glass on render progress with progress format circle draws a glossy ring without chart data.
  • AppleScript updates use the same request/validation pipeline as CLI and Shortcuts.
  • render image accepts either a direct value (render image "/tmp/file.png") or a POSIX file value.
  • annotation true and annotate true are treated as the same option.
  • If Script Editor does not recognize commands after an app update, relaunch Terminal Widget and reopen Script Editor.