Notifications

Notifications

swiftDialog allows you to send notifications using the --notification argument. This indicates that swiftDialog should send a notification instead of showing a dialog window.

Notifications use the same --title, --message and --icon arguments to present text and media. Any other arguments not listed on this page are ignored.

There is an additional argument --subtitle which adds a subtitle to the notification.

Notification styles (v3.1+)

From v3.1, swiftDialog routes notifications through dedicated helper applications embedded inside Dialog.app. Use the --style argument to select the notification type:

--style value	Behaviour	Helper used
banner	System notification that appears briefly then dismisses automatically	Dialog Banner
alert	System notification that persists until the user dismisses it	Dialog Alert
pseudo	Pseudo notification banner (same as pseudo-banner)	Main app
pseudo-banner	Pseudo notification that auto-dismisses after a timeout	Main app
pseudo-alert	Pseudo notification that stays until user interaction	Main app

The default when --style is omitted depends on the system notification settings configured for the app.

Legacy path (deprecated in v3.1)

Calling --notification without --style still works for backwards compatibility but routes through the main Dialog.app bundle. This path is deprecated and will emit a warning to stderr: In a future release, sending a notification without --style will default to --style banner.

To ensure the style types are correctly set for system notifications, deploy a mobileconfig that pre-approves notifications for the relevant helper apps (au.csiro.dialog.banner and au.csiro.dialog.alert) with the desired notification style.

Use

Sending a basic banner notification:

dialog --notification --style banner --title "Test Notification" --message "A test notification message"

Sending a persistent alert notification:

dialog --notification --style alert --title "Test Notification" --message "A test notification message"

If the message is longer than what the notification can show, the message will be truncated and show elipses ... to indicate as such. There should also appear a chevron in the top right of the notification when the user hovers over the notification that lets the user expand the contents

Adding a subtitle:

dialog --notification --style banner --title "Test Notification" --message "A test notification message" --subtitle "Test Subtitle"

Including title and subtitle a notification can have up to 5 lines of text. A \n character within the message body will create a newline in the notification.

An image can be added with --icon and accepts all existing image formats and sources.

When displaying an image, the content of the notification can be expanded by the user

Note: You cannot replace the default icon that is displayed with the notification. Images added using --icon will appear within the notification

Setting an action

You can set an action to be performed when the user clicks on the notification. This can be a URL or a shell command.

NOTE: Notifications are user driven, and consequently the actions taken by the notification are in the user context.

The basic use for this feature is:

dialog --notification --style banner --title "<text>" --message "<text>" --button1action "open -a Safari.app"
dialog --notification --style banner --title "<text>" --message "<text>" --button1action "https://swiftdialog.app/"

You can specify an additional action and define the button labels:

dialog --notification --style banner --title "<text>" --message "<text>" \
    --button1text "Do Something" --button1action "/do/something" \
    --button2text "Do Something Else" --button2action "/do/something/else/"

--button1action is the default action when either the notification body or button1 is clicked. --button2action only triggers when button2 is clicked.

Notification identifiers and removal

You can assign a persistent identifier to a notification using --identifier. This allows you to remove a specific notification later:

# Send a notification with an identifier
dialog --notification --style banner --title "Update Available" --message "Version 2.0 is ready" --identifier "update-available"

# Remove it later
dialog --notification --style banner --remove --identifier "update-available"

Calling --remove without --identifier removes all pending notifications from that helper.

Identifiers also work with pseudo notifications (see below).

Enabling notification sounds

Use --enablenotificationsounds to play the default notification sound when the notification is delivered:

dialog --notification --style alert --title "Alert" --message "Action required" --enablenotificationsounds

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.

Why use pseudo notifications?

• Custom icon support — The icon displayed on the notification is fully customisable using --icon, including SF Symbols, URLs, file paths, and app bundles. Unlike system notifications, this does not require setting the Dialog.app bundle icon and restarting NotificationCenter.
• No MDM profile required — Pseudo notifications do not go through the macOS notification center, so no mobileconfig or notification permissions are needed.
• Inline images — Use --image to display an image within the notification body.
• Inline markdown — The --message content supports inline markdown formatting.

What pseudo notifications are not?

Pseudo notifications are not system notifications. They do not persist once dismissed and do not follow the standard rules for macOS system notifications. They also do not stack. Multiple pseudo notifications can be sent but they will appear on top of each other until they are dismissed. If this is important to you then use regular system notifications.

Pseudo notification styles

--style value	Behaviour
pseudo	Same as pseudo-banner
pseudo-banner	Auto-dismisses after 6 seconds (or the value of --timer)
pseudo-alert	Stays on screen until the user clicks or closes it

Basic usage

# Banner-style pseudo notification (auto-dismisses)
dialog --notification --style pseudo --title "Update Available" --message "Version 2.0 is ready to install"

# Alert-style pseudo notification (persistent)
dialog --notification --style pseudo-alert --title "Restart Required" --message "Please save your work and restart"

Custom icon and image

dialog --notification --style pseudo --title "Deployment" --message "Software install complete" \
    --icon /System/Applications/App\ Store.app  \
    --image "/Applications/Keynote.app"

Action buttons

When --button2text or --button2action is specified, an action bar appears at the bottom of the notification with two buttons:

dialog --notification --style pseudo-alert --title "Update Available" \
    --message "macOS 26.4 is ready to install" \
    --button1text "Later" \
    --button2text "Install Now" --button2action "open 'x-apple.systempreferences:com.apple.Software-Update-Settings.extension'"

• Clicking the notification body or Button 1 executes --button1action.
• Clicking Button 2 executes --button2action.
• If neither --button2text nor --button2action is specified, the action bar is hidden and clicking anywhere on the notification triggers --button1action.

Auto-dismiss timer

For pseudo-banner style, the notification auto-dismisses after 6 seconds by default. Use --timer to set a custom duration in seconds:

# Auto-dismiss after 15 seconds
dialog --notification --style pseudo-banner --title "Reminder" --message "Meeting in 5 minutes" --timer 15

Close button

When the user hovers over a pseudo notification, a close button (×) appears in the top-left corner. Clicking it dismisses the notification with the same behaviour as a timeout (slides out, exits with code 0, no button action executed).

Live timestamp

Pseudo notifications display a “now” timestamp next to the title. After 60 seconds this updates to “1m ago” and continues updating every 60 seconds for as long as the notification remains visible.

Identifiers and removal

Pseudo notifications support --identifier for targeted removal:

# Send a pseudo notification with an identifier
dialog --notification --style pseudo-alert --title "Updating" --message "Please wait..." --identifier "update-progress"

# Remove it when done
dialog --notification --style pseudo --remove --identifier "update-progress"

# Remove ALL visible pseudo notifications
dialog --notification --style pseudo --remove

When sending a new pseudo notification with the same identifier as an existing one, the old notification is automatically dismissed before the new one appears.

Notification sounds

Use --enablenotificationsounds to play the system alert sound when the pseudo notification appears:

dialog --notification --style pseudo --title "Alert" --message "Something happened" --enablenotificationsounds

Approving and Setting Notification type via MDM

When you first use notifications you may not receive any feedback or be prompted to allow notifications.

To manually allow notifications you will need to go to System Settings -> Notifications and enable notifications for the relevant application(s). You can also select between None, Banner or Alert style.

When deploying swiftDialog via MDM it is preferred to deploy a mobileconfig that will pre-approve notifications and set the notification type.

Bundle identifiers

Version	Bundle identifier	Notes
v2.2.1 and earlier	au.bartreardon.dialog	Legacy
v2.3 – v3.0	au.csiro.dialog	Main app bundle
v3.1+ (banner style)	au.csiro.dialog.banner	Dialog Banner helper
v3.1+ (alert style)	au.csiro.dialog.alert	Dialog Alert helper

To confirm the exact bundle identifiers on an installed build, run:

defaults read "/Library/Application Support/Dialog/Dialog.app/Contents/Helpers/Dialog Banner.app/Contents/Info.plist" CFBundleIdentifier
defaults read "/Library/Application Support/Dialog/Dialog.app/Contents/Helpers/Dialog Alert.app/Contents/Info.plist" CFBundleIdentifier

If you have a mixed installation you can include multiple bundle entries in the same profile. An example payload for banner style notifications might look like this:

<key>PayloadContent</key>
<array>
    <dict>
        <key>PayloadDisplayName</key>
        <string>Notifications Payload</string>
        <key>PayloadIdentifier</key>
        <string>449B1259-E631-4051-ADCE-9532B813ADDC</string>
        <key>PayloadOrganization</key>
        <string>Org Name</string>
        <key>PayloadType</key>
        <string>com.apple.notificationsettings</string>
        <key>PayloadUUID</key>
        <string>12EA8FDA-B204-4AD0-802C-C980615F0BA5</string>
        <key>PayloadVersion</key>
        <integer>1</integer>
        <key>NotificationSettings</key>
        <array>
            <dict>
                <key>AlertType</key>
                <integer>1</integer>
                <key>BadgesEnabled</key>
                <true/>
                <key>BundleIdentifier</key>
                <string>au.bartreardon.dialog</string>
                <key>CriticalAlertEnabled</key>
                <false/>
                <key>NotificationsEnabled</key>
                <true/>
                <key>ShowInLockScreen</key>
                <true/>
                <key>ShowInNotificationCenter</key>
                <true/>
                <key>SoundsEnabled</key>
                <true/>
            </dict>
            <dict>
                <key>AlertType</key>
                <integer>1</integer>
                <key>BadgesEnabled</key>
                <true/>
                <key>BundleIdentifier</key>
                <string>au.csiro.dialog</string>
                <key>CriticalAlertEnabled</key>
                <false/>
                <key>NotificationsEnabled</key>
                <true/>
                <key>ShowInLockScreen</key>
                <true/>
                <key>ShowInNotificationCenter</key>
                <true/>
                <key>SoundsEnabled</key>
                <true/>
            </dict>
            <dict>
                <key>AlertType</key>
                <integer>1</integer>
                <key>BadgesEnabled</key>
                <true/>
                <key>BundleIdentifier</key>
                <string>au.csiro.dialog.notifier.banner</string>
                <key>CriticalAlertEnabled</key>
                <false/>
                <key>NotificationsEnabled</key>
                <true/>
                <key>ShowInLockScreen</key>
                <true/>
                <key>ShowInNotificationCenter</key>
                <true/>
                <key>SoundsEnabled</key>
                <true/>
            </dict>
            <dict>
                <key>AlertType</key>
                <integer>2</integer>
                <key>BadgesEnabled</key>
                <true/>
                <key>BundleIdentifier</key>
                <string>au.csiro.dialog.notifier.alert</string>
                <key>CriticalAlertEnabled</key>
                <false/>
                <key>NotificationsEnabled</key>
                <true/>
                <key>ShowInLockScreen</key>
                <true/>
                <key>ShowInNotificationCenter</key>
                <true/>
                <key>SoundsEnabled</key>
                <true/>
            </dict>
        </array>
    </dict>
</array>

Note that the AlertType key controls the notification style independently of --style:

• 1 = Banner (dismisses automatically)
• 2 = Alert (persists until dismissed)

When deploying with --style alert, set AlertType to 2 in the au.csiro.dialog.alert entry, and vice versa for banners.

A note about notification Errors

If you receive the following:

Notifications are not available: Couldn't communicate with a helper application

verify that the relevant Dialog application has notifications enabled in System Settings, either by applying one of the above mobileconfig files via MDM or manually in System Settings.

Updating the default notification icon

Notifications will use the default swiftDialog icon. If you would like to re-brand to use a different icon, e.g. a corporate identity, then you can use the following steps to update the app bundle icon to something more appropriate for your use.

Support from macOS 26.4 onwards

In macOS 26.4 updating the app bundle icon and therefore the notification icon no longer works correctly. If branding is important then use the new pseudo notification feature, which presents a similar UI to system notifications but doesn’t use the macOS system notification system, therefore may not be appropriate to all situations.

Prerequisites

• Latest swiftDialog pkg
• An appropriate replacement image at least 512x512 (1024x1024 preferred)

• Generating an image

  You can generate an image from your MDM vendors self service application using the sips command. For example:

  Kandji

  sudo /bin/mkdir -p /Library/Application\ Support/Dialog
  sips -s format png /Applications/Kandji\ Self\ Service.app/Contents/Resources/AppIcon.icns --out /Library/Application\ Support/Dialog/Dialog.png

  Jamf

  temp_file=$(/usr/bin/mktemp)
  /usr/bin/xxd -p -s 260 "$(defaults read /Library/Preferences/com.jamfsoftware.jamf self_service_app_path)"/Icon$'\r'/..namedfork/rsrc | /usr/bin/xxd -r -p > "$temp_file"
  sudo /bin/mkdir -p /Library/Application\ Support/Dialog
  sudo /usr/bin/sips -s format png "$temp_file" --out /Library/Application\ Support/Dialog/Dialog.png

Steps

1. Copy your replacement icon image to /Library/Application Support/Dialog/Dialog.png (case sensitive)
2. Install swiftDialog from the .pkg installer.

With the replacement Dialog.png in place the installer will replace the built in icon with the specified image. Notifications will then use the custom image as the notification icon.