APPRISE(1)

✨ APPRISE(1) — apprise is literally that notification main character ✨

✨ NAME ✨

apprise — Push Notifications that work with just about every platform!

🛠️ SYNOPSIS 🛠️

apprise [options...] service-url...
apprise storage [options...] [action] [url-or-uid...]

Okay bestie, two modes: normal notification mode and storage mode. Periodt. 💅

💖 DESCRIPTION 💖

Okay so apprise lets you send a notification to almost all of the most popular notification services available to us today, like Discord, Telegram, Pushbullet, Slack, Twitter, etc. It’s giving “universal notification adapter” but make it cute. 🦋

• One notification library to rule them all. 👑
• A common and intuitive notification syntax.
• Supports the handling of images (to the notification services that will accept them). 🎀
• It’s incredibly lightweight. ✨
• Amazing response times because all messages sent asynchronously. ⚡

🎀 OPTIONS 🎀

The Apprise options are as follows:

• -b, --body=VALUE — Specify the message body. If no body is specified then content is read from stdin. 🍓
• -t, --title=VALUE — Specify the message title. This field is completely optional.
• -c, --config=CONFIG-URL — Specify one or more configuration locations.
• -a, --attach=ATTACH-URL — Specify one or more file attachment locations.
• -P, --plugin-path=PATH — Specify a path to scan for custom notification plugin support. You can create your own notification by simply creating a Python file that contains the @notify("schema") decorator.

You can optionally choose to specify more than one --plugin-path (-P) to increase the modules included.

• -n, --notification-type=VALUE — Specify the message type (default=info). Possible values are "info", "success", "failure", and "warning".
• -i, --input-format=VALUE — Specify the input message format (default=text). Possible values are "text", "html", and "markdown".
• -T, --theme=VALUE — Specify the default theme.
• -tv, --template-var=NAME=VALUE — Supply a value used by a YAML configuration written with ${NAME}. Specify this option more than once to supply more than one value, but name each one only once. A value not provided here uses the default in the configuration’s template: section, then APPRISE_TEMPLATE_<NAME>. A URL that still has no value available is not loaded.
• -g, --tag=VALUE — Specify one or more tags to filter which services to notify:
  • -g "tagA" -g "tagB": Match tagA OR tagB (Union).
  • -g "tagA,tagB": Match tagA AND tagB (Strict).
  • -g "all": Notify ALL services.
  • (Omitted): Notify untagged services only.

Tag values may include an optional priority prefix and/or retry suffix:

• -g "2:tagA": Match only entries for tagA assigned priority 2.
• -g "tagA:3": Match all tagA entries, retrying each up to 3 times.
• -g "2:tagA:3": Priority-2 tagA entries only, with up to 3 retries.

• -Da, --disable-async — Send notifications synchronously (one after the other) instead of all at once.
• -L, --limit=SECONDS — Give up on the whole run if it’s taking too long, e.g. -L 10 or -L 2.5. By default (0) there’s no limit; see --service-limit below to cap each service on its own instead. If a service is truly stuck, Apprise gives it a few extra seconds to wrap up, then exits anyway with status 5.
• -SL, --service-limit=SECONDS — Give up on any single service if it’s taking too long, e.g. -SL 10 or -SL 2.5, or 0 to turn this off entirely. Leave it unset to use Apprise’s own default of 60 seconds.
• -R, --recursion-depthINTEGER — The number of recursive import entries that can be loaded from within Apprise configuration. By default this is set to 1. If this is set to zero, then import statements found in any configuration is ignored.
• -e, --interpret-escapes — Enable interpretation of backslash escapes. For example, this would convert sequences such as \n and \r to their respected ascii new-line and carriage return characters prior to the delivery of the notification.
• -j, --interpret-emojis — Enable interpretation of emoji strings. For example, this would convert sequences such as :smile: or :grin: to their respected unicode emoji character.
• -S, --storage-path=PATH — Specify the path to the persistent storage caching location.
• -SM, --storage-mode=MODE — Specify the persistent storage operational mode. Possible values are "auto", "flush", and "memory". The default is "auto" if not specified.
• -SPD, --storage-prune-days=INTEGER — Define the number of days the storage prune should run using. Setting this to zero (0) will eliminate all accumulated content. By default this value is 30 (days).
• -SUL, --storage-uid-length=INTEGER — Define the number of unique characters to store persistent cache in. By default this value is 8 (characters).
• -d, --dry-run — Perform a trial run but only prints the notification services to-be triggered to stdout. Notifications are never sent using this mode. 🚫
• -l, --details — Prints details about the current services supported by Apprise.
• -v, --verbose — The more of these you specify, the more verbose the output is. e.g: -vvvv
• -D, --debug — A debug mode; useful for troubleshooting.
• -V, --version — Display the apprise version and exit.
• -h, --help — Show this message and exit.

