Node Notifier CLI

Common errors

• notify: command not found

  cause 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)

  cause 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)

  cause 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.

  cause 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.

Warnings

• breaking The 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.
• breaking The 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`.
• gotcha On 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.
• gotcha The `--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.
• 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.
• gotcha The `--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.

Install

• npm install node-notifier-cli npm
• yarn add node-notifier-cli yarn
• pnpm add node-notifier-cli pnpm

Imports

• notify
  wrong:

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

  correct:

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

  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
  wrong:

  npx notify -m 'Message'

  correct:

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

  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
  wrong:

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

  correct:

  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}`);
    }
  });

  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.

Quickstart

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"