TerminalWidget2.1.9 - App Store

Scripters rejoice! Now you can have output from your scripts, AppleScripts, and Shortcuts display in widgets on iOS (and sync to and from your Mac via iCloud). You can see progress indicators, charts, graphs, icons, tables, and more. All controllable via Shortcuts or with a URL scheme (and a CLI on Mac). This is a universal purchase for the Mac, iOS, and Watch apps.

Version History ### CHANGED

- Widget gallery description mentions Home Screen and Lock Screen sizes
- Open at Login no longer shows a redundant "Open at Login enabled/disabled" note under the On/Off toggle; failures are still reported

### NEW

- Lock Screen widgets support rectangular and circular sizes on iPhone using the same target as the Home Screen widget
- Lock Screen rectangular shows text-first content (icon plus stripped text, optional progress), then progress, image, or a mini chart when text is absent
- Lock Screen circular shows a progress ring when percent is set, otherwise the SF Symbol icon or a letter fallback
- Widget Recipes item in the menu bar menu opens the recipes page

### IMPROVED

- Lock screen images load once and fall back to the empty state if decode fails
- Lock Screen text starts larger and scales down to fit, with a higher ceiling when --fit-text is set

### FIXED

- Lock screen text strips ANSI from widget titles as well as body text
- Lock Screen short text no longer stays tiny when --fit-text only bumped the text style
- iCloud sync from the Mac no longer marks a widget as synced until CloudKit confirms the upload, so iPhone widgets stop getting stuck on an older revision
- Running the app binary with no arguments while TerminalWidget is already running no longer launches a second menu bar instance; it prints the help text to stderr and exits with status 2
- terminal-widget symlink with no arguments now correctly detects whether the app is running instead of always reporting that it is 2.1.9 Sep 30 #### NEW

- Lock Screen widgets support rectangular and circular sizes on iPhone using the same target as the Home Screen widget
- Lock Screen rectangular shows text-first content (icon plus stripped text, optional progress), then progress, image, or a mini chart when text is absent
- Lock Screen circular shows a progress ring when percent is set, otherwise the SF Symbol icon or a letter fallback

#### IMPROVED

- Lock screen images load once and fall back to the empty state if decode fails

#### FIXED

- Lock screen text strips ANSI from widget titles as well as body text 2.1.8 Sep 5 ### NEW

- terminal-widget log subcommand reads the bounded diagnostic event log from the App Group (--level, --target, --limit, --follow, --json, --clear).
- twdiags widgets on Mac and iOS render the device-local event log as text while keeping that target's styling; each device shows its own events only (no cross-device mirroring).
- Info/Debug recent events on Mac lists the last fifty diagnostic events and includes them when copying cloud diagnostics.
- Diagnostic event log records silent failures from the host app, CLI, and widget extension into one local JSONL store in the App Group.
- Button command outcomes capture nonzero exits, stderr, slow runs, and signal kills for widget run-command actions instead of failing quietly.
- Missing widget images are recorded when a payload claims an image the renderer cannot load on Mac and iOS.
- Image fetch, copy, write, and App Group fallback failures are recorded instead of failing quietly.
- Save, iCloud pull/push/retry/subscribe, payload decode, and table clamp failures are recorded in the diagnostic log on Mac and iOS.
- Autoupdate shortcut and image refresh failures are recorded in the diagnostic log.
- Chart data truncation and open handoff failures from the CLI are recorded in the diagnostic log.
- Widget button actions with an unknown kind, invalid URL, or missing app bundle are recorded instead of failing silently on Mac and iOS.
- Widget reload requests and timeline builds are paired in the log so stalled refreshes are easier to spot on Mac and iOS.

### IMPROVED

- Fish and bash completions key off the first positional subcommand so flag values that look like subcommand names no longer steal completions (including log subcommand flags).
- Noisy diagnostic codes can be throttled per target so repeated reload, sync, and timeline events do not flood the log.
- terminal-widget log --follow flushes stdout so piped output appears promptly while tailing the log.

### FIXED

- Hiding the menu bar icon no longer quits the app, so Control Center or a menu bar manager can park the item and bring it back instead of leaving no process to restore.
- Quit TerminalWidget, logout, and shutdown still exit normally after an intentional quit.
- Shortcuts and URL-scheme updates on iOS that fail validation or cannot save the payload now record the failure instead of failing quietly.
- Failing button commands slower than the timeout now record their exit instead of stopping at a still running warning that implied success.
- Commands killed by a signal are recorded as failures rather than being treated as a clean exit.
- terminal-widget log --json no longer prints prose on stdout when the log is empty, so piping to jq works instead of failing on the first line.
- terminal-widget log --clear is refused alongside --target, --level, --limit, or --follow instead of accepting filters and then deleting every target's events anyway. 2.1.6 Aug 26 ### CHANGED

- Idle widget taps remain inert when no --action-kind is set (placeholder Hello World does not clear on click).

### NEW

- Pie charts with --chart-format pie and label:value[:color] tokens (space- or comma-separated), optional per-slice colors, JSON slices arrays, inline side legend on medium/extra-large widgets, and percentage labels in the legend.
- Multi-series line charts with --chart-format series (slash-separated groups), shared Y scaling, and optional --chart-series-labels for legend names.
- --chart-key legend placement (auto, inline/left, bottom, external, none) for pie and series charts on macOS and iOS widgets.
- --key-target to write legend rows to a second widget (for example cpu-key), including legend-only key widgets that inherit colors from the main chart and scale text to fill the widget.
- --chart-bar-style glass support for pie slices (liquid glass wedge fills).
- Quad4 multi-goal progress with comma-separated --progress values, --progress-format quad4 (quad-4 alias), and optional --progress-layout grouping across CLI, URL, AppleScript, Shortcuts, and JSON.

### IMPROVED

- Matrix charts keep up to 2048 cells (was 128, same as sparklines) and shrink cell size to fit the widget so extra-large heatmaps can show a dense series.
- Series line colors now match legend swatches instead of using a single foreground color for every line.
- External key widgets inherit foreground, background, gradient, and padding from the main chart update.
- --fit-text for tables grows cell fonts until width or height binds, persists on table updates, and vertically centers with --center-table (auto layout).
- Table fit-text width safety so grown cells stop before truncating, instead of overshooting into ellipses.
- --font on tables uses the same installed font for cells and column measurement as --text (macOS and iOS).

### FIXED

- Figlet and other --no-wrap ASCII blocks no longer clip the first lines in WidgetKit. Multiline terminal art is rasterized to an image, scaled with the same 10pt inset as --padding fill, and centered when --fit-text is on.
- Comma-separated pie literals such as Work:40,Play:25,Sleep:35 now parse correctly (commas inside rgb(...) colors are preserved).
- iOS pie/series widget updates by adding pie, series, and legend fields to the host app payload and URL handler so Shortcuts and URL updates persist and reload widgets.
- External key widget updates from CLI and URL scheme now write legend payloads to the --key-target widget instead of leaving it on the placeholder.
- Whole-widget taps on Mac and iPhone/iPad use App Intents (same path as launcher buttons) so configured actions keep working when custom-scheme widgetURL delivery fails. 2.1.5 Aug 21 ### NEW

- Pie charts with --chart-format pie and label:value[:color] tokens (space- or comma-separated), optional per-slice colors, JSON slices arrays, inline side legend on medium/extra-large widgets, and percentage labels in the legend.
- Multi-series line charts with --chart-format series (slash-separated groups), shared Y scaling, and optional --chart-series-labels for legend names.
- --chart-key legend placement (auto, inline/left, bottom, external, none) for pie and series charts on macOS and iOS widgets.
- --key-target to write legend rows to a second widget (for example cpu-key), including legend-only key widgets that inherit colors from the main chart and scale text to fill the widget.
- --chart-bar-style glass support for pie slices (liquid glass wedge fills).

### IMPROVED

- Series line colors now match legend swatches instead of using a single foreground color for every line.
- External key widgets inherit foreground, background, gradient, and padding from the main chart update.

### FIXED

- Comma-separated pie literals such as Work:40,Play:25,Sleep:35 now parse correctly (commas inside rgb(...) colors are preserved).
- iOS pie/series widget updates by adding pie, series, and legend fields to the host app payload and URL handler so Shortcuts and URL updates persist and reload widgets.
- External key widget updates from CLI and URL scheme now write legend payloads to the --key-target widget instead of leaving it on the placeholder. 2.1.4 Aug 20 ### IMPROVED

- Matrix charts keep up to 2048 cells (was 128, same as sparklines) and shrink cell size to fit the widget so extra-large heatmaps can show a dense series.

### FIXED

- Figlet and other --no-wrap ASCII blocks no longer clip the first lines in WidgetKit. Multiline terminal art is rasterized to an image, scaled with the same 10pt inset as --padding fill, and centered when --fit-text is on. 2.1.3 Aug 19 ### CHANGED

- Auto table columns hug their measured text instead of stretching leftover width into every cell. Extra space stays after the last column; use --table-layout equal for uniform columns that fill the widget.

### NEW

- Center table (--center-table) centers a content-sized table horizontally instead of leaving leftover space after the last column. Applies only to auto layout and is ignored for equal and fill. Also on AppleScript, Shortcuts, JSON, and the URL scheme.
- Per-column table alignment with --table-align (left, center, or right, plus short aliases). Too few values repeat the last column; extras are ignored. Default is all left. Also on AppleScript, Shortcuts, JSON, and the URL scheme.
- Table layout fill (--table-layout fill) measures columns from content then stretches them proportionally to the widget width (the previous auto behavior). Also on AppleScript, Shortcuts, JSON, and the URL scheme. 2.1.2 Aug 18 ### NEW

- Background image for all chart types
- Quadrant progress widgets with segmented arcs on Mac and mobile
- Quadrant progress via AppleScript and Shortcuts update requests
- Auto-update recipes for Shortcut re-run or http(s) image refresh on Mac host timers
- Open at Login keeps the menu bar app and timers running across reboots
- Shortcuts Run Every fields configure shortcut auto-update from Update TerminalWidget

### IMPROVED

- Markdown link labels can include nested square brackets (for example [Item [nested]](https://example.com))
- Quadrant progress captions match circle progress layout and footer behavior
- CLI progress formats parse, document, complete, and emit quadrant payloads

### FIXED

- Quadrant progress arc direction, segment gaps, and full-ring stroke thickness
- Quadrant URL updates preserve the quadrant progress format on Mac and mobile 2.1.1 Aug 17 ### NEW

- Quadrant progress widgets with segmented arcs on Mac and mobile
- Quadrant progress via AppleScript and Shortcuts update requests
- Auto-update recipes for Shortcut re-run or http(s) image refresh on Mac host timers
- Open at Login keeps the menu bar app and timers running across reboots
- Shortcuts Run Every fields configure shortcut auto-update from Update TerminalWidget

### IMPROVED

- Markdown link labels can include nested square brackets (for example [Item [nested]](https://example.com))
- Quadrant progress captions match circle progress layout and footer behavior
- CLI progress formats parse, document, complete, and emit quadrant payloads

### FIXED

- Quadrant progress arc direction, segment gaps, and full-ring stroke thickness
- Quadrant URL updates preserve the quadrant progress format on Mac and mobile 2.1.0 Aug 14 ### IMPROVED

- Markdown link labels can include nested square brackets (for example [Item [nested]](https://example.com)) 2.0.10 Aug 11 ### IMPROVED

- ANSI colors apply to text next to markdown links (for example a colored flag prefix before a tappable [label](url)) 2.0.9 Aug 10 ### CHANGED

- Image URL imports now use authorized image folders before asking you to choose a file.
- Synced transparent images materialize as PNG (opaque photos still use JPEG) so widget backgrounds show through after sync.

### NEW

- Extra Large widget size on Mac and on iPad/Home Screen where the OS offers it.
- Table cells (CSV/TSV/JSON, including headers) support CommonMark [label](url) inline links on Mac and iPhone/iPad, same rules and tap behavior as --text links.
- Image folders (Info/Debug on Mac) let you grant one or more folders so CLI, AppleScript, and Shortcuts can load local images without a permission prompt for every file.

### IMPROVED

- Extra Large layouts scale text, tables, charts, and progress intentionally (not just a stretched Large).
- Launcher buttons can use up to four columns on Extra Large widgets.
- GUI startup avoids duplicate activation verification.
- In-app help explains the permission prompt and what to do if TerminalWidget is missing from Settings > Notifications.
- Local image imports try granted folders first, then fall back to a file chooser when the app can prompt (including AppleScript/Shortcuts), instead of failing silently.
- AppleScript image updates now offer the image chooser when a supplied image URL cannot be read.

### FIXED

- Mac open-url and markdown link taps now open in the system default browser (including Choosy or Zen) instead of always preferring Safari.
- Widget taps with no action do nothing on Mac and iPhone/iPad instead of opening Terminal Widget.
- Image-folder imports continue to later granted folders when an earlier access attempt does not copy the file.
- Image folder list stays current when widgets reload from disk or CLI sync.
- iCloud image sync keeps transparency for PNG/alpha sources instead of flattening them to white JPEG on Mac and iPhone/iPad.
- Stale white JPEG sync blobs refresh when the on-disk source image still has alpha. 2.0.8 Aug 10 ### CHANGED

- Image URL imports now use authorized image folders before asking you to choose a file.
- Synced transparent images materialize as PNG (opaque photos still use JPEG) so widget backgrounds show through after sync.

### NEW

- Table cells (CSV/TSV/JSON, including headers) support CommonMark [label](url) inline links on Mac and iPhone/iPad, same rules and tap behavior as --text links.
- Image folders (Info/Debug on Mac) let you grant one or more folders so CLI, AppleScript, and Shortcuts can load local images without a permission prompt for every file.

### IMPROVED

- GUI startup avoids duplicate activation verification.
- In-app help explains the permission prompt and what to do if TerminalWidget is missing from Settings > Notifications.
- Local image imports try granted folders first, then fall back to a file chooser when the app can prompt (including AppleScript/Shortcuts), instead of failing silently.
- AppleScript image updates now offer the image chooser when a supplied image URL cannot be read.

### FIXED

- Mac open-url and markdown link taps now open in the system default browser (including Choosy or Zen) instead of always preferring Safari.
- Widget taps with no action do nothing on Mac and iPhone/iPad instead of opening Terminal Widget.
- Image-folder imports continue to later granted folders when an earlier access attempt does not copy the file.
- Image folder list stays current when widgets reload from disk or CLI sync.
- iCloud image sync keeps transparency for PNG/alpha sources instead of flattening them to white JPEG on Mac and iPhone/iPad.
- Stale white JPEG sync blobs refresh when the on-disk source image still has alpha. 2.0.7 Aug 7 ### CHANGED

- --fit-text scaling is skipped when any markdown link is present so link hit targets stay reliable.
- iOS launcher buttons mute open-app and run-command (unsupported) while open-url, run-shortcut, and refresh still work.

### NEW

- Markdown links in widget text use CommonMark [label](url) syntax and render as tappable buttons on macOS and iOS.
- Link taps open the linked URL while non-link areas keep the existing widget tap/--action-kind behavior.
- Launcher buttons via JSON buttons (label, color, action-type, action-value; max 12) render as a tappable footer grid under any widget content on macOS and iOS.
- button-columns accepts smart/auto or 1/2/3 to force the footer grid; omit keeps the previous setting, and "buttons": [] clears buttons.
- Smart button layout on medium/large uses 3 columns when the count is divisible by 3, otherwise 2, pads incomplete rows for uniform widths, and keeps small widgets single-column.
- Button borders support per-button border / border-color / border-width (0-12) / border-radius (0-48) plus root defaults via button-border, button-border-color, button-border-width, and button-border-radius.
- Border shorthand accepts values like 2px #0f0aff (either order); color alone implies width 1, and omitted radius defaults to 8.
- Button tap intents ship for macOS and iOS so launcher actions run from the widget (host intents handle refresh/run-command).

### IMPROVED

- Buttons-only widgets vertically center the button grid when there is no other content.
- Edit Widget shows only Target name and hides the internal Instance ID field.

### FIXED

- --json overlays now persist text, colors, theme, and related fields instead of dropping them when only JSON supplied those values.
- Inline --json '{...}' is accepted as JSON instead of being treated as a missing file path.
- URL and app opens from widget buttons and markdown links stay on the Mac instead of Continuity-handing off to iPhone.
- Edit Widget target names (including widget1) are always honored instead of being remapped onto widgetN via the instance registry.
- Instance registry repair no longer wipes mappings just because many named CLI targets exist.
- Mac widget gallery shows "Terminal Widget" again so Desktop widgets are easier to find beside Continuity copies.
- Invalid launcher icons ASCII names that are not valid SF Symbols now leave the reserved gutter empty.
- Widget taps without a configured action on macOS now open the non-mutating action URL instead of update?target=, which was rebuilding an empty payload and blanking the widget.
- Target-only update URLs are ignored on macOS and iOS so stale widget timelines cannot wipe existing content. 2.0.6 Aug 6 - Fix for widgets blanking when tapped 2.0.5 Aug 4 ### CHANGED

- Chart hard max keeps the newest 128 points instead of the oldest when series overflow.
- --fit-text scaling is skipped when any markdown link is present so link hit targets stay reliable.
- iOS launcher buttons mute open-app and run-command (unsupported) while open-url, run-shortcut, and refresh still work.

### NEW

- --append adds chart columns (same syntax as --chart, including slash-grouped series and rangebar low-high pairs) or text lines to an existing widget while preserving unrelated settings.
- --limit N keeps the newest N chart columns or text lines in storage, persists on the target, works with chart/text/append or alone, and uses 0 to clear the soft limit.
- Append and limit are available from CLI, AppleScript, Shortcuts, URL scheme, and structured JSON with shape checks for incompatible chart data.
- Markdown links in widget text use CommonMark [label](url) syntax and render as tappable buttons on macOS and iOS; link taps open the URL while non-link areas keep the existing widget tap/--action-kind behavior.
- Launcher buttons via JSON buttons (label, color, action-type, action-value; max 12) render as a tappable footer grid under any widget content on macOS and iOS.
- button-columns accepts smart/auto or 1/2/3 to force the footer grid; omit keeps the previous setting, and "buttons": [] clears buttons.
- Smart button layout on medium/large uses 3 columns when the count is divisible by 3, otherwise 2, pads incomplete rows for uniform widths, and keeps small widgets single-column.
- Button borders support per-button border / border-color / border-width (0-12) / border-radius (0-48) plus root defaults via button-border, button-border-color, button-border-width, and button-border-radius.
- Border shorthand accepts values like 2px #0f0aff (either order); color alone implies width 1, and omitted radius defaults to 8.

### IMPROVED

- Buttons-only widgets vertically center the button grid when there is no other content.
- Edit Widget shows only Target name and hides the internal Instance ID field.

### FIXED

- --json overlays now persist text, colors, theme, and related fields instead of dropping them when only JSON supplied those values.
- Inline --json '{...}' is accepted as JSON instead of being treated as a missing file path.
- URL and app opens from widget buttons and markdown links stay on the Mac instead of Continuity-handing off to iPhone.
- Edit Widget target names (including widget1) are always honored instead of being remapped onto widgetN via the instance registry.
- Instance registry repair no longer wipes mappings just because many named CLI targets exist.
- Mac widget gallery shows "Terminal Widget" again so Desktop widgets are easier to find beside Continuity copies. 2.0.4 Aug 4 ### CHANGED

- Chart hard max keeps the newest 128 points instead of the oldest when series overflow.
- Allow users to disable iCloud syncing

### NEW

- --append adds chart columns (same syntax as --chart, including slash-grouped series and rangebar low-high pairs) or text lines to an existing widget while preserving unrelated settings.
- --limit N keeps the newest N chart columns or text lines in storage, persists on the target, works with chart/text/append or alone, and uses 0 to clear the soft limit.
- Append and limit are available from CLI, AppleScript, Shortcuts, URL scheme, and structured JSON with shape checks for incompatible chart data. 2.0.3 Aug 2 2.0.1 Jul 30