🗂️ PERSISTENT STORAGE 🗂️

Persistent storage by default writes to the following location unless the environment variable APPRISE_STORAGE_PATH overrides it and/or --storage-path (-SP) is specified to override it:

~/.local/share/apprise/cache

To utilize the persistent storage https://appriseit.com/cli/persistent-storage/ element associated with Apprise, simply specify the keyword storage:

$ apprise storage

The storage action has the following sub actions:

• list — List all of the detected persistent storage elements and their state (stale, active, or unused). This is the default action if nothing further is identified. Results may be filtered by passing one or more 8-character UID prefix strings, or by passing full Apprise service URLs — each URL is resolved to its storage namespace automatically, making it easy to look up a specific plugin’s cache entry without knowing the hash in advance.
• prune — Removes all persistent storage that has not been referenced for more than 30 days. You can optionally set the --storage-prune-days to alter this default value.
• clean — Removes all persistent storage regardless of age.

🚦 EXIT STATUS 🚦

apprise exits with a status of:

• 0 — if all of the notifications were sent successfully. 💖
• 1 — if every notification failed, or the notification could not start.
• 2 — if there was an error specified on the command line such as not providing a valid argument.
• 3 — if one or more Apprise Service URLs were successfully loaded but none could be notified due to user filtering (via tags).
• 4 — if at least one notification was sent successfully and at least one other was not (whether it failed outright or ran out of time).
• 5 — if no notification was sent, and the only problem was that one or more services ran out of time.

🔗 SERVICE URLS 🔗

There are too many service URL and combinations to list here. It’s best to visit the Apprise GitHub page https://appriseit.com/services/ and see what’s available. Also try out the Apprise URL Builder https://appriseit.com/tools/url-builder/ to easily construct the URLS this tool supports and works with.

The environment variable of APPRISE_URLS (comma/space delimited) can be specified to provide the default set of URLs you wish to notify if none are otherwise specified.

🌸 EXAMPLES 🌸

Send a notification to multiple services by chaining their URLs:

$ apprise -vv -t "my title" -b "my notification body" \
   "mailto://myemail:mypass@gmail.com" \
   "pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b"

If you don’t specify a --body (-b) then stdin is used allowing you to use the tool as part of your every day administration:

$ cat /proc/cpuinfo | apprise -vv -t "cpu info" \
    "mailto://myemail:mypass@gmail.com"

Load in a configuration file which identifies all of your notification service URLs and notify them all:

$ apprise -vv -t "my title" -b "my notification body" \
   --config=~/apprise.yml

Load in a configuration file from a remote server that identifies all of your notification service URLs and only notify the ones tagged as devops.

$ apprise -vv -t "my title" -b "my notification body" \
   --config=https://localhost/my/apprise/config \
   -t devops

🏷️ Tagging Logic Examples 🏷️

Notify any service tagged with "devops" OR "admin" (Union):

$ apprise -vv -t "Union Test" \
   --config=~/apprise.yml \
   -g devops -g admin

Notify only services tagged with BOTH "devops" AND "critical" (Intersection):

$ apprise -vv -t "Intersection Test" \
   --config=~/apprise.yml \
   -g devops,critical

