swiftDialog 3.1.0 Release Notes

What’s New in swiftDialog 3.1.0

Cards Workflow (Multi-Step Dialogs)

swiftDialog 3.1.0 introduces Cards — a powerful new feature for building multi-step dialog workflows from a single JSON configuration.

Define an array of cards 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

See Cards 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

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"

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