Repository files navigation

ntfy brings notification to your shell. It can automatically providedesktop notifications when long running commands finish or it can sendpush notifications to your phone when a specific command finishes.Confused? This video demonstrates some of this functionality:

$ sudo pip install ntfy$ ntfy sendtest# send a notification when the command `sleep 10` finishes# this sends the message '"sleep 10" succeeded in 0:10 minutes'$ ntfydone 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!"$ ntfydone --pid 6379# pid extra$ ntfy send":tada: ntfy supports emoji! :100:"# emoji extra# Enable shell integration$echo'eval "$(ntfy shell-integration)"'>>~/.bashrc

The install technique in the quickstart is the suggested method ofinstallation. It can be installed in a virtualenv, but with somecaveats: Linux notifications require--system-site-packages for thevirtualenv and OS X notifications don't work at all.

🐧 NOTE:Linux DesktopNotifications require Python DBUSbindings. Seehere for moreinfo.

ntfy has support forautomatically sending notifications when longrunning commands finish in bash and zsh. In bash it emulates zsh'spreexec and precmd functionality withrcaloras/bash-preexec. Toenable it add the following to your.bashrc or.zshrc:

eval"$(ntfy shell-integration)"

By default it will only send notifications for commands lasting longerthan 10 seconds and if the terminal is focused. Terminal focus works onX11(Linux) and with Terminal.app and iTerm2 on MacOS. Both options canbe configured via the--longer-than and--foreground-too options.

To avoid unnecessary notifications when running interactive programs,programs listed inAUTO_NTFY_DONE_IGNORE don't generatenotifications. 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 aspip install ntfy[pid]-emoji support requiresinstalling aspip install ntfy[emoji]-XMPP support requires installing aspip install ntfy[xmpp]-Telegram support requires installing aspip install ntfy[telegram]-Instapush support requires installingaspip install ntfy[instapush]-Slack support requires installing aspip install ntfy[slack]-Slack Incoming webhook - simpler slackimplementation that doesn't have additional dependencies-Rocket.Chat support requires installingaspip install ntfy[rocketchat]

To install multiple extras, separate with commas: e.g.,pip install ntfy[pid,emoji].

ntfy is configured with a YAML file stored at~/.ntfy.yml or instandard platform specific locations:

• Linux -~/.config/ntfy/ntfy.yml
• macOS -~/Library/Application Support/ntfy/ntfy.yml
• Windows -C:\Users\<User>\AppData\Local\dschep\ntfy.yml

The backends key specifies what backends to use by default. Each backendhas its own configuration, stored in a key of its own name. For example:

---backends:    -pushoverpushover:user_key:hunter2pushbullet:access_token:hunter2simplepush:key:hunter2slack:token:slacktokenrecipient:"#slackchannel"xmpp:jid:"user@gmail.com"password:"xxxx"mtype:"chat"recipient:"me@jit.si"

If you want mulitple configs for the same backend type, you can specifyany name and then specify the backend with a backend key. For example:

---pushover:user_key:hunter2cellphone:backend:pushoveruser_key:hunter2

See the backends below for available backends and options. As of v2.6.0ntfy also supports3rd party backends

Required parameters:

: -user_key

Optional parameters:

: -sound-priority-expire-retry-callback-api_token - use your own application token-device - target a device, if omitted, notification is sent toall devices-url-url_title-html

Required parameter:

: -access_token - Your Pushbullet access token, created athttps://www.pushbullet.com/#settings/account

Optional parameters:

: -device_iden - a device identifier, if omited, notification issent to all devices-email - send notification to pushbullet user with thespecified email or send an email if they aren't a pushulletuser

Required parameter:

: -key - Your Simplepush key, created by installing the AndroidApp (no registration required) athttps://simplepush.io

Optional parameters:

: -event - sets ringtone and vibration pattern for incomingnotifications (can be defined in the simplepush app)

Requires parameters:

: -jid-password-recipient

Optional parameters

: -hostname (if not from jid)-port-path_to_certs-mtype

Requires 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 serverhostname if it doesn't match the jid.

Specify port if other than 5222. NOTE: Ignored without specifiedhostname

NOTE: Google Hangouts doesn't support XMPP since 2017

Requires extras, install like this:pip install ntfy[telegram].

Requiresntfy to be installed asntfy[telegram]. This backend isconfigured the first time you will try to use it:ntfy -b telegram send "Telegram configured for ntfy".

Required parameter:

: -secret - The Pushjet service secret token, created withhttp://docs.pushjet.io/docs/creating-a-new-service

Optional parameters:

: -

    `endpoint` - custom Pushjet API endpoint    :   (defaults to <https://api.pushjet.io>)-   `level` - The importance level from 1(low) to 5(high)-   `link`

Required parameter:

: -

    `webhook` - The webhook link, created at <https://n.tkte.ch/>    :   (choose `Plain Text` service when creating the webhook)

Requires extras, install like this:pip install ntfy[slack].

Required parameter:

: -token - The Slack service secret token, either a legacy usertoken created athttps://api.slack.com/custom-integrations/legacy-tokens or atoken obtained by creating an app athttps://api.slack.com/apps?new_app=1 withchat:write:botscope and linking it to a workspace.-recipient - The Slack channel or user to send notificationsto. If you use the# symbol the message is send to a Slackchannel and if you use the@ symbol the message is send to aSlack user.

Slack Incoming Webhook -slack_webhook~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Required parameter: *url - the URL of the incoming webhook *user - The Slack channel or user to send notifications to

Requires extras, install like thispip install ntfy[instapush].

Instapush does not support notification title. It sends template-drivennotifications, so you have to setup you events on the dashboard first.The backend is called insta due to homonymy with the instapush pythonwrapper

Required parameters:

: -appid - The application id-secret - The application secret-event_name - The instapush event to be used-trackers - The array of trakers to use

Note on trackers: Trackers are placeholders for events (a sort ofnotification template). If you defined more than one tracker in yourevent you'll have to provide more messages. At the moment, the only wayto do so is to separate each message with a colon (:) character. You canalso escape the separator character: Example:

ntfy -b insta send"message1:message2"ntfy -b insta send"message1:message2\:with\:colons"

Optional parameters:

: -api_key-provider_key-priority-url

Works via [dbus]{.title-ref}, works with most DEs like Gnome, KDE, XFCEand with libnotify.

The following dependecies should be installed.

$ sudo apt install python-dbus# on ubuntu/debian

You will need to install some font that supports emojis (in Debian[fonts-symbola]{.title-ref} or Gentoo[media-fonts/symbola]{.title-ref}).

Optional parameters:

: -icon - Specifies path to the notification icon, empty stringfor 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).

Usespywin32.

Requiresntfy to be installed globally (not in a virtualenv).

Uses thesyslog core Python module, which is not available on Windowsplatforms.

Optional parameters:

: -prio - Syslog priority level. Default isALERT. Possiblevalues are:

    -   EMERG    -   ALERT    -   CRIT    -   ERR    -   WARNING    -   NOTICE    -   INFO    -   DEBUG-   `facility` - Syslog facility. Default is `LOCAL5`. Possible    values are:    -   KERN    -   USER    -   MAIL    -   DAEMON    -   AUTH    -   LPR    -   NEWS    -   UUCP    -   CRON    -   SYSLOG    -   LOCAL0    -   LOCAL1    -   LOCAL2    -   LOCAL3    -   LOCAL4    -   LOCAL5    -   LOCAL6    -   LOCAL7-   `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}`.

Requires the app to be install from the Play store and the CLI utilitybe installed withapt install termux-api.

Required parameter:

: -auth_token - Your private Pushalot auth token, found herehttps://pushalot.com/manager/authorizations

Optional parameters:

: -source - source of the notification-ttl - message expire time in minutes (time to live)-url - URL to include in the notifications-url_title - visible URL title (ignored if no url specified)-image - URL of image included in the notifications-important - mark notifications as important-silent - mark notifications as silent

Requires extras, install like this:pip install ntfy[rocketchat].

Required parameters:

: -url - URL of your Rocket.Chat instance-username - login username-password - login password-room - room/channel name to post in

Requires extras, install like this:pip install ntfy[matrix].

Required parameters:

: -url - URL of your homeserver instance-roomId - room to post in-userId - login userid-password - login password-token - access token

You must either specifytoken, oruserId andpassword.

Webpush -ntfy_webpush~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Webpush support is provded by an external ntfy module, install likethis:pip install ntfy ntfy-webpush.

Required parameters:

: -subscription_info - APushSubscriptionObject-private_key - the path to private key file or anything elsethat works withpywebpush.

For more info, see [ntfy-webpush]{#ntfy-webpush}<https://github.com/dschep/ntfy-webpush\>\`\_

To use or implement your own backends, specify the full path of themodule as your backend. The module needs to contain a module with afunction callednotify with the following signature:

defnotify(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    """pass

Title is configurable with the [title]{.title-ref} key in the config.Example:

---title:Customized Title

• Airgram
• Boxcar

python setup.pytest

• dschep - Maintainer & Lead Developer
• danryder - XMPP Backend & emojisupport
• oz123 - Linux desktop notificationimprovements
• schwert - PushJet support
• rahiel - Telegram support
• tymm - Simplepush support
• jungle-boogie - Documentationupdates
• tjbenator - Advanced Pushoveroptions
• mobiusklein - Win32 Bugfix
• rcaloras - Creator of[bash-prexec]{.title-ref}, without which there woudn't be bashshell integration for [ntfy]{.title-ref}
• eightnoteight - Notifico support
• juanpabloaj - Slack support
• giuseongit - Instapush support
• jlesage - Systemlog support
• sambrightman - Prowl support
• mlesniew - Pushalot support
• webworxshop - Rocket.Chat support
• rhabbachi - transient option inLinux desktop notifications
• Half-Shot - Matrix support