Updated CLI_Usage (markdown)

Chris Caron
2019-09-30 14:47:47 -04:00
parent 4ab72930a7
commit e2f63ff44c

@ -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. 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. 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 ```bash
# Set a notification to a hotmail (email) account: # Set a notification to a hotmail (email) account:
@ -23,3 +24,90 @@ python apprise --body="Notify more than one service" \
kodi://example.com 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: <tags>=<url>
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
```