Notify only priority-2 "alerts" services (exclusive priority filter):

$ apprise -vv -t "High Alert" \
   --config=~/apprise.yml \
   -g "2:alerts"

Notify all "alerts" services and retry each up to 3 times on failure:

$ apprise -vv -t "Critical Event" \
   --config=~/apprise.yml \
   -g "alerts:3"

Include an attachment:

$ apprise -vv -t "School Assignment" -b "See attached" \
   --attach=Documents/FinalReport.docx

List all of the notifications loaded:

$ apprise --dry-run --tag=all

List all of the details around the current persistent storage setup:

$ apprise storage list

Look up the storage namespace for a specific notification URL (shows the UID even when no data has been written yet):

$ apprise storage list "mailtos://user:pass@example.com"

Prune all persistent storage that has not been referenced for at least 10 days or more

$ apprise storage prune --storage-prune-days=10

🧩 CUSTOM PLUGIN/NOTIFICATIONS 🧩

okay so this is the part where Apprise lets you be the main character 💅 You can define your own custom schema:// entries, trigger them like any other service, and have them call whatever services you've already defined. literally build-your-own-notification, no cap.

By default, apprise goes looking in these local spots for custom plugin files and loads whatever it finds:

~/.apprise/plugins
~/.config/apprise/plugins
/var/lib/apprise/plugins

If you wanna override that whole list with your own, just set the APPRISE_PLUGIN_PATH environment variable. Use a semi-colon (;), line-feed (\n), and/or carriage return (\r) to delimit multiple entries. easy peasy 🎀

Then you literally just make your own Python file with this bare minimum content in it:

from apprise.decorators import notify

# This example assumes you want your function to trigger on foobar://
# references:
@notify(on="foobar", name="My Custom Notification")
def my_wrapper(body, title, notify_type, *args, **kwargs):

     print("Define your custom code here")

     # Returning True/False will relay your status back through Apprise
     # Returning nothing (None by default) is always interpreted as True
     return True

like, that's it. that's the whole vibe. ✨

---

⚙️ CONFIGURATION ⚙️

