TerminalWidget AppleScript

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

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

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, background 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 background image Convenience command for full-bleed background 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 4 9 3/2 5 8 4/6 7 5 2" chart format "series" ¬
chart series labels "CPU,Memory,Disk" foreground "#f87171,#4ade80,#60a5fa" background "#0f172a"
render chart target "widget1" chart "CPU:45 Memory:30 Disk:25" chart format "pie" ¬
foreground "#f87171,#4ade80,#60a5fa" background "#0f172a"
render widget target "cpu" chart "CPU:45 Memory:30 Disk:25" chart format "pie" ¬
chart key "external" key target "cpu-key" background "#0f172a" foreground "#e2e8f0"
render chart target "widget1" chart "1-3 2-3 1-4" chart format "rangebar"
render widget target "widget1" append data "6 7" limit 20
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"
render background image "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?auto=format&fit=crop&w=1600&q=80" ¬
target "widget1" filter "alpha:40"
render widget target "widget1" background image "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?auto=format&fit=crop&w=1600&q=80" ¬
filter "alpha:35" chart "4 8 15 16 23 42" text "Throughput"
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 or multi-series line groups (for example 0 1 5 2/1 2 5 3, up to four series), rangebar low-high pairs, pie label:value[:color] tokens (for example CPU:45 Memory:30 Disk:25), or JSON (flat array, nested numeric series, named series objects, or pie slices).
[append data text] : Append chart columns (same syntax as chart) or text lines to the existing widget. Named append data because append is reserved in AppleScript. Incompatible with replacing chart/text in the same command.
[limit integer] : Keep the last N chart columns or text lines (persisted). 0 clears the soft limit.
[chart format text] : Chart format name (sparkline, graph, series/lines/multiline, pie, matrix, rangebar, etc.).
[chart key text] : Legend placement for series and pie: auto, inline/left, bottom, external, or none. Pie on medium/extra-large widgets uses a side legend for auto/inline/left.
[chart series labels text] : Comma-separated legend labels for series charts (order matches slash-separated groups).
[key target text] : Second widget target for an external legend (for example cpu-key). Use with chart key external. The key widget inherits foreground, background, gradient, and padding from the chart update.
[bar radius integer] : Sparkline bar or range bar corner radius percentage (0–100).
[chart bar style text] : solid (default) or glass for sparkline/bar, waveform, rangebar, matrix, pie, 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, quadrant, 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.
[background image text] : Path or URL to a full-bleed background image. It can accompany text, progress, charts, or tables, but not 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 (auto, equal, or fill).
[table align text] : Per-column table text alignment (comma-separated left, center, or right; remaining columns repeat the last value).
[center table boolean] : Center an auto-sized table horizontally. Ignored for equal and fill layouts.
[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 multi-series lines, pie label:value tokens, or JSON).
[chart format text] : Chart format name, such as sparkline, graph, series, pie, matrix, or rangebar.
[chart key text] : Legend placement for series and pie (auto, inline/left, bottom, external, none).
[chart series labels text] : Comma-separated legend labels for series charts.
[key target text] : External legend widget target (pair with chart key external).
[bar radius integer] : Sparkline bar or range 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, quadrant, 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 background image v : Convenience wrapper for full-bleed background image updates.

[background image text] : Path or URL to the background image.
[target text] : Widget target identifier.
[filter text] : Image filter specification; use alpha:0-100 to fade the background.
[title text] : Optional title at the top.
[title alignment text] : Title alignment: left, center, or right.
[title color text] : Title color (hex/rgb/rgba).
[caption text text] : Optional footer text.
[timestamp boolean] : Show the last update time.
[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.
[header boolean] : Show table header row.
[grid text] : Table grid style.
[table layout text] : Table layout mode (auto, equal, or fill).
[table align text] : Per-column table text alignment (comma-separated left, center, or right; remaining columns repeat the last value).
[center table boolean] : Center an auto-sized table horizontally. Ignored for equal and fill layouts.
[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.
Multi-series line charts use chart format series (aliases lines, multiline) with the same slash syntax. Set chart series labels for custom legend names.
Pie charts use chart format pie with label:value[:color] tokens in chart. Use chart key inline/left for a side legend on medium/extra-large widgets, or chart key external with key target for a dedicated legend widget.
External key widgets inherit foreground, background, and padding from the chart update and scale legend text to fill the widget.
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.
render background image accepts a path, URL, or POSIX file value the same way.
annotation true and annotate true are treated as the same option.
If Script Editor does not recognize commands after an app update, relaunch TerminalWidget and reopen Script Editor.