Terminal Widget AppleScript

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.
• [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 in the caption area (charts or progress).
• [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.
• [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.
• [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.
• [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.
• [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.