An Apprise configuration file (https://appriseit.com/getting-started/configuration/) can be in the format of either TEXT or YAML — and TEXT is the easiest and most ideal solution for most users. But! YAML config files grant you a bit more leverage and access to some of the internal features of Apprise. Regardless of which format you pick, both let you leverage tagging, which adds a more rich and powerful notification environment 🏆

Configuration files can be directly referenced via apprise when you reference the --config= (-c) CLI directive. You can identify as many as you like on the command line and all of them will be loaded. You can also point your configuration to a cloud location (by referencing http:// or https://). By default, apprise looks in these local locations for configuration files and loads them:

~/.apprise.conf
~/.apprise.yaml
~/.config/apprise.conf
~/.config/apprise.yaml

~/.apprise/apprise.conf
~/.apprise/apprise.yaml
~/.config/apprise/apprise.conf
~/.config/apprise/apprise.yaml

/etc/apprise.conf
/etc/apprise.yaml
/etc/apprise/apprise.conf
/etc/apprise/apprise.yaml

The configuration files listed above can also be identified with a .yml extension, or even by just entirely removing the .conf extension altogether. flexible queen 💅

The environment variable APPRISE_CONFIG_PATH can be specified to override the list above with one of your own. Use a semi-colon (;), line-feed (\n), and/or carriage return (\r) to delimit multiple entries.

So here's the slay part: if a default configuration file is referenced in any way by the apprise tool, you no longer need to provide it a Service URL. Usage of the apprise tool simplifies to:

$ apprise -vv -t "my title" -b "my notification body"

And if you leveraged tagging (https://appriseit.com/cli/usage/#tagging-and-filtering), you can define all of the Apprise Service URLs you want in your configuration and then only specifically notify a subset of them:

$ apprise -vv --title "Will Be Late Getting Home" \
    --body "Please go ahead and make dinner without me." \
    --tag=family

🫶 lowkey the tagging thing is the best part, iykyk

🧚 TEMPLATE VARIABLES 🧚

A YAML configuration can leave a value out of a URL and have it filled in later. Write ${NAME} where the value belongs and declare every name you use in a template: section:

template:
  # A value written here is used when nothing else supplies one
  smtp_host: smtp.example.com
  # No value, so this one must always be supplied
  api_key:

urls:
  - sendgrid://${API_KEY}:noreply@example.com/you@example.com:
      - tag: alerts

Values are looked for in this order, stopping at the first one that answers:

1. a value given with --template-var (-tv)
2. the default written in the template: section
3. the environment variable APPRISE_TEMPLATE_<NAME>

A URL with no value available is not loaded, and apprise exits with a status of 4 if others were notified, or 1 if none were. Use --dry-run to see which values a configuration is still waiting for 👀

${NAME} only means something when NAME appears in the template: section. Anywhere else it's ordinary text and is sent exactly as written, so a password containing ${...} is never altered. periodt. Names ignore case, and a name may be used as often as you like. Values may be up to 1,024 characters. Extra supplied names are accepted and ignored; their names appear only in the local debug log, never with their values. 🔒

The configuration author may place a variable directly in a URL or in a named YAML setting below it. URL markers can change any field, including the destination; whole-host markers also accept user@host and user:pass@host. A named setting changes only its option, so prefer it for values supplied by less-trusted callers. 💡

careful bestie: a variable may not appear before ://, may not be used for tag:/tags:, and may not be used as a setting's name. The service and tags are selected before values are filled in, so neither can be dynamic.

This applies to YAML configuration only; TEXT configuration is passed through unchanged.

---

🌈 ENVIRONMENT VARIABLES 🌈

• APPRISE_URLS — Specify the default URLs to notify IF none are otherwise specified on the command line explicitly. If --config (-c) is specified, then this will override any reference to this variable. Use white space and/or a comma (,) to delimit multiple entries.
• APPRISE_CONFIG_PATH — Explicitly specify the config search path to use (overriding the default). Use a semi-colon (;), line-feed (\n), and/or carriage return (\r) to delimit multiple entries.
• APPRISE_PLUGIN_PATH — Explicitly specify the custom plugin search path to use (overriding the default). Use a semi-colon (;), line-feed (\n), and/or carriage return (\r) to delimit multiple entries.
• APPRISE_STORAGE_PATH — Explicitly specify the persistent storage path to use (overriding the default).
• APPRISE_TEMPLATE_<NAME> — Supply a value for a ${NAME} used by a YAML configuration. For example APPRISE_TEMPLATE_API_KEY fills in ${API_KEY}. A value supplied with --template-var (-tv) and a configuration default both take priority. Blank values are ignored.
• HTTP_PROXY, HTTPS_PROXY, NO_PROXY — Standard proxy variables honored by the underlying requests library (not Apprise-specific). Set HTTP_PROXY/HTTPS_PROXY to route outbound notifications through a proxy, and NO_PROXY to exempt specific hosts. SOCKS proxies (socks5h://...) additionally require the optional PySocks package (pip install pysocks) to be installed.

---

🐛 BUGS 🐛

If you find any bugs, please make them known at: https://github.com/caronc/apprise/issues

no gatekeeping, we wanna know 🙈

---

💖 DONATIONS 💖

If you found Apprise useful at all, please consider sponsoring https://github.com/sponsors/caronc or donating https://www.paypal.com/donate/?hosted_button_id=CR6YF7KLQWQ5E!

like fr fr, even a lil bit helps 🫶✨

---

👑 COPYRIGHT 👑

Apprise is Copyright (C) 2026 Chris Caron lead2gold@gmail.com

---

and that's a wrap bestie 🎀 this absolute icon of a page is brought to you by Chris Caron <lead2gold@gmail.com>, dated September 2026, and it lives in section APPRISE(1) of your manual — go forth and notify responsibly 💅✨🦋