swiftDialog 3.1.0 Release Notes

What’s New in swiftDialog 3.1.0

Workflow (Multi-Step Dialogs)

swiftDialog 3.1.0 introduces Workflow — a powerful new feature for building multi-step dialogs from a single JSON configuration.

Define an array of workflow pages using the workflow key in your JSON, each with its own title, message, icon, and input fields
Users can navigate forward and backward between cards, with input preserved across navigation
Accumulated input from all cards is returned as a single JSON output on completion
Global configuration properties (defined outside the cards array) act as defaults, overridable per card
New --onadvance argument allows a shell script to run when the user advances between cards — the script receives the current card index, card ID, and user input via stdin as JSON, and can block advancement by exiting with a non-zero code
Required field validation is enforced per card before advancing
Button bar adapts automatically (Back / Next / Finish) based on card position

Workflow pages can also branch based on user input (dropdown selection or checkbox state) with no callback script required, and the Next/Previous button text is customisable via --nextbuttontext / --previousbuttontext.

See Workflow for full documentation.

Notifications

⚠️ Note: From macOS 26.4 onward, setting the Dialog.app bundle icon in order to set the notification icon may no operate as expected. Pseudo Notifications may help address this issue for certain notification types

Notifications are now delivered by dedicated helper apps (Dialog Alert.app and Dialog Banner.app) rather than Dialog.app itself.

Separate apps for Alert and Banner style notifications, ensuring the correct macOS notification presentation style
Helper apps are bundled inside Dialog.app/Contents/Helpers/ and are automatically invoked by the dialog CLI launcher when --style alert or --style banner is used alongside --notification
The “Approve Notifications” alert now persists until dismissed — it no longer auto-dismisses
New app icons for the notifier helper apps

Deprecation Notice: Sending notifications via Dialog.app directly (without --style alert or --style banner) is deprecated. A warning is now printed to stderr when this legacy usage is detected. This behaviour will be removed in a future release and notifications without a specified style will be delivered as banners by default using the Dialog Banner.app helper.

Pseudo Notifications

Pseudo notifications are custom notification-style windows rendered by swiftDialog itself, rather than macOS system notifications. They slide in from the right edge of the screen and mimic the appearance of native notifications with a translucent material background.

Pseudo notifications are not system notifications. They do not persist once dismissed and do not follow the standard rules for macOS system notifications.

More Info

Inspect Mode

A substantial update to inspect mode (which shipped in 3.0.x):

