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

Now your reference to the Apprise CLI got even easier:

# Set a notification to a yahoo email account, Slack, and a Kodi Server:
python 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 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 apprise a configuration file for a Work/Home account and fill it with tags:

# 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
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

Now there is a lot to ingest from the above, but here is a great (relatively simple) example of how you can use this:

# Send an alert to yourself and your spouse; this would trigger
# the first 2 entries because they have the tag `family`
# It would 'NOT' send to any other entry defined
python apprise --body="Hi guys, i'm going to be late getting home tonight" \
   --tag=family

# This would just send yourself an email:
python 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:

# This would just send yourself an email:
```bash
# notify the services that have either a `devops` or `team` tag
# If you check our our configuration; this matches 3 separate URLs
python 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.
python 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:
notify -b "has TagA" --tag=TagA
notify -b "has TagA OR TagB" --tag=TagA --tag=TagB

# For each item you group with the same --tag value is AND'ed
notify -b "has TagA AND TagB" --tag="TagA, TagB"
notify -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:
python 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 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:
python apprise --tag=team,email --dry-run

Happy notifying!