Notifications from scripts

A script writing to a Terminalis terminal can request a desktop notification. Clicking the notification in the shipped macOS app returns to that terminal.

Use terminalis-notify #

The interactive Bash, Zsh, and Fish integrations provide a terminalis-notify shell function. At a Terminalis prompt, run:

terminalis-notify 'Demo check finished'

This sends a body-only notification whose title identifies the terminal and uses the macOS Pop sound. It works independently of managed-command completion alerts and may notify even while Terminalis is in front. Normal system notification settings still apply.

In 3.7.0, ordinary notifications are removed five seconds after delivery, including from Notification Center history. Choose a mode explicitly when needed:

terminalis-notify --persistent 'Review the deployment result'
terminalis-notify --transient 'Demo check finished'
terminalis-notify -- '-message beginning with a dash'

Persistent alerts have no application expiry timer and require enabled alerts with Persistent style in macOS Notifications settings. Use -- before a message beginning with a dash. The same flags work before a title and body.

The helper is a shell function, not a standalone executable. A child script should not assume it inherits the function; use the raw sequence below. Other shells can also print the raw sequence without needing the helper.

Custom titles #

Use the two-argument helper for a title and body:

terminalis-notify 'demo' 'API check finished'

For a standalone shell script, emit the OSC 777 notification sequence instead:

printf '\033]777;notify;%s;%s\007' 'demo' 'API check finished'

Legacy OSC 9 and OSC 777 notifications are transient. The title and message must be nonblank text. Keep semicolons out of the raw OSC 777 title because they delimit fields, and do not put terminal control characters in either value. Rapid notifications from the same terminal are rate-limited to roughly one every 1.5 seconds. Clicks focus the terminal; they cannot be configured to open an arbitrary URL.

Detect Terminalis #

Terminalis exports TERMINALIS_TERMINAL=1 to its shells and child processes. A POSIX shell script can use it before printing a notification:

if [ "${TERMINALIS_TERMINAL:-}" = "1" ]; then
  printf '\033]777;notify;%s;%s\007' 'demo' 'Worker check finished'
fi

This example works in Bash, Zsh, or a standalone sh script. For Fish, use if test "$TERMINALIS_TERMINAL" = 1, the same printf call, and end.

The escape must reach the terminal. If stdout is redirected to a file, write to /dev/tty when a controlling terminal exists. Avoid emitting it into machine-readable output or a log you intend to parse. For missing alerts, check permissions.