mirror of
https://github.com/caronc/apprise.git
synced 2025-08-16 11:38:08 +02:00
Updated CLI_Usage (markdown)
90
CLI_Usage.md
90
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.
|
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
|
||||||
|
```
|
Reference in New Issue
Block a user