repository·master·Indexed 27 days ago
https://github.com/julienxx/terminal-notifierA command-line tool and Ruby gem for sending macOS User Notifications (macOS 10.10+). It allows developers to trigger system alerts, play sounds, open URLs, run shell commands, and manage notification groups via the terminal or Ruby API using methods like TerminalNotifier.notify, TerminalNotifier.remove, and TerminalNotifier.list.
You can install terminal-notifier using Homebrew or the RubyGems package manager.
Homebrew:
brew install terminal-notifierRubyGems:
[sudo] gem install terminal-notifierbrew install terminal-notifierTo use terminal-notifier, you must call the binary located inside the application bundle. If you installed the Ruby gem, you can use the terminal-notifier wrapper command directly.
Direct binary usage:
./terminal-notifier.app/Contents/MacOS/terminal-notifier -[message|group|list] [VALUE|ID|ID] [options]Ruby gem wrapper usage:
terminal-notifier -[message|group|list] [VALUE|ID|ID] [options]./terminal-notifier.app/Contents/MacOS/terminal-notifier -[message|group|list] [VALUE|ID|ID] [options]Install the Ruby wrapper using the standard gem command to enable macOS User Notifications from your Ruby applications.
$ gem install terminal-notifierUse -title, -subtitle, and -appIcon to customize the appearance of the notification.
terminal-notifier -title ProjectX -subtitle "new tag detected" -message "Finished" -appIcon http://vjeantet.fr/images/logo.pngYou can pipe data directly into terminal-notifier to use it as the message body. Use the -sound option to play a system sound (e.g., default).
echo 'Piped Message Data!' | terminal-notifier -sound defaultUse the -open option to specify a web URL, file URL, or custom URL scheme to be opened when the user clicks the notification.
terminal-notifier -title '💰' -message 'Check your Apple stock!' -open 'http://finance.yahoo.com/q?s=AAPL'Use the -activate option with a bundle identifier (e.g., com.apple.Safari) to launch or bring an application to the foreground when the notification is clicked.
terminal-notifier -group 'address-book-sync' -title 'Address Book Sync' -subtitle 'Finished' -message 'Imported 42 contacts.' -activate 'com.apple.AddressBook'You can manage active notifications using group identifiers (such as Process.pid):
TerminalNotifier.remove(group_id): Removes notifications belonging to the specified group.TerminalNotifier.list: Lists all active notifications.TerminalNotifier.list(group_id): Lists notifications belonging to a specific group.TerminalNotifier.remove(Process.pid)
TerminalNotifier.list(Process.pid)
TerminalNotifier.listUse TerminalNotifier.notify to send notifications to the macOS Notification Center (macOS 10.10+). You can pass a message string as the first argument, followed by an optional hash of configuration options.
Supported options include:
:title: The title of the notification.:subtitle: A subtitle for the notification.:activate: An application bundle ID to activate when the notification is clicked.:open: A URL or file path to open.:execute: A shell command to execute.:group: A group identifier (e.g., Process.pid) to group notifications.:sender: The bundle ID of the sender.:sound: The sound to play (e.g., 'default').TerminalNotifier.notify('Hello World')
TerminalNotifier.notify('Hello World', :title => 'Ruby', :subtitle => 'Programming Language')
TerminalNotifier.notify('Hello World', :activate => 'com.apple.Safari')
TerminalNotifier.notify('Hello World', :open => 'http://twitter.com/julienXX')
TerminalNotifier.notify('Hello World', :execute => 'say "OMG"')
TerminalNotifier.notify('Hello World', :group => Process.pid)
TerminalNotifier.notify('Hello World', :sender => 'com.apple.Safari')
TerminalNotifier.notify('Hello World', :sound => 'default')At a minimum, you must specify either the -message, -remove, or -list option.
Note on Sticky Notifications: To make notifications stay on screen until dismissed, change the style from Banners to Alerts in System Preferences -> Notifications -> terminal-notifier. This cannot be done per-notification.
Use TerminalNotifier.remove(group, verbose) to clear existing notifications.
Parameters:
group: The group ID of the notifications to remove. Use 'ALL' (default) to remove all notifications.verbose: (Optional) Boolean to print command output to STDOUT.Returns true if the command executed successfully.
Retrieve details about sent notifications using TerminalNotifier.list(group, verbose).
Parameters:
group: The group ID to query. Use 'ALL' (default) to list all notifications.verbose: (Optional) Boolean to print command output to STDOUT.Returns:
group is 'ALL': An Array of Hash objects containing notification details.group is provided: The Hash for the first matching notification, or nil if none found.Hash Keys:
:group:title:subtitle:message:delivered_at (parsed as a Time object)