ntfy
Version 2.4.4
ntfy
ntfy brings notification to your shell. It can automatically provide
desktop notifications when long running commands finish or it can send
push notifications to your phone when a specific command finishes.
Confused? This video demonstrates some of this functionality:
$ sudo pip install ntfy
$ ntfy send test
# send a notification when the command `sleep 10` finishes
# this sends the message '"sleep 10" succeeded in 0:10 minutes'
$ ntfy done sleep 10
$ ntfy -b pushover -o user_key t0k3n send 'Pushover test!'
$ ntfy -t 'ntfy' send "Here's a custom notification title!"
$ echo -e 'backends: ["pushover"]npushover: {"user_key": "t0k3n"}' > ~/.ntfy.yml
$ ntfy send "Pushover via config file!"
$ ntfy done --pid 6379 # pid extra
$ ntfy send ":tada: ntfy supports emoji! :100:" # emoji extra
# Enable shell integration
$ echo 'eval "$(ntfy shell-integration)"' >> ~/.bashrcThe install technique in the quickstart is the suggested method of installation.
It can be installed in a virtualenv, but with some caveats: Linux notifications
require --system-site-packages for the virtualenv and OS X notifications
don't work at all.
? NOTE: Linux Desktop Notifications require Python DBUS bindings. See here for more info.
ntfy has support for automatically sending notifications when long
running commands finish in bash and zsh. In bash it emulates zsh's preexec and
precmd functionality with rcaloras/bash-preexec.
To enable it add the following to your .bashrc or .zshrc:
eval "$(ntfy shell-integration)"By default it will only send notifications for commands lasting longer than 10
seconds and if the terminal is focused. Terminal focus works on X11(Linux) and
with Terminal.app and iTerm2 on MacOS. Both options can be configured via the
--longer-than and --foreground-too options.
To avoid unnecessary notifications when running interactive programs, programs
listed in AUTO_NTFY_DONE_IGNORE don't generate notifications. For example:
export AUTO_NTFY_DONE_IGNORE="vim screen meld"ntfy has a few features that require extra dependencies.ntfy done -p $PID requires installing as pip install ntfy[pid]pip install ntfy[emoji]pip install ntfy[xmpp]pip install ntfy[telegram]pip install ntfy[instapush]pip install ntfy[slack]pip install ntfy[rocketchat]To install multiple extras, separate with commas: e.g., pip install ntfy[pid,emoji].
ntfyntfy is configured with a YAML file stored at ~/.ntfy.yml or in standard platform specific locations:
~/.config/ntfy/ntfy.yml~/Library/Application Support/ntfy/ntfy.ymlC:Users<User>AppDataLocaldschepntfy.ymlThe backends key specifies what backends to use by default. Each backend has its own configuration, stored in a key of its own name. For example:
---
backends:
- pushover
pushover:
user_key: hunter2
pushbullet:
access_token: hunter2
simplepush:
key: hunter2
slack:
token: slacktoken
recipient: "#slackchannel"
xmpp:
jid: "[email protected]"
password: "xxxx"
mtype: "chat"
recipient: "[email protected]"If you want mulitple configs for the same backend type, you can specify any name and then specify the backend with a backend key. For example:
---
pushover:
user_key: hunter2
cellphone:
backend: pushover
user_key: hunter2See the backends below for available backends and options. As of v2.6.0 ntfy also supports
3rd party backends
pushoveruser_keysoundpriorityexpireretrycallbackapi_token - use your own application tokendevice - target a device, if omitted, notification is sent to all devicesurlurl_titlehtmlpushbulletaccess_token - Your Pushbullet access token, created at https://www.pushbullet.com/#settings/accountdevice_iden - a device identifier, if omited, notification is sent to all devicesemail - send notification to pushbullet user with the specified email or send an email if they aren't a pushullet usersimplepushkey - Your Simplepush key, created by installing the Android App (no registration required) at https://simplepush.ioevent - sets ringtone and vibration pattern for incoming notifications (can be defined in the simplepush app)xmppjidpasswordrecipienthostname (if not from jid)portpath_to_certsmtypeRequires extras, install like this: pip install ntfy[xmpp].
To verify the SSL certificates offered by a server: path_to_certs = "path/to/ca/cert"
Without dnspython library installed, you will need to specify the server hostname if it doesn't match the jid.
Specify port if other than 5222. NOTE: Ignored without specified hostname
NOTE: Google Hangouts doesn't support XMPP since 2017
telegramRequires extras, install like this: pip install ntfy[telegram].
Requires ntfy to be installed as ntfy[telegram]. This backend is
configured the first time you will try to use it: ntfy -b telegram send
"Telegram configured for ntfy".
pushjetsecret - The Pushjet service secret token, created with http://docs.pushjet.io/docs/creating-a-new-serviceendpoint - custom Pushjet API endpointlevel - The importance level from 1(low) to 5(high)linknotificowebhook - The webhook link, created at https://n.tkte.ch/Plain Text service when creating the webhook)slackRequires extras, install like this: pip install ntfy[slack].
token - The Slack service secret token, either a legacy user token created at https://api.slack.com/custom-integrations/legacy-tokens or a token obtained by creating an app at https://api.slack.com/apps?new_app=1 with chat:write:bot scope and linking it to a workspace.recipient - The Slack channel or user to send notifications to. If you use the # symbol the message is send to a Slack channel and if you use the @ symbol the message is send to a Slack user.slack_webhookurl - the URL of the incoming webhookuser - The Slack channel or user to send notifications toinstaRequires extras, install like this pip install ntfy[instapush].
Instapush does not support notification title. It sends template-driven notifications, so you have to setup you events on the dashboard first. The backend is called insta due to homonymy with the instapush python wrapper
appid - The application idsecret - The application secretevent_name - The instapush event to be usedtrackers - The array of trakers to useNote on trackers: Trackers are placeholders for events (a sort of notification template). If you defined more than one tracker in your event you'll have to provide more messages. At the moment, the only way to do so is to separate each message with a colon (:) character. You can also escape the separator character: Example:
ntfy -b insta send "message1:message2"
ntfy -b insta send "message1:message2:with:colons"prowlapi_keyprovider_keypriorityurllinuxWorks via dbus, works with most DEs like Gnome, KDE, XFCE and with libnotify.
The following dependecies should be installed.
$ sudo apt install python-dbus # on ubuntu/debianYou will need to install some font that supports emojis (in Debian fonts-symbola or Gentoo media-fonts/symbola).
icon - Specifies path to the notification icon, empty string for no icon.urgency - Specifies the urgency level (low, normal, critical).transient - Skip the history (exp: the Gnome message tray) (true, false).soundfile - Specifies the notification sound file (e.g. /usr/share/sounds/notif.wav).timeout - Specifies notification expiration time level (-1 - system default, 0 - never expire).win32Uses pywin32.
darwinRequires ntfy to be installed globally (not in a virtualenv).
systemlogUses the syslog core Python module, which is not available on Windows
platforms.
prio - Syslog priority level. Default is ALERT. Possible values
are:
facility - Syslog facility. Default is LOCAL5. Possible values
are:
fmt - Format of the message to be sent to the system logger. The
title and the message are specified using the following placeholders:
{title}{message}Default is [{title}] {message}.
termuxRequires the app to be install from the Play store and the CLI utility be
installed with apt install termux-api.
pushalotauth_token - Your private Pushalot auth token, found here https://pushalot.com/manager/authorizationssource - source of the notificationttl - message expire time in minutes (time to live)url - URL to include in the notificationsurl_title - visible URL title (ignored if no url specified)image - URL of image included in the notificationsimportant - mark notifications as importantsilent - mark notifications as silentrocketchatRequires extras, install like this: pip install ntfy[rocketchat].
url - URL of your Rocket.Chat instanceusername - login usernamepassword - login passwordroom - room/channel name to post inmatrixRequires extras, install like this: pip install ntfy[matrix].
url - URL of your homeserver instanceroomId - room to post inuserId - login useridpassword - login passwordtoken - access tokenYou must either specify token, or userId and password.
ntfy_webpushWebpush support is provded by an external ntfy module, install like this: pip install ntfy ntfy-webpush.
subscription_info - A PushSubscription Objectprivate_key - the path to private key file or anything else that works with pywebpush.For more info, see ntfy-webpush <https://github.com/dschep/ntfy-webpush>`_
To use or implement your own backends, specify the full path of the module as your backend. The
module needs to contain a module with a function called notify with the following signature:
def notify(title, message, **kwargs):
"""
kwargs contains retcode if using ntfy done or ntfy shell-integration
and all options in your backend's section of the config
"""
passTitle is configurable with the title key in the config. Example:
---
title: Customized Titlepython setup.py test
