Registry / communication / node-notifier-cli

node-notifier-cli

library2.0.0jsnpmunverified

node-notifier-cli is a command-line interface (CLI) package that provides a convenient way to send cross-platform desktop notifications. It acts as a wrapper around the `node-notifier` library, enabling users to trigger notifications directly from their terminal or shell scripts without writing JavaScript code. It supports various notification systems including macOS Notification Center (since 10.8), Windows Toast notifications, Growl, and `notify-send` for Linux. Version 2.0.0 is the current stable release, with its last major update occurring approximately five years ago. Its release cadence is closely tied to its underlying `node-notifier` library, which provides the core notification functionality. The package differentiates itself from programmatic notification libraries by offering a simple, unified command-line syntax for sending messages, titles, icons, and even opening URLs on click, focusing solely on CLI usability.

communication

npm install node-notifier-cli

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-NOTIFIER-CLI

node-notifier-cli

communicationjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

notify

✓ notify -t 'Task Complete' -m 'Your build finished successfully!'

✗ import { notify } from 'node-notifier-cli'

This package is a CLI tool; its primary 'symbol' is the `notify` command executed from the shell after global or local installation. It is not designed for direct programmatic import as an ES module or CommonJS module.

npx

✓ npx -p node-notifier-cli notify -t 'Reminder' -m 'Don\'t forget that meeting at 3 PM!' -s Glass

✗ npx notify -m 'Message'

Using `npx` is a common pattern to execute the `notify` command without a global installation. The `-p node-notifier-cli` flag ensures `npx` finds and uses the correct package.

spawn

✓ import { spawn } from 'child_process'; const title = 'System Alert'; const message = 'Disk space low! Cleanup recommended.'; const icon = 'https://raw.githubusercontent.com/mikaelbr/node-notifier/master/example/coulson.jpg'; const child = spawn('notify', ['-t', title, '-m', message, '--icon', icon, '-s', 'Basso']); child.on('error', (err) => { console.error('Failed to start notify process:', err.message); }); child.on('close', (code) => { if (code !== 0) { console.warn(`notify process exited with code ${code}`); } });

✗ spawn('node-notifier-cli', ['-t', 'Title', '-m', 'Message'])

For programmatic integration within Node.js applications, the `notify` command can be executed as a child process. The executable name is `notify`, not the package name. Ensure `node-notifier-cli` is globally installed or accessible in the system's PATH for `spawn('notify', ...)` to work directly, or provide the full path to the executable.

Demonstrates global installation and various ways to send desktop notifications, including titles, messages, sounds, custom icons, opening URLs, and piping input.

# Install globally (recommended for CLI usage) npm i -g node-notifier-cli # Basic notification notify -t 'Hello World' -m 'This is a test notification from the CLI.' # Notification with sound and opening a URL on click notify -t 'GitHub Update' -m 'New pull request on your repository!' -s Basso --open 'https://github.com/mikaelbr/node-notifier-cli' # Notification with a custom icon notify -t 'Agent Coulson' --icon 'https://raw.githubusercontent.com/mikaelbr/node-notifier/master/example/coulson.jpg' -m 'I know, right?' # Pipe content to message echo "This message comes from stdin!" | notify -t "Piped Message"

node-notifier --version

Debug

Known issues

breakingThe underlying `node-notifier` library, which `node-notifier-cli` depends on, had a Command Injection vulnerability (CVE-2020-28283) in versions less than 5.4.5, and specifically in the range `>=8.0.0 <8.0.2`, and `>=9.0.0 <9.0.1`. `node-notifier-cli@2.0.0` depends on `node-notifier@^8.0.1`, which is within the vulnerable range. This means `node-notifier-cli@2.0.0` is directly susceptible to arbitrary command execution on Linux systems if user-provided input (e.g., from `--title`, `--message`, `--icon`) is not properly sanitized before being passed to the CLI.

fix

Users of `node-notifier-cli@2.0.0` should either manually update their `node-notifier` dependency to a non-vulnerable version (e.g., `8.0.2` or later `8.x.x` if available) within their `node_modules` or ideally, avoid using user-controlled input in notification parameters until an official update to `node-notifier-cli` or a safer fork is available. Always validate and sanitize all inputs.