Compliance dashboards — plist-driven UI with a ComplianceAggregatorService, shared compliance-summary / findings-list content blocks, and auto-bound bento cells.
Gated cadence engine — messages advance only when a monitored attribute is satisfied, with optional IPC drive and per-entry timeouts (stepType: "cadence"); plus a carousel cadence (DEPNotify-style done/active/pending icon row).
managedpref attribute — cadence/gating can read /Library/Managed Preferences/<domain>.plist (device or user scope).
ManagedValueRef — per-tenant branding pulls brand colour/claims from different MDM payload domains.
Forced appearance — appearance config key forces the inspect window’s light/dark appearance regardless of OS setting (#669).
Preset 3 redesign (hero block, footer, slim brand progress line); persistent footer brand logo with dark-mode variant; per-item descriptions in Presets 1/2/3/5/6 (#663); unified brand-tinted info badge.
IPC / sessions — per-PID session discovery (--published-sessions-dir publishes <pid>.json); session JSON enriched with resultFile, readinessFile, eventFile paths.
Refinement pass (PR #684): single header spinner + static status dots for concurrent installs; full (uncropped) file-based hero images; crisp Preset 5 cross-fades; refined Preset 5 onboarding (emphasised prose, centred browser dropdowns); unified 12pt spacing grid across Presets 1–3 and the wallpaper picker; readiness signalling added to Presets 1/2/3; live interaction-log events for dropdown/radio/checkbox; Preset 4 report view via progressMode "report" and external progress via the progress: IPC command; unified config intake with strict schema validation (tolerant of quoted numbers/booleans from MDM tooling) with detailed JSON error reporting.

The --bannerimage argument now supports solid colour and gradient options in addition to image files.

Solid colour banner:

dialog --bannerimage "colour=accent"
dialog --bannerimage "colour=#0066CC"
dialog --bannerimage "colour=blue,nogradient"   # disable the default gradient overlay

A subtle gradient overlay is applied by default. Append ,nogradient to disable it.

Multi-colour gradient banner:

dialog --bannerimage "gradient=red,orange,yellow"
dialog --bannerimage "gradient=red,orange,yellow:angle=135"

Colours are comma-separated names or hex values. The optional :angle=<degrees> suffix sets the gradient direction (0 = bottom-to-top, 90 = left-to-right, 180 = top-to-bottom; default is 90).

The same colour= and gradient= keywords also work for --background (watermark) images.

Title Enhancements

Subtitle Argument (for use with --title and --bannertitle)

--subtitle allows you to add a subtitle below the main title. This is useful for providing additional context or instructions to the user.

dialog --title "Main Title" --subtitle "This is a subtitle"

The subtitle text is styled with the same font properties as the title but at 75% opacity. When a banner image is used with --bannertext enable, the subtitle also adopts the banner text styling (white colour, shadow).

Title Font Offset

--titlefont now accepts an offset=<float> parameter to nudge the title text vertically within its container. Useful when using banner images with overlaid title text but can also be used in regular dialogs to fine-tune title positioning.

dialog --titlefont "size=36,offset=-10"

Builder / Construction Kit

Major improvements to --builder mode:

Export the current design to JSON and to a command line invocation.
Markdown sources — set the message / infobox from a .md file or URL; the builder loads the content for the live preview while exports reference the file/URL.
Screen background image option surfaced in the Window pane.
Drag-to-reorder for text fields, checkboxes and list items (now list-based with drag handles, matching the Images pane).
Structured button-symbol editor — SF Symbol name, position, rendering mode, size and colour/palette as individual controls, with a fixed live preview of button symbols.
Shared SF-Symbol icon picker across the icon, list and checkbox panes; banner-title now included in export; Dock icon shown while in builder mode.

Other new options

Screen background — display an image behind dialog windows via --screenbackground (#655).
Info box width — size the info-box text area independently of the icon (#665).
aria2 partial-file support — cacheExtensions is a configurable array marking items as “downloading” (defaults download, pkg, dmg; add aria2 for aria2) (#617).

Previously Undocumented Arguments

The following arguments existed in earlier releases but were not documented. Help text is now available via --help <argument> for each:

Argument	Description
`--helpalignment [left\|centre\|right]`	Sets the text alignment of the help sheet message
`--helpsheetbuttontext <text>`	Sets the dismiss button label on the help sheet (default: `OK`)
`--iconalttext <text>`	Accessibility label for the dialog icon
`--bannerheight <num>`	Sets the height of the banner image area in points
`--selectstyle [list\|radio\|searchable\|multiselect]`	Global display style for all select lists
`--progresstextalignment [left\|right]`	Horizontal alignment of progress bar text (default: centred)
`--verbose`	Enable verbose log output to stderr
`--eula`	Display message in EULA mode (monospaced, scrollable)
`--alwaysreturninput`	Return user input for all exit codes, not just exit code 0
`--hidetimer`	Hide the countdown indicator during image carousel autoplay transitions
`--listfonts`	Print all available font names to stdout

Bug Fixes

Fix #632 — Multiselect dropdown correctly renders selected tags in a scrollable flow layout
File/URL loading no longer errors on non-existent file paths (#654).
Mini view now renders structured text instead of inline text (#677); sizing adjusted for macOS 26 (Tahoe) and newer (#649).
Inspect Preset 2: auto-follows the active install (#565); honours custom status and progress text (#571); header subtitle sourced from message (#670).
Inspect: appearance: dark is now honoured when set in inspect-mode JSON.

Changes & Deprecations

Sending notifications via Dialog.app directly (no --style) is deprecated — use --style alert / --style banner; legacy usage warns on stderr.
Removed the stub --inspect-schema and --schema-validate commands.