CLI_Usage

📣 Apprise CLI

This small tool wraps the apprise python library to allow individuals such as Developers, DevOps, and Administrators to send notifications from the command line.

Getting Started

Apprise in it's most basic form requires that you provide it a message and an Apprise URL which contains enough information to send the notification with.

# Set a notification to a hotmail (email) account:
apprise --body="My Message" mailto://user:password@hotmail.com

If you don't specify a --body (-b) then Apprise reads from stdin instead:

# without a --body, you can use a pipe | to redirect output
# into you're notification:
uptime | apprise mailto://user:password@hotmail.com

There is no limit to the number of services you want to notify, just keep adding/chaining them one after another:

# Set a notification to a yahoo email account, Slack, and a Kodi Server:
apprise --body="Notify more than one service" \
   mailto://user:password@yahoo.com \
   slack://token_a/token_b/token_c \
   kodi://example.com

File Based Configuration

Ideally it's never safe to store your personal details on the command line; others might see it! So the best thing to do is stick your configuration into a simple configuration file. With respect to the above example, maybe your file will look like this:

# use hashtag/pound characters to add comments into your
# configuration file.  Define all of your URLs one after
# another:
mailto://user:password@yahoo.com
slack://token_a/token_b/token_c
kodi://example.com

Then you can notify all of your services like so:

# Set a notification to a yahoo email account, Slack, and a Kodi Server:
apprise --body="Notify more than one service" \
   --config=/path/to/your/apprise/config.txt

If you stick your configuration in the right locations, you don't even need to reference the --config as it will be included automatically; the default filename paths are as follows:

• Linux/Mac users:
  • ~/.apprise
  • ~/.config/apprise
• Microsoft Windows users:
  • %APPDATA%/Apprise/apprise
  • %LOCALAPPDATA%/Apprise/apprise

With default configuration file(s) in place, reference to the Apprise CLI gets even easier:

# Set a notification to a yahoo email account, Slack, and a Kodi Server:
apprise --body="Notify all of my services"

🏷️ Leverage Tagging

Consider the case where you've defined all of your Apprise URLs in one file, but you don't want to notify all of them each and every time.

• 📥 Maybe you have special notifications that only fire when a download completed.
• 🚨 Maybe you have home monitoring that requires you to notify several different locations
• 👷‍♂️ Perhaps you work as an Administrative, Developer, and/or Devops role and you want to just notify certain people at certain times (such as when a software build completes, or a unit test fails, etc).

Apprise makes this easy by simply allowing you to tag your URLs. There is no limit to the number of tags associate with a URL. Let's make a simple apprise configuration file; this can be done with any text editor of your choice:

# Tags in a Text configuration sit in front of the URL
#  - They are comma and/or space separated (if more than one
#  - To mark that you are no longer specifying tags and want to identify
#    the URL, you just place an equal (=) sign and write the URL:
#
# Syntax: <tags>=<url>

# Here we set up a mailto:// URL and assign it the tags: me, and family
# maybe we are doing this to just identify our personal email and
# additionally tag ourselves with the family (which we will tag elsewhere
# too)
me,family=mailto://user:password@yahoo.com

# Here we set up a mailto:// URL and assign it the tag: family
# In this example, we would email 2 people if triggered
family=mailto://user:password@yahoo.com/myspouse@example.com/mychild@example.com

# This might be our Slack Team Server targeting the #devops channel
# We assign it the tag: team
team=slack://token_a/token_b/token_c/#general

# Maybe our company has a special devops group too idling in another
# channel; we can add that to our list too and assign it the tag: devops
devops=slack://token_a/token_b/token_c/#devops

# Here we assign all of our colleagues the tags: team, and email
team,email=mailto://user:password@yahoo.com/john@mycompany.com/jack@mycompany.com/jason@mycompany.com

# Maybe we have home automation at home, and we want to notify our 
# kodi box when stuff becomes available to it
mytv=kodi://example.com

# There is no limit... fill this file to your hearts content following
# the simple logic identified above

Now there is a lot to ingest from the configuration above, but it will make more sense when you see how the content is referenced. Here are a few examples (based on config above):

# This would notify the first 2 entries they have the tag `family`
# It would 'NOT' send to any other entry defined
apprise --body="Hi guys, I'm going to be late getting home tonight" \
   --tag=family

# This would only notify the first entry as it is the only one
# that has the tag: me
apprise --body="Don't forget to buy eggs!" \
   --tag=me

If you're building software, you can set up your continuous integration to notify your team AND devops by simply identifying 2 tags:

# notify the services that have either a `devops` or `team` tag
# If you check our our configuration; this matches 3 separate URLs
apprise --title="Apprise Build" \
   --body="Build was a success!" \
   --tag=devops --tag=team

When you specify more than one --tag the contents are OR'ed together.

If you identify more than one element on the same --tag using a space and/or comma, then these get treated as an AND. Here is an example:

# notify only the services that have both a team and email tag
# In this example, there is only one match.
apprise --title="Meeting this Friday" \
   --body="Guys, there is a meeting this Friday with our director." \
   --tag=team,email

There is a special reserved tag called all. all will match ALL of your entries regardless of what tag name you gave it. Use this with caution.

Here is another way of looking at it:

# assuming you got your configuration in place; tagging works like so:
apprise -b "has TagA" --tag=TagA
apprise -b "has TagA OR TagB" --tag=TagA --tag=TagB

# For each item you group with the same --tag value is AND'ed
apprise -b "has TagA AND TagB" --tag="TagA, TagB"
apprise -b "has (TagA AND TagB) OR TagC" --tag="TagA, TagB" --tag=TagC

Testing Configuration and Tags

Once you've built your elaborate configuration file and assigned all your tags. You certainly won't want to notify everyone over and over again while you test it out. Don't worry, that's what --dry-run (-d) is for. You can use this to test your tag logic out and not actually perform the notification.

# Test which services would have been notified if the tags team and email
# were activated:
apprise --title="Meeting this Friday" \
   --body="Guys, there is a meeting this Friday with our director." \
   --tag=team,email \
   --dry-run

If you use the --dry-run (-d) switch, then some rules don't apply. For one, the --body (-b) is not even a required option. The above could have been re-written like so:

# Test which services would have been notified if the tags team and email
# were activated (without actually notifying them):
apprise --tag=team,email --dry-run

Happy notifying!