affects: 2.0.0

breakingThe CLI functionality was removed from the main `node-notifier` package starting with version `5.0.0` and moved into this separate `node-notifier-cli` package. Users updating `node-notifier` to `5.0.0` or higher would lose the `notify` command if they did not also install `node-notifier-cli`.

fix

To continue using the `notify` command from the terminal, install `node-notifier-cli` separately: `npm i -g node-notifier-cli`.

affects: >=5.0.0 of node-notifier

gotchaOn macOS, custom icons specified with the `--icon` option may not display as the primary notification icon. macOS notifications often display the icon of the parent application initiating the notification (which is `terminal-notifier` in this case). To use a truly custom icon, one generally needs to fork and recompile `terminal-notifier` with the desired icon embedded.

fix

Be aware of this platform limitation. For a more integrated custom icon, consider using a programmatic solution (like `node-notifier` directly within an Electron app) that allows bundling with custom executables, or adjust expectations for macOS CLI notifications.

affects: >=1.0.0

gotchaThe `--subtitle` option is explicitly noted as 'not available on Windows OS'. Attempting to use this option on Windows will have no effect. [cite: README]

fix

Avoid using the `--subtitle` option when targeting Windows environments. Structure your message to incorporate subtitle-like information within the main `--message` field.

affects: >=1.0.0

gotcha`node-notifier` (and by extension `node-notifier-cli`) relies on native OS tools for notifications. For Linux, `notify-osd` or `libnotify-bin` must be installed. For macOS, `terminal-notifier` is used (which is bundled). Without these, notifications may fail or fall back to less preferred methods (like Growl).

fix

Ensure the necessary native notification tools are installed on your Linux system (e.g., `sudo apt-get install libnotify-bin` on Ubuntu/Debian). On Windows, ensure Windows Notifications are enabled and not blocked by security policies.

affects: >=1.0.0

gotchaThe `--sound` option on macOS supports specific system sounds (e.g., `Basso`, `Bottle`, `Glass`). Using `true` as a value will default to 'Bottle'. Using an invalid sound name or `true` on platforms that don't support it (e.g., Windows Toasters or `notify-send`) might result in no sound or a default system sound, not an error.

fix

Consult the `node-notifier` documentation for a list of supported sound names on macOS. Test sound functionality on target platforms for consistent behavior. Use `--sound none` to explicitly disable sound.

affects: >=1.0.0

Errors

Common errors & fixes

notify: command not found

The `node-notifier-cli` package, and thus the `notify` executable, is not installed globally or is not in your system's PATH.

fix

Install the package globally: `npm i -g node-notifier-cli` or ensure that the local `node_modules/.bin` directory is in your PATH if installed locally.

Notifications not appearing on Linux (Ubuntu/Debian-like systems)

The required system utility, `notify-send` (provided by `libnotify-bin`), is not installed.

fix

Install `libnotify-bin`: `sudo apt-get install libnotify-bin`.

Notifications not appearing in Windows Subsystem for Linux (WSL2)

WSL2 environment may not have proper display server integration or permissions to forward notifications to the Windows host OS.

fix

Ensure your WSL2 setup is configured for GUI applications, potentially involving an X server, or modify Windows permissions for the `SnoreToast.exe` binary used by `node-notifier`. Refer to `node-notifier`'s documentation on 'Windows and WSL2' for detailed steps.

Notification timeout behavior is inconsistent on Windows, often disappearing quickly.

On Windows, the `wait` and `timeout` options for toast notifications can be inconsistent. The system often enforces a default display duration (e.g., 5 seconds) regardless of settings, and 'sticky' notifications are not universally supported.

fix

Be aware that custom `timeout` settings may not always be honored on Windows for transient toast notifications. For longer-lasting notifications, consider using the `actions` or `reply` options which inherently require a user interaction to dismiss, or explore platform-specific sticky notification solutions outside of this CLI.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

node-notifierrequiredThis package is a CLI wrapper around the `node-notifier` library, which provides the core cross-platform notification logic. It's a direct runtime dependency.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mikaelbr/node-notifier-cli ↗

packagehttps://www.npmjs.com/package/node-notifier-cli ↗