config

📣 Apprise Configuration

Configuration allows you to identify all of your notification services in one or more secure spots.

There are 2 supported formats:

• TEXT: Super basic and easy to use.
• YAML: A wee bit more complicated (when comparing to TEXT) but offers you much more flexibility.

CLI

The following lines work really with the command line:

• --config (-c): so you can manually load configuration files and process the notification URLs from there. You only need to provide this option if you don't have a configuration file already set up in the default search paths (explained below).
• --tag (-g): so you can filter what you notify by the label you assigned to them.

If the Apprise CLI tool is executed without any notification URLs or Configuration based ones specified, then the following local files are tested to see if they exist and can be processed:

• ~/.apprise
• ~/.apprise.yml
• ~/.config/apprise
• ~/.config/apprise.yml

Microsoft Windows users can find the configuration path as:

• %APPDATA%/Apprise/apprise
• %APPDATA%/Apprise/apprise.yml
• %LOCALAPPDATA%/Apprise/apprise
• %LOCALAPPDATA%/Apprise/apprise.yml

Note: The configuration locations identified above are ignored if a --config (-c) argument is specified.

CLI Examples:

Here are some simple examples:

# The following will only send notifications to services that has the
# `tv` tag associated with it.
notify -b "Notify only Kodi's in house" --tag=tv

You can also get your configuration from a web server:

# website
notify --config=https://myserver/my/apprise/config -b "notify everything"

# you can specify as many --config (-c) lines as you want to add more
# and more notification services to be handled:
notify --config=https://myserver/my/apprise/config \
 --config=/a/path/on/the/local/pc -b "notify everything"

# Remember to tag everything because the most powerful feature is to
# load all of your services but only trigger the specific ones you're
# interested in notifying:
notify --config=https://myserver/my/apprise/config \
 --config=/a/path/on/the/local/pc \
 -b "notify urls tagged with my-admin-team only" \
 --tag=my-admin-team

Developers

For developers, there is a new object called AppriseConfig() which works very similar to the AppriseAsset() object. It's just anothr object that can be easily consumed by the Apprise() instance.

Up until now, you would add URLs to Apprise like so:

from apprise import Apprise

# Our object
a = Apprise()

# Add our services (associate a tag with each)
a.add('mailto://user:[email protected]', tag='email')
a.add('gnome://', tag='desktop')

# Send off our all of our notifications (v0.8.0 or less)
a.notify("A message!", title="An Optional Title")

# For Apprise v0.8.1 or newer, the following will notify everything:
# The 'all' is a system level keyword to notify everything disreguarding
# tag assignments:
a.notify("A message!", title="An Optional Title", tag="all")

# To notify specific URLs that were loaded, you can match them by their
# tag; the below would only access out mailto:// entry:
a.notify("A message!", title="An Optional Title", tag="email")

Well this is how little your code has to change with configuration:

from apprise import AppriseConfig

# Create an AppriseConfig() object
config = AppriseConfig()

# Similar to the Apprise() we add our configuration paths

# Add a configuration file by it's local path
config.add('/local/path/on/your/server/config')

# Same as the above, except it's a good idea to get in the
# habit of locating local files with the file:// prefix.
config.add('file://~.apprise')

# URLs work too http:// an https://
config.add('http://localhost/my/apprise/config/url/path')
config.add('http://example.com/config')

# ---
# Our new config object can be simply added into our apprise
# instance as though it were another notification service
# it were a notification service:
a.add(config)

# Send off our all of our notifications
a.notify("A message!", title="An Optional Title")

# filter our notifications by those associated with the
# devops tag:
a.notify(tag="devops")

Apprise Config Format Detection:

File Based (file://)

• .yml and .yaml files are assumed to be YAML
• as anything else is assumed to follow the TEXT

Web Based (http:// and https://)

Apprise is capable of retrieving your configuration from a remote HTTP server. For HTTP requests, the Content-Type HTTP Header (which defines Mime Type) is very important.

Support YAML formats:

• text/yaml
• text/x-yaml
• application/yaml
• application/x-yaml

Support TEXT formats:

• text/plain
• text/html

Force Format

You can always force the format and over-ride anything detected by adding ?format=text or ?format=yaml to your configuration URL.

# force a file that would have otherwise been interpreted as a text file
# to be considered a YAML one:
notify --config=https://myserver/my/apprise/config?format=yaml -b "notify everything"

This also applies to developers whenever they load the AppriseConfig() object:

from apprise import Apprise

# create our object
a = Apprise()

# Our Config object while explicitly setting the format to yaml
# you can pass this in as an argument to the class to save
# ourselves from calling config.add().
config = AppriseConfig('https://myserver/yaml/?format=yaml')

# add our config object into apprise
a.add(config)

# Send our notification to all of the sites loaded from the specified
# configuration website
a.notify("hello world!")

🏷️ Tagging from the CLI:

Tagging (with the --tag= (or -g) allows you to only notify entries from the configuration you defined that you want to. You could define hundreds of entries and through tagging, just notify a few (or if any at all).

# 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