Notifications

Dux Shell

Notifications

The dms notify command sends a desktop notification over the standard org.freedesktop.Notifications D-Bus interface. Its flags mirror notify-send, so existing scripts can swap the binary name and keep working, and it adds a --file shortcut for "a file arrived" style notifications.

Quick Start

# Summary and body
dms notify "Hello" "World"

# Critical, never expires
dms notify -u critical -t 0 "Disk almost full"

# App name, icon and category
dms notify -a "Backup" -i drive-harddisk --category transfer.complete "Backup finished"

# Buttons: prints the chosen name and exits
dms notify -A retry=Retry -A Dismiss "Build failed"

Arguments

Argument	Description
<summary>	Title line, required
[body]	Optional body text

Use -- before a summary that starts with a dash:

dms notify -- "-rf is dangerous"

Appearance

Flag	Short	Description
--app-name	-a	Application name (default DMS)
--icon	-i	Icon name or file path
--app-icon	-n	Application icon. When set, --icon is sent as the image-path hint instead
--urgency	-u	low, normal or critical
--category		Category string such as device.added or transfer.complete, comma separated
--transient	-e	Mark the notification transient so it is not kept in history
--expire-time	-t	Timeout in milliseconds. 0 never expires, -1 (default) uses the shell's own timeout settings

Urgency drives the shell's popup behavior: critical notifications bypass the normal queue limit and, when the Do Not Disturb exception is enabled, still show while Do Not Disturb is on.

note

-c is taken by the global --config flag, so --category has no short form here.

Identity

Flag	Short	Description
--print-id	-p	Print the notification id to stdout
--id-fd		Write the id to this file descriptor instead
--replace-id	-r	Replace an existing notification instead of creating a new one

Replacing keeps a single popup updated, which is what progress scripts want:

id=$(dms notify -p "Copying" "0%")
for pct in 25 50 75 100; do
  sleep 1
  dms notify -r "$id" "Copying" "$pct%"
done

Actions and Waiting

Flag	Short	Description
--action	-A	Add a button as [NAME=]Text. Repeatable. Implies --wait
--wait	-w	Block until the notification closes
--selected-action-fd		Also write the chosen action name to this file descriptor

When a button is clicked, its NAME is printed to stdout and the command exits. Without a NAME, the button's index (starting at 0) is used. If the notification closes without a click, nothing is printed. With a positive --expire-time, waiting also gives up after that many milliseconds and prints Wait timeout expired to stderr.

case "$(dms notify -A open=Open -A later=Later "Update available")" in
  open) dms update ;;
  later) ;;
esac

The action named default is what the shell fires when the notification body itself is clicked, matching the Desktop Notifications spec.

File Notifications

Flag	Description
--file	Path to a file. Adds Open and Open Folder buttons and uses the file as the image

dms notify "File received" "photo.jpg" --file ~/Downloads/photo.jpg

The buttons are handled for you: Open runs xdg-open on the file and Open Folder on its directory. When the shell is running, its daemon watches for the click. Otherwise a small background listener is spawned, so the command returns immediately either way. --file and --action cannot be combined.

Extra Hints

Flag	Short	Description
--hint	-h	Arbitrary hint as TYPE:NAME:VALUE. Repeatable

Supported types are boolean, int, double, string and byte. The variant type from notify-send is not supported.

# Progress value hint read by some notification servers
dms notify -h int:value:42 "Downloading"

# Show as coming from a desktop entry
dms notify -h string:desktop-entry:org.mozilla.firefox "Firefox"

Hints given with --hint override the ones set by other flags. -h is the hint flag like in notify-send, so use --help for help.

Scripting

Errors go to stderr with a non-zero exit code, and stdout only ever carries what you asked for (the id with --print-id, the action name with --action), so the command composes cleanly in shell scripts and plugin hooks.

# Notify when a long job finishes, critical on failure
make all; rc=$?
dms notify -u "$([ "$rc" -eq 0 ] && echo normal || echo critical)" "Build done" "exit $rc"

# Drop-in for notify-send
alias notify-send='dms notify'

All Options

Flag	Short	Description
--app-name	-a	Application name (default DMS)
--icon	-i	Icon name or path
--app-icon	-n	Application icon; turns --icon into the image
--urgency	-u	low, normal, critical
--category		Notification category
--transient	-e	Do not keep in history
--expire-time	-t	Timeout in ms (0 never, -1 shell default)
--hint	-h	Extra hint TYPE:NAME:VALUE
--print-id	-p	Print the notification id
--id-fd		Write the id to a file descriptor
--replace-id	-r	Replace an existing notification
--wait	-w	Wait until closed
--action	-A	Add a button [NAME=]Text, implies --wait
--selected-action-fd		Write the chosen action to a file descriptor
--file		File path with Open / Open Folder buttons
--help		Show help

--app and --timeout from older DMS versions still work as aliases of --app-name and --expire-time.