Release notes for TerminalWidget. For installation and usage, see the
CLI, AppleScript, and widget gallery pages.
1.2.0
CHANGED
Preserve and round-trip neo chart character settings in widget payloads so neo rendering stays consistent across updates and devices.
Combining chart data with images is rejected from the CLI and automation (Shortcuts Update Widget and related flows); AppleScript dictionary notes that images omit chart data; terminalwidget URLs resolve chart-vs-image conflicts by dropping the conflicting side.
Existing Shortcuts that used the free-text Action Kind field on Update Terminal Widget may need that parameter re-selected after upgrading.
URL scheme handling accepts fitText and fit-text query keys as aliases for text full width alongside textFullWidth / text-full-width.
NEW
Grouped sparkline/bar charts accept slash-separated value sets in --chart (for example 0 1 5 2/1 2 5 3) with side-by-side sub-bars per column, shared Y scaling, default series opacity stepping, and comma-separated --foreground colors (first color for text/icons, full list for series). The same slash literal works in Shortcuts and AppleScript chart parameters; JSON chart input may use a nested numeric array (for example [[0,1,5],[1,2,5]]) which normalizes to the slash form for URLs and storage.
Circle progress format supports --chart-bar-style glass for a gradient glass ring (CLI, URL, Shortcuts, and AppleScript via existing chart bar style).
Add –base N and –base-zero so chart scaling can start from a fixed baseline instead of the series minimum.
Add a neo chart format with selectable katakana, ascii, or binary characters across CLI, URL updates, AppleScript, and Shortcuts on macOS and iOS.
Add –chart-height N[%] to CLI updates so chart widgets can be constrained by points or percent while keeping 100% as the default behavior.
Add chart height support to URL updates, AppleScript commands/dictionary, and Shortcuts intents on macOS and iOS so automation can set chart size consistently.
Add –bg-gradient-from, –bg-gradient-to, and –bg-gradient-start so widgets can render directional background gradients directly from the CLI.
Add background gradient parameters to URL updates, AppleScript, and Shortcuts (macOS and iOS) so automation workflows can set gradient colors and direction consistently.
Optional alpha in image filter specs; CLI expands tilde in local image paths and can hand off permission-restricted image files to the running app for import instead of failing silently; Show Chart shortcut intent exposes optional image path and filter when there is no chart.
Shortcuts widget tap action kind is a fixed picker (Open URL, Open App, Run Shortcut, Run Shell Command) instead of typing raw strings; optional tap action kind, value, and clear action are available on Show Terminal Widget Text, Chart, Progress, Image, and Table intents on macOS and iOS, not only Update Terminal Widget.
CLI --fit-text enables fitting text in text-only and text+icon layouts without enabling fill/full-width image behavior; AppleScript recognizes fit text / fit-text / fit-text as aliases for full-width-style fitting flags where mapped.
Apple Watch app lists iCloud-synced widget targets, opens a square preview with back navigation and remembers the last viewed target across launches, merges quick text edits into existing CloudKit JSON without stripping chart or table fields, and handles terminalwidgetwatch:// deep links from the complication.
Watch complication (accessory rectangular): CloudKit timelines with simplified chart or synced image preview, clear widget container background, one App Intent recommendation per known target (cached from the CloudKit index), no SF Symbol overlay, and plain text display with ANSI escape stripping.
Structured JSON refresh overlay and shared chart literal parsing through macOS and iOS automation, the bundled CLI, Shortcuts, and AppleScript update flows.
CLI and automation support for chart baseline (–base / –base-zero), neo chart character sets, chart height in points or percent, background gradient colors and direction, and fit-text for text layouts.
IMPROVED
Show mirrored y-axis labels for waveform charts so symmetric top/bottom halves read consistently with –label-y.
Support chart baseline values in AppleScript and Shortcuts chart updates for parity with CLI behavior.
Update chart rendering for neo mode with direction-aware y-axis labels and full-height layout behavior to better fit widget families.
Apply chart height constraints in macOS and iOS widget rendering so sparkline, graph, waveform, matrix, and rangebar charts respect explicit height overrides.
Keep gradient rendering stable across partial updates by preserving gradient output when only one stop or direction is provided in a later update.
IOS widget payloads decode background gradients and chart options (baseline, height, neo characters) from shared storage; CloudKit-driven payload merges accept newer widget revisions when sync metadata is stale.
Bundled and app CLI default output stays quiet: stderr hints for empty --command, deferred --image import, App Group image fallback, and image copy diagnostics print only when --verbose is passed.
MacOS and iOS widgets: text fitting uses a lower minimum scale, height-aware scaling with multiline no-wrap, and line caps that cooperate with text full width for ANSI and plain multiline content.
Shortcuts widget tap action kind is a fixed picker across Update and Show intents; chart and image updates reject conflicting payloads with clearer behavior; default CLI output stays quieter with optional –verbose diagnostics for image and command edge cases.
MacOS and iOS widgets honor chart height and baseline, preserve partial background gradients, improve waveform y-axis labeling, tighten text fitting for multiline ANSI, and fix full-width layouts for images and gradient progress bars.
FIXED
Fall back to embedded base64 image data when App Group image copies fail, so –image updates can still succeed in restricted environments.
Reject invalid chart height values and enforce that chart height can only be set when chart content is present, with clear validation errors.
Fill missing background gradient stop colors from –bg (or theme defaults) so one-sided gradient updates do not collapse to solid backgrounds.
MacOS and iOS widgets lay out gradient progress and fill-mode images across the full widget without leaving empty chart space above images; sparkline bar charts honor the payload chart baseline.
Waveform charts honor optional chart baseline (chartBase) when normalizing bar heights on macOS and iOS widget extensions.
Widget and CLI validation for chart height, base64 image fallback when App Group file copies fail, waveform scaling with chartBase, and several gradient or fill layout edge cases on macOS and iOS extensions.
1.1.5
NEW
Add –base N and –base-zero so chart scaling can start from a fixed baseline instead of the series minimum.
Add neo chart mode: a full-height cascading character-rain chart style for numeric series values.
Add –neo-characters (katakana|ascii|binary) to control the character set used by neo charts.
IMPROVED
Show mirrored y-axis labels for waveform charts so symmetric top/bottom halves read consistently with –label-y.
Support chart baseline values in AppleScript and Shortcuts chart updates for parity with CLI behavior.
Wire neo chart and –neo-characters through URL automation, AppleScript, and Shortcuts (macOS + iOS).
1.1.4
CHANGED
Menu bar extra icon asset switched to MenuBarAppIconVector.pdf (Contents.json updated).
The iOS app help screen notes that you can assign a widget tap action via Shortcuts, the URL scheme, or the TerminalWidget CLI on Mac.
CloudKit pulls coalesce behind a single in-flight guard, a lightweight throttle for routine callers, forced pulls for startup, pushes, explicit URL sync requests, plus one queued follow-up when callers stack during an active fetch.
FIXED
Tapping an iOS widget when no tap action is configured no longer wipes widget content because the tap URL always uses the non-mutating scheme host instead of falling through to update parsing.
Medium and large iOS text widgets with an icon keep the icon and text grouped and centered together instead of pinning the icon on the left while only the text centers.
1.1.3
CHANGED
Keep --background COLOR as the widget background color option while treating bare --background as background update mode.
Update the TerminalWidget app icon artwork used by the macOS, iOS, and watchOS app targets.
Refreshed the terminalwidget3 app icon asset.
Bundled/hosted CLI: default zebra opacity documentation and parsing match 0.24; clearer stdin behavior when combining tables with implicit piped text and explicit –text.
NEW
Improved dropdown menu on macOS and app screen on iOS
Add bare --background and --background-mode CLI options for prompt hooks that update widgets without launching TerminalWidget or opening the refresh URL.
Optional notify-on-change on widget payloads (synced); local Notification Center alerts when display content changes after CLI, URL, Shortcuts, AppleScript, or CloudKit pull on macOS and iOS.
CLI and standalone CLI package: –notify, –no-notify, and –notify-once after widget updates when content changed.
AppleScript and Shortcuts (macOS and mobile): persistent notify, notify-once, and sdef parameters for render widget and convenience commands.
Widgets can store a tap/click action per target and route configured taps through Terminal Widget while preserving the existing update/open behavior when no action is set.
MacOS widget actions can open URLs, run Shortcuts, launch apps by bundle identifier, or run shell commands through Terminal Widget.
IOS widget actions can open URLs and run Shortcuts; synced macOS-only app and shell actions fall back to the normal widget open/update behavior instead of no-op taps.
CLI and standalone CLI package: –action-kind, –action-value, –tap-action, –tap-action-value, and –clear-action configure or remove persisted widget actions.
AppleScript and Shortcuts on macOS and iOS can configure or clear widget actions through the same update pipeline.
Adds a rangebar chart format for macOS and iOS widgets, drawing each data item as a contiguous low-high bar from values like “1-3,2-3,1-4”.
CLI, URL automation, AppleScript, and Shortcuts can create rangebar charts and preserve range data in widget payloads.
Optional glass-style bar and heatmap fills for supported chart types (sparkline, waveform, matrix, rangebar, delta), exposed via –chart-bar-style, URL chartBarStyle, AppleScript, Shortcuts, and the AppleScript dictionary on macOS and iOS.
Separate colors for main widget text vs chart/progress captions and timestamps (–text-color, –caption-color, matching URL keys and automation).
Optional last-update time shown below captions when timestamp is enabled, driven by a stored update time on each successful widget apply.
IMPROVED
Rangebar charts expand to fill available vertical space on medium and large widgets while still supporting captions, annotation, icons, and Y-axis labels.
The documentation site can show a docked table of contents on long pages, including the CLI page.
URL and CLI alpha now also scales opacity for text and caption colors when those colors are set.
Chart glass fills use a stronger vertical gradient and outer rim so glass reads clearly versus solid fills on small widgets.
Glass bars add an inset inner stroke (translucent white toward top-leading, soft dark toward bottom-trailing) a few points inside the pill for a reflective glazed edge like glossy UI references.
Default table zebra striping is lighter (CLI and widgets default to 0.24 unless –zebra-opacity overrides).
Vertical gradient progress moves the “[n%]” caption below the bar when the bar is too narrow so it does not wrap one character per line.
Sync-debug-app.sh caps pluginkit, mdfind, and lsregister work during –deep-refresh so stale LaunchServices cleanup cannot hang indefinitely.
IOS widget payload model carries tableGridMode, tableLayout, and tableZebraOpacity like the desktop payload.
Menu bar extra icon uses the vector MenuBarAppIcon asset at a slightly larger template frame.
FIXED
Cold TerminalWidget launches from the CLI now use open -g so updates do not steal focus from Terminal or hide visor-style terminals.
Terminal-widget and non-app CLI no longer crash with –notify (UserNotifications when running inside a .app bundle; AppleScript display notification fallback when main bundle is not available).
Bar glass style is preserved when follow-up URLs update the chart but omit chartBarStyle, so configured glass no longer briefly appears then reverts to solid.
Range bar glass mode draws with Canvas plus the same liquid-glass helper as the waveform chart so WidgetKit snapshots show gradients and bezel instead of flattening layered SwiftUI fills to a flat color.
Range bar (and other charts combined with title text) no longer take the text-only layout branch, so range bars and glass styling render under the headline like on macOS.
ANSI-colored text in widgets no longer has the widget tint forced over escape-sequence colors, and reset segments use the normal text color again.
ANSI background colors (SGR 40-47 / 100-107) render reliably on iOS widgets by compositing segments with SwiftUI backgrounds where AttributedString background colors are ignored.
1.1.2
NEW
Improved dropdown menu on macOS and app screen on iOS
1.1.1
FIXED
Allow --text - with no piped input to clear widget text instead of failing with a stdin error.
1.0.0
CHANGED
Replace the repo-root terminal-widget bash/Python script with a small launcher that runs the embedded app binary, a local SwiftPM build, or respects TERMINAL_WIDGET_CLI.
Sparkline rendering and icon/sparkline layout are more consistent in desktop widgets.
Sparkline visuals no longer draw the rounded background or outline, showing bars only.
Removed the bottom-right widget target indicator from the widget UI.
Removed experimental polling options after unreliable update behavior in real use.
CLI status output is now quiet by default and only prints detailed update/debug information when --verbose is set.
Updated macOS and iOS widget rendering to support full-width image mode while keeping default image fit behavior when the flag is omitted.
Changed image fill semantics from –full-width to –padding fill for clearer, mode-based image layout control.
Updated macOS and iOS widget rendering to use the new image fill mode flag while preserving default fit behavior when fill is not enabled.
CLI validation now enforces chart context for –caption so the flag is only used with –sparkline or –matrix.
Expanded chart format parsing to accept waveform/wave while preserving existing sparkline, graph, and matrix aliases.
Split smooth and sine behavior so smooth keeps curve smoothing while sine uses half-sine interpolation between points.
Removed in-app privileged install buttons and moved system-path install flow to Terminal-driven sudo execution.
Matrix progress now uses a 9-column layout for more consistent completion behavior.
Refine matrix/dots progress and chart layout alignment so captions and grids render more consistently across widget families.
Progress updates now preserve gradient settings in payload and URL updates, with defaults that fall back to foreground color when explicit gradient colors are omitted.
Added --grid modes (none, row/horizontal, column/vertical, both, zebra, zebra-row, zebra-column) and made header separators always render under header rows.
Gradient progress bars now always render with rounded corners in both macOS and mobile widget extensions.
Updated CLI usage and validation so filter and table formatting options are explicitly documented and normalized.
Full-width text rendering now adapts alignment per payload content on both macOS and iOS widgets while preserving centered layout for regular text.
AppleScript automation commands now use parser-safe render ... verbs (render widget, render text, render chart, render progress, render image, render table) so scripts compile reliably.
AppleScript render image convenience command now supports full width and padding options for layout control parity with broader widget updates.
AppleScript render progress convenience command now accepts foreground and background color parameters for colorized progress updates.
Shortcuts convenience actions for text, progress, image, and table now expose padding, full width, and fullsize controls in the action UI.
Automation text updates now expand GitHub-style :emoji: shortcodes (for example :rocket:) consistently outside the standalone CLI path.
CLI execution now routes through the main TerminalWidget app binary, including updated launcher path guidance for /Applications and /Applications installs.
CLI text, icon, and table content now support GitHub-style 📝 shortcodes such as 🚀 and 👍.
Refresh macOS, menu bar, and iOS app icon assets.
NEW
Ship a Swift terminal-widget Mach-O binary built via SwiftPM and embedded in the app bundle so users do not need Python or other scripting runtimes for the helper.
Widget progress bar (0-100) and min-max bar sparkline from payload; CLI –progress and –sparkline/–spark (comma or space separated values, up to 128 points).
–image now accepts remote http(s) URLs in addition to local file paths so API-generated images can be displayed directly.
Added –padding N and –fullsize flags to control widget content inset, including edge-to-edge image layouts.
Added –font “FONT NAME” to set widget text to an installed system font for a target.
Added –mode as an alias for –theme so dark/light/system overrides can be set with either flag.
Added –padding N and –fullsize controls for per-widget content inset, including edge-to-edge image layouts.
–image accepts remote http(s) URLs as well as local file paths for API-generated images.
Added –foreground/–fg and –background/–bg with support for RRGGBB, #RRGGBB, rgb(…), and rgba(…) color formats.
Added –alpha to override foreground/background transparency per update.
Added –font “FONT NAME” support for text rendering with installed system fonts.
Added –poll MINUTES to refresh a target automatically while the app is running, with support for command or image poll sources.
Added polling stop controls via –poll 0/false/off and –clear for per-target disable.
Added –clear to reset widget content and styling fields for a target in one command.
Added a matrix heatmap chart mode that can render numeric series in the widget alongside existing icon and image layouts.
Added iPhone and iPad app/widget support with shared target-based widget updates.
Added mobile App Intent configuration so iOS/iPadOS widgets can pick and render synced targets.
Added –full-width for –image to fill widget width and crop vertically like Photos-style widgets.
Added –caption mode for sparkline and matrix updates to show a centered [min/max] label below the chart.
Added waveform chart support for serial numeric data with centered mirrored bars and interpolation between values for a denser visual style.
Added chart formats for area, lollipop, strip/dot, radial, delta, threshold, smooth, sine, and peak to visualize serial numeric data in multiple styles.
Added a Run in Terminal action next to Copy sudo command to open Terminal and prefill the install command automatically.
Added –progress-format bar|matrix so progress can render as a 10x4 matrix with fractional lower-row opacity and foreground color styling.
Added a centered [NN%] caption for matrix progress when –caption is used.
Added a watchOS companion app and watch complication so you can browse targets and push quick text updates from Apple Watch.
–caption now works with standard progress bars and shows a right-aligned [NN%] label inline with the bar.
Add –font-size and full-width text scaling for text-only and text+icon layouts when using –padding fill/–full-width, while keeping –image fill behavior unchanged.
Add dots as a supported –progress-format across CLI, macOS widgets, and iOS widgets.
Add watch complication target selection backed by CloudKit target discovery, with target-aware payload rendering in inline/circular/rectangular families.
Added a stack progress format that renders 10 full-width horizontal bars and fills bottom-up using 10 opacity levels per bar.
Added gradient progress modes: gradient (alias), gradient-horizontal, and gradient-vertical for macOS and iOS widgets.
Added –gradient-from, –gradient-to, and –gradient-width so gradient colors and bar thickness can be controlled from the CLI.
Added --table support for CSV, TSV, and JSON sources from files or stdin with automatic format detection.
Added a dedicated table renderer in macOS widgets with header support, status coloring, and content-measured column sizing.
Added GitHub emoji shortcode expansion for --icon, --text, and table cell values so shortcodes like :x: render as emoji.
Added built-in image filters for widgets (grayscale, sepia, negative, pixelate, blur) via --filter.
Added table layout and zebra tuning controls with --table-layout auto|equal and --zebra-opacity.
Added a “CLI docs” action to the menu bar app menu that opens https://terminalwidget.app/cli.
Added a matching “CLI docs” action to the setup/install window so help is available during onboarding.
Add iOS Shortcuts actions for updating widgets with text, charts, progress, images, and tables.
Add GitHub emoji shortcode expansion for automated text updates.
Add automation support for no-wrap text, ANSI rendering modes, stripping ANSI colors, and sparkline bar radius.
IMPROVED
Widget refresh behavior with a shorter timeline fallback, tighter staggered WidgetCenter retries, and applying custom-scheme URLs on the main thread immediately when already there.
Load payload from App Group JSON with an optional UserDefaults mirror and pick the newest revision; mirror defaults when reloading from disk from the host app.
Expose a stable App Group container path for the unsandboxed CLI so it writes the same JSON the app and widget read.
CLI output: manual test URL includes progress and sparkline when set; prints sparkline value count or cleared when –sparkline is used.
CLI and widget payload rules for icon-only vs text, progress, sparkline, and image updates (omit flags to clear bars and sparkline where documented).
Widget refresh behavior is more reliable with real timeline timestamps and automatic compaction of oversized instance registry data.
Custom font selection now resolves common family/display/PostScript names more reliably instead of silently falling back.
Fullsize image mode now reaches true edge-to-edge by disabling WidgetKit content margins and using low-radius corners for flush images.
Poll settings are persisted and restored per target while the app remains active, without requiring external services.
Appearance controls remain available and stable, including font and color customization support.
Added --matrix support in the CLI so matrix values can be sent directly to the widget payload.
Added stdin dash-input support for --text, --sparkline, and --matrix, plus piped-stdin fallback to text when no explicit stdin flag is used.
Expanded iCloud payload sync between macOS and iOS with source-device tracking, pull/push diagnostics, and retry queue behavior.
Kept –full-width as a compatibility alias so existing scripts continue to work while migrating to –padding fill.
Fill mode is now orientation-aware: portrait images fill width and crop height, while landscape and panorama images fill height and crop width.
Chart captions are now rendered consistently on both macOS and iOS widgets with compact numeric formatting for integer and decimal series.
Chart payload parsing and rendering now stay in sync across macOS and iOS targets, including caption behavior for all chart modes.
Icon-only widgets now scale symbols to fill available vertical space inside the current padding on macOS and iOS.
Added –annotate labels for sparkline, graph, and waveform chart formats.
IOS widget updates now refresh more reliably after payload writes and preserve current rendering state.
Matrix progress now scales to fill available widget space so squares grow in wider widget layouts.
Improve watch cloud diagnostics with clearer iCloud/capability error messages and add an in-app watch payload preview section.
Dots progress now keeps previously filled dots in place between updates so increasing progress adds dots and decreasing progress removes dots without reshuffling.
IOS widget timeline loading now prefers newer cloud payload revisions and persists refreshed payload data for more reliable cross-device updates.
Gradient progress now supports caption overlays with automatic contrast-aware text color for better readability.
Added iOS URL sync support for base64 tablePayload updates, including clamping and table/chart mode coordination.
Updated icon rendering on macOS and iOS to gracefully handle both SF Symbols and literal emoji text.
Gradient progress now places its midpoint at 20% of the remaining range from the progress start, making the active color more readable.
Filter chaining now works in order with repeated --filter flags and comma-separated lists like --filter "sepia:20,blur:10".
Multiline widget text now automatically left-aligns when lines start with spaces or tabs, so ASCII art and preformatted terminal output keep their intended shape instead of being centered.
AppleScript image path handling now normalizes alias-style and URL-style inputs and uses a copy fallback path so valid images render consistently in widgets.
Shortcuts action discovery is more reliable by using a non-empty app display name and refreshing app shortcut parameters on app launch.
CLI payload writes now prefer the real App Group container when available, improving update reliability from the app-bundled executable.
Bring AppleScript, Shortcuts, and CLI update options closer to parity across text, chart, progress, image, and table widgets.
Render ANSI foreground/background color sequences in widget text while allowing callers to force ANSI on, off, or stripped.
Improve sparkline widgets with configurable bar corner radius.
Declare the macOS app’s App Store category as Productivity.
FIXED
Stop the desktop widget from updating tens of seconds or minutes after the menu bar already showed new text by posting a Darwin notification after payload writes and reloading timelines from the widget extension process (avoids WidgetKit throttling WidgetCenter reloads from the LSUIElement host).
Handle terminalwidget:///update?sync=1 by reloading from disk so URL-based refresh does not merge stale in-memory state over fresh CLI writes.
Prevent a crash when the “Set up terminal-widget” / Install CLI tool window opens by disabling NSHostingView-driven window min/max sync, using a fixed content width, and setting explicit window content size limits so AppKit’s constraint update cycle no longer throws during display.
Install to system PATH from the app now triggers the admin password dialog instead of failing immediately with a permissions error.
Widget instances keep stable target names instead of drifting into high widget numbers, so –target updates the expected widget again.
Renaming a widget target now updates the stock demo command text to the new –target value.
Widgets recover cleanly after payload files are deleted by recreating missing payload JSON and avoiding stale mirrored fallback content.
Progress-only widgets are vertically centered instead of sticking to the top.
Text-only and text-plus-progress layouts now remain vertically centered consistently with other widget content combinations.
Running terminal-widget now fully replaces widget content with only the flags provided, so stale images/icons no longer persist when omitted.
Text-only, progress-only, and mixed text/progress layouts are consistently vertically centered.
Fullsize image rendering now reaches widget edges by disabling WidgetKit content margins, while preserving low-radius corners for flush images.
CLI updates now replace prior content state, clearing stale fields such as image/icon/padding/font when omitted from a command.
Custom fonts now resolve more reliably from common installed font names (family/display/PostScript matches) instead of silently falling back.
Text-only, progress-only, and mixed text/progress combinations stay vertically centered.
CLI updates now fully replace prior widget content, clearing stale image/icon/padding/font/color state when those flags are omitted.
CLI now validates poll usage so –poll requires either –command or –image as the refresh source.
Widget update flow remains immediate and reliable without background polling side effects.
Added argument validation errors for conflicting chart modes and conflicting stdin dash usage to prevent ambiguous command behavior.
Local –image updates now sync across devices by embedding a scaled image payload that each device decodes into local widget image storage.
Restored reliable Xcode scheme behavior by adding shared schemes so the app and widget extension can be rebuilt and run consistently.
Updated CLI install AppleScript success handling to avoid false warning behavior with newer NSAppleScript APIs.
Commands now write a fresh payload each time so unspecified fields are cleared and old chart/text/image content never leaks into later updates.
Improved Terminal launch reliability by explicitly opening/activating Terminal and retrying command injection during startup.
–full-width now implies zero padding so image fill mode behaves as edge-to-edge by default.
Explicit widget target names are now preserved more reliably instead of being remapped to stale widgetN slots.
Matrix progress now fills the active 10s column correctly for 1-9 remainder values instead of spilling into the next column.
Matrix progress now pre-fills prior lower-row columns consistently so values like 57% render with the expected solid and partial blocks.
Matrix progress now renders 100% as fully completed, with lower rows darkening to match the top-row fill color.
Watch app and complication bundle IDs now align with the iOS companion app prefix requirements so watch simulator installs succeed.
Progress format parsing and payload handling now accept stack consistently across CLI and URL-driven updates on macOS and iOS.
Full-width text scaling now keeps a built-in 10pt inset so text does not render edge-to-edge when using padding fill mode.
Gradient bars now render with a 6px corner radius when constrained by –gradient-width, while full-bleed gradients stay square.
Prevented filtered images from going blank by hardening widget-side Core Image rendering for large inputs.
AppleScript scripting metadata now registers correctly so TerminalWidget appears as a usable dictionary in Script Editor instead of reporting a corrupted dictionary.
AppleScript render image now accepts direct file arguments (including POSIX file) and named image/path values more reliably instead of failing or silently dropping the image update.
Shortcuts Update TerminalWidget now accepts icon-only updates instead of requiring text, chart, progress, image, or table content.
Embedded CLI signing now uses the app’s code-sign identity with hardened runtime so notarization checks pass for nested binaries.
Running terminal-widget with no flags now exits with clear guidance instead of unintentionally launching duplicate app instances when TerminalWidget is already running.
Fix iOS widget updates so the app and widget extension apply fresh CloudKit payloads instead of letting stale local files block newer remote content.
Fix iOS CloudKit push handling so sync can run before SwiftUI views appear.
Fix macOS CLI update handoff so command-line writes notify the app through SIGUSR1 and the URL scheme, with permission warnings suppressed.
Allow --text - to accept empty or whitespace-only piped input so the widget text can be cleared while preserving specified options such as background color.
TerminalWidget
1.0
CHANGED
Replace the repo-root terminal-widget bash/Python script with a small launcher that runs the embedded app binary, a local SwiftPM build, or respects TERMINAL_WIDGET_CLI.
Sparkline rendering and icon/sparkline layout are more consistent in desktop widgets.
Sparkline visuals no longer draw the rounded background or outline, showing bars only.
Removed the bottom-right widget target indicator from the widget UI.
Removed experimental polling options after unreliable update behavior in real use.
CLI status output is now quiet by default and only prints detailed update/debug information when --verbose is set.
Updated macOS and iOS widget rendering to support full-width image mode while keeping default image fit behavior when the flag is omitted.
Changed image fill semantics from –full-width to –padding fill for clearer, mode-based image layout control.
Updated macOS and iOS widget rendering to use the new image fill mode flag while preserving default fit behavior when fill is not enabled.
CLI validation now enforces chart context for –caption so the flag is only used with –sparkline or –matrix.
Expanded chart format parsing to accept waveform/wave while preserving existing sparkline, graph, and matrix aliases.
Split smooth and sine behavior so smooth keeps curve smoothing while sine uses half-sine interpolation between points.
Removed in-app privileged install buttons and moved system-path install flow to Terminal-driven sudo execution.
NEW
Ship a Swift terminal-widget Mach-O binary built via SwiftPM and embedded in the app bundle so users do not need Python or other scripting runtimes for the helper.
Added first-party AppleScript automation (render widget and convenience render ... commands) with full update-parameter coverage and annotation true support parity with CLI behavior.
Added Shortcuts App Intent automation actions (Update TerminalWidget plus convenience actions) with parity mapping for annotation/caption/label toggles.
Widget progress bar (0-100) and min-max bar sparkline from payload; CLI –progress and –sparkline/–spark (comma or space separated values, up to 128 points).
–image now accepts remote http(s) URLs in addition to local file paths so API-generated images can be displayed directly.
Added –padding N and –fullsize flags to control widget content inset, including edge-to-edge image layouts.
Added –font “FONT NAME” to set widget text to an installed system font for a target.
Added –mode as an alias for –theme so dark/light/system overrides can be set with either flag.
Added –padding N and –fullsize controls for per-widget content inset, including edge-to-edge image layouts.
–image accepts remote http(s) URLs as well as local file paths for API-generated images.
Added –foreground/–fg and –background/–bg with support for RRGGBB, #RRGGBB, rgb(…), and rgba(…) color formats.
Added –alpha to override foreground/background transparency per update.
Added –font “FONT NAME” support for text rendering with installed system fonts.
Added –poll MINUTES to refresh a target automatically while the app is running, with support for command or image poll sources.
Added polling stop controls via –poll 0/false/off and –clear for per-target disable.
Added –clear to reset widget content and styling fields for a target in one command.
Added a matrix heatmap chart mode that can render numeric series in the widget alongside existing icon and image layouts.
Added iPhone and iPad app/widget support with shared target-based widget updates.
Added mobile App Intent configuration so iOS/iPadOS widgets can pick and render synced targets.
Added –full-width for –image to fill widget width and crop vertically like Photos-style widgets.
Added –caption mode for sparkline and matrix updates to show a centered [min/max] label below the chart.
Added waveform chart support for serial numeric data with centered mirrored bars and interpolation between values for a denser visual style.
Added chart formats for area, lollipop, strip/dot, radial, delta, threshold, smooth, sine, and peak to visualize serial numeric data in multiple styles.
Added a Run in Terminal action next to Copy sudo command to open Terminal and prefill the install command automatically.
IMPROVED
Updated README automation docs with AppleScript and Shortcuts examples, including annotation true usage and parity guidance between automation and CLI surfaces.
Widget refresh behavior with a shorter timeline fallback, tighter staggered WidgetCenter retries, and applying custom-scheme URLs on the main thread immediately when already there.
Load payload from App Group JSON with an optional UserDefaults mirror and pick the newest revision; mirror defaults when reloading from disk from the host app.
Expose a stable App Group container path for the unsandboxed CLI so it writes the same JSON the app and widget read.
CLI output: manual test URL includes progress and sparkline when set; prints sparkline value count or cleared when –sparkline is used.
CLI and widget payload rules for icon-only vs text, progress, sparkline, and image updates (omit flags to clear bars and sparkline where documented).
Widget refresh behavior is more reliable with real timeline timestamps and automatic compaction of oversized instance registry data.
Custom font selection now resolves common family/display/PostScript names more reliably instead of silently falling back.
Fullsize image mode now reaches true edge-to-edge by disabling WidgetKit content margins and using low-radius corners for flush images.
Poll settings are persisted and restored per target while the app remains active, without requiring external services.
Appearance controls remain available and stable, including font and color customization support.
Added --matrix support in the CLI so matrix values can be sent directly to the widget payload.
Added stdin dash-input support for --text, --sparkline, and --matrix, plus piped-stdin fallback to text when no explicit stdin flag is used.
Expanded iCloud payload sync between macOS and iOS with source-device tracking, pull/push diagnostics, and retry queue behavior.
Kept –full-width as a compatibility alias so existing scripts continue to work while migrating to –padding fill.
Fill mode is now orientation-aware: portrait images fill width and crop height, while landscape and panorama images fill height and crop width.
Chart captions are now rendered consistently on both macOS and iOS widgets with compact numeric formatting for integer and decimal series.
Chart payload parsing and rendering now stay in sync across macOS and iOS targets, including caption behavior for all chart modes.
Icon-only widgets now scale symbols to fill available vertical space inside the current padding on macOS and iOS.
FIXED
Stop the desktop widget from updating tens of seconds or minutes after the menu bar already showed new text by posting a Darwin notification after payload writes and reloading timelines from the widget extension process (avoids WidgetKit throttling WidgetCenter reloads from the LSUIElement host).
Handle terminalwidget:///update?sync=1 by reloading from disk so URL-based refresh does not merge stale in-memory state over fresh CLI writes.
Prevent a crash when the “Set up terminal-widget” / Install CLI tool window opens by disabling NSHostingView-driven window min/max sync, using a fixed content width, and setting explicit window content size limits so AppKit’s constraint update cycle no longer throws during display.
Install to system PATH from the app now triggers the admin password dialog instead of failing immediately with a permissions error.
Widget instances keep stable target names instead of drifting into high widget numbers, so –target updates the expected widget again.
Renaming a widget target now updates the stock demo command text to the new –target value.
Widgets recover cleanly after payload files are deleted by recreating missing payload JSON and avoiding stale mirrored fallback content.
Progress-only widgets are vertically centered instead of sticking to the top.
Text-only and text-plus-progress layouts now remain vertically centered consistently with other widget content combinations.
Running terminal-widget now fully replaces widget content with only the flags provided, so stale images/icons no longer persist when omitted.
Text-only, progress-only, and mixed text/progress layouts are consistently vertically centered.
Fullsize image rendering now reaches widget edges by disabling WidgetKit content margins, while preserving low-radius corners for flush images.
CLI updates now replace prior content state, clearing stale fields such as image/icon/padding/font when omitted from a command.
Custom fonts now resolve more reliably from common installed font names (family/display/PostScript matches) instead of silently falling back.
Text-only, progress-only, and mixed text/progress combinations stay vertically centered.
CLI updates now fully replace prior widget content, clearing stale image/icon/padding/font/color state when those flags are omitted.
CLI now validates poll usage so –poll requires either –command or –image as the refresh source.
Widget update flow remains immediate and reliable without background polling side effects.
Added argument validation errors for conflicting chart modes and conflicting stdin dash usage to prevent ambiguous command behavior.
Local –image updates now sync across devices by embedding a scaled image payload that each device decodes into local widget image storage.
Restored reliable Xcode scheme behavior by adding shared schemes so the app and widget extension can be rebuilt and run consistently.
Updated CLI install AppleScript success handling to avoid false warning behavior with newer NSAppleScript APIs.
Commands now write a fresh payload each time so unspecified fields are cleared and old chart/text/image content never leaks into later updates.
Improved Terminal launch reliability by explicitly opening/activating Terminal and retrying command injection during startup.
–full-width now implies zero padding so image fill mode behaves as edge-to-edge by default.
TerminalWidget is in development and will be available soon. In the meantime, you can sign up for updates
to be notified when it's ready!
