diff --git a/CLI_Usage.md b/CLI_Usage.md index 1dca63d..66696ab 100644 --- a/CLI_Usage.md +++ b/CLI_Usage.md @@ -1,6 +1,7 @@ -## Apprise CLI +## :mega: 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. ```bash # Set a notification to a hotmail (email) account: @@ -23,3 +24,90 @@ python apprise --body="Notify more than one service" \ 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|config]]. With respect to the above example, maybe your file will look like this: +```apache +# 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: +```bash +# 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: +```bash +# Set a notification to a yahoo email account, Slack, and a Kodi Server: +python apprise --body="Notify all of my services" +``` + +### :label: 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: +```apache +# 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: = +me,family=mailto://user:password@yahoo.com +family=mailto://user:password@yahoo.com/myspouse@example.com/mychild@example.com +team=slack://token_a/token_b/token_c/#devops +devops=slack://token_a/token_b/token_c/#build_status +team,email=mailto://user:password@yahoo.com/john@mycompany.com/jack@mycompany.com/jason@mycompany.com +downloads=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: +```bash +# 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: +```bash +# 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: +```bash +# 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 +``` \ No newline at end of file