Usage & Arguments

This guide covers everything from basic flags to advanced scripting techniques with the Apprise CLI.

Command Line Arguments

You can view the full help menu at any time by running apprise --help.

Message Composition

Flag	Long flag	Description
-b	--body	The message body to send. If omitted, Apprise reads from stdin.
-t	--title	The message title (optional).
-n	--notification-type	Notification type. Values: info, success, warning, failure. Default is info.
-i	--input-format	Input format. Values: text, html, markdown. Default is text.
-e	--interpret-escapes	Interpret backslash escapes in --body (for example \n, \r).
-j	--interpret-emojis	Interpret emoji shortcodes in --body (for example :smile:).
-T	--theme	Set the default theme.

Configuration, Filtering, and Plugins

Flag	Long flag	Description
-c	--config	One or more configuration locations (local file or remote URL).
-g	--tag	Filter which services to notify (see Tag filtering).
-R	--recursion-depth	Maximum number of recursive include directives allowed while loading config. Default is 1. Set to 0 to ignore include/import statements.
-P	--plugin-path	Add one or more paths to scan for custom notification plugins.

Timeouts

Sometimes a service is slow to respond, or simply unreachable. These flags cap how long Apprise is willing to wait before giving up and moving on.

Flag	Long flag	Description
-L	--limit	Give up on the whole run if it’s taking too long, in seconds (e.g. 2.5). Default 0 – no limit.
-SL	--service-limit	Give up on any single service if it’s taking too long, in seconds, or 0 to turn this off. Leave unset for Apprise’s own default (60 seconds).

# Give up on the whole run after 10 seconds
apprise -t "Status" -b "Quick check" --limit 10 \
    "slack://tokenA/tokenB/tokenC"

# Give each individual service only 5 seconds, no matter how many
# services are being notified
apprise -t "Status" -b "Quick check" --service-limit 5 \
    "slack://tokenA/tokenB/tokenC" "discord://webhook_id/webhook_token"

Tip

--limit caps the whole run; --service-limit caps each service on its own. Use --service-limit when you want consistent patience across many services; use --limit when you just want the whole command to finish by a certain time.

Caution

A time limit can stop Apprise from waiting on a service, but it cannot forcibly stop a service call that is already running. Python cannot neatly interrupt a network request that is stuck halfway through.

With the CLI, if the overall result is TIMEOUT, Apprise waits about 5 extra seconds to let the abandoned call finish on its own. If it is still running, the command exits anyway by stopping the process. In practice, a CLI command usually finishes within about --limit/--service-limit + 5 seconds. That is useful for cron jobs or automations that must not hang forever.

This guarantee is specific to the CLI. A Python app using Apprise as a library cannot stop its whole process just to halt one notification.

Attachments

Flag	Long flag	Description
-a	--attach	One or more attachment locations (local file path or URL). Can be specified multiple times.

Storage

Apprise supports a persistent storage cache. You can tune it with the flags below, or use the apprise storage subcommand.

Flag	Long flag	Description
-S	--storage-path	Path to the persistent storage caching location.
-SM	--storage-mode	Storage mode. Values: auto, flush, memory. Default is auto.
-SPD	--storage-prune-days	Number of days used for storage prune. Default is 30. Set to 0 to delete all accumulated content.
-SUL	--storage-uid-length	Number of unique characters used to store persistent cache in. Default is 8.

Execution and Diagnostics

Flag	Long flag	Description
-Da	--disable-async	Send synchronously (one after the other) instead of in parallel.
-d	--dry-run	Trial run. Prints which services would be triggered to stdout. Does not send notifications.
-l	--details	Print details about currently supported services.
-tv	--template-var	Supply a value for a ${NAME} used by a YAML configuration, written as NAME=VALUE. Repeat for more than one, but name each only once.
-v	--verbose	Increase verbosity. You can stack it (for example -vvvv).
-D	--debug	Debug mode, useful for troubleshooting.
-V	--version	Print version and exit.
-h	--help	Show the help message and exit.

Template Variable Example

First declare the value in a YAML configuration:

apprise.yml

template:
  recipient:

urls:
  - mailtos://user:password@example.com/:
      - to: ${RECIPIENT}

Then supply it when sending:

apprise --config apprise.yml \
  --template-var recipient=admin@example.com \
  --body "Backup complete"

Only names declared under template: are replaced. See Template Variables for defaults, environment values, placement rules, and more examples.

Environment Variables

You can pre-set default behaviors using environment variables. This is useful for containerized environments or setting system-wide defaults.

Variable	Description
APPRISE_URLS	Default service URLs to notify if none are provided on the command line. Space, comma and/or semicolon delimited. If --config is specified, it overrides any APPRISE_URLS reference.
APPRISE_CONFIG_PATH	Override the default configuration search paths. Use ;, \n, and/or \r to delimit multiple entries.
APPRISE_PLUGIN_PATH	Override the default plugin search paths. Use ;, \n, and/or \r to delimit multiple entries.
APPRISE_STORAGE_PATH	Override the default persistent storage path.
APPRISE_TEMPLATE_<NAME>	Supply a value for a ${NAME} used by a YAML configuration. For example APPRISE_TEMPLATE_API_KEY fills in ${API_KEY}. See Template Variables.
HTTP_PROXY, HTTPS_PROXY, NO_PROXY	Standard proxy variables honored automatically (not Apprise-specific). Route outbound notifications through a proxy, or exempt specific hosts with NO_PROXY. See Proxy Support for details, including SOCKS proxies.

Default Configuration Locations

If you do not specify a configuration file via the CLI (--config), Apprise automatically loads a default configuration file for you.

Linux/BSD/Apple

The following configuration files are scanned in the order identified below; the first match is loaded and nothing further is processed thereafter.

1. ~/.apprise
2. ~/.apprise.conf
3. ~/.apprise.yml
4. ~/.apprise.yaml
5. ~/.config/apprise
6. ~/.config/apprise.conf
7. ~/.config/apprise.yml
8. ~/.config/apprise.yaml
9. ~/.apprise/apprise
10. ~/.apprise/apprise.conf
11. ~/.apprise/apprise.yml
12. ~/.apprise/apprise.yaml
13. ~/.config/apprise/apprise
14. ~/.config/apprise/apprise.conf
15. ~/.config/apprise/apprise.yml
16. ~/.config/apprise/apprise.yaml

The following global paths are also searched if nothing is found above:

1. /etc/apprise
2. /etc/apprise.yml
3. /etc/apprise.yaml
4. /etc/apprise/apprise
5. /etc/apprise/apprise.conf
6. /etc/apprise/apprise.yml
7. /etc/apprise/apprise.yaml

Microsoft Windows

The following configuration files are scanned in the order identified below; the first match is loaded and nothing further is processed thereafter.

1. %APPDATA%\Apprise\apprise
2. %APPDATA%\Apprise\apprise.conf
3. %APPDATA%\Apprise\apprise.yml
4. %APPDATA%\Apprise\apprise.yaml
5. %LOCALAPPDATA%\Apprise\apprise
6. %LOCALAPPDATA%\Apprise\apprise.conf
7. %LOCALAPPDATA%\Apprise\apprise.yml
8. %LOCALAPPDATA%\Apprise\apprise.yaml

The following global paths are also searched if nothing is found above:

1. %ALLUSERSPROFILE%\Apprise\apprise
2. %ALLUSERSPROFILE%\Apprise\apprise.conf
3. %ALLUSERSPROFILE%\Apprise\apprise.yml
4. %ALLUSERSPROFILE%\Apprise\apprise.yaml
5. %PROGRAMFILES%\Apprise\apprise
6. %PROGRAMFILES%\Apprise\apprise.conf
7. %PROGRAMFILES%\Apprise\apprise.yml
8. %PROGRAMFILES%\Apprise\apprise.yaml
9. %COMMONPROGRAMFILES%\Apprise\apprise
10. %COMMONPROGRAMFILES%\Apprise\apprise.conf
11. %COMMONPROGRAMFILES%\Apprise\apprise.yml
12. %COMMONPROGRAMFILES%\Apprise\apprise.yaml

For a user named foobar with Microsoft Windows installed on C:\, these paths become:

Environment Variable	Example Translation
%APPDATA%	C:\Users\foobar\AppData\Roaming
%LOCALAPPDATA%	C:\Users\foobar\AppData\Local
%ALLUSERSPROFILE%	C:\ProgramData
%PROGRAMFILES%	C:\Program Files
%COMMONPROGRAMFILES	C:\Program Files\Common Files

Did you know?

Apprise automatically determines the format (TEXT vs YAML) based on the file extension (.yml or .yaml). If your file has no extension, it defaults to TEXT unless valid YAML structure is detected.

File Attachments

You can send files alongside your notifications using the --attach (-a) flag. Apprise handles the upload logic automatically for services that support it (like Discord, Slack, and Telegram).

Local Files

Send a log file or image from your local disk.

apprise \
  --title "System Log" \
  --body "See attached log for details" \
  --attach "/var/log/syslog" \
  "discord://webhook_id/webhook_token"

Remote Attachments

Apprise can fetch a file from a URL and forward it as an attachment.

# Apprise downloads the image and sends it to Telegram
apprise \
  --title "Front Door" \
  --body "Motion detected" \
  --attach "http://camera-ip/snapshot.jpg" \
  "tgram://bot_token/chat_id"

Multiple Attachments

You can specify the flag multiple times to send several files at once.

apprise \
  --body "Here are the build artifacts" \
  --attach "release-notes.txt" \
  --attach "build.zip" \
  "slack://tokenA/tokenB/tokenC"

Tagging and Filtering

Apprise allows you to target specific subsets of your configuration using tags.

Logic Rules

Use --tag (-g) to 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 (tagged and untagged).
• (Omitted): Notify untagged services only.

Another way to look at it:

• OR Logic: To notify services that have either Tag A OR Tag B, use the --tag switch multiple times.
• AND Logic: To notify services that have both Tag A AND Tag B, separate tags with a comma within a single switch.

Priority Filtering

Tags defined in your configuration may carry a numeric priority prefix (for example 1:alerts or 5:alerts in a YAML config). This enables two modes depending on whether you include a priority in your --tag value.

Without a priority prefix – escalation mode (default)

When you pass a plain tag name, Apprise dispatches services in ascending priority order. If every service in the lowest-numbered group succeeds, Apprise returns immediately and skips all higher-numbered groups. If any service in that group fails, Apprise escalates to the next group.

• -g "alerts": Dispatch priority-1 entries first. If they all succeed, skip priority-5 (and any others). If any fail, run the priority-5 entries as a fallback.

With a priority prefix – exclusive mode

When you include a numeric prefix in the tag value, Apprise targets only services whose alerts tag carries that exact priority. No other priority levels are triggered.

• -g "2:alerts": Trigger only alerts entries assigned priority 2.

Per-Call Retry Override

A tag value may also carry a trailing retry count (:N) that overrides each matched service’s configured retry for this one call only:

• -g "alerts:3": Notify all alerts services, retrying each up to 3 times on failure.
• -g "2:alerts:3": Notify priority-2 alerts services only, with up to 3 retries each.

The retry count does not change the service’s permanent configuration; it applies only to the current invocation.

Examples

# Notify services tagged 'devops' OR 'admin'
apprise -t "Union Test" --config apprise.yml \
   --tag devops --tag admin

# Notify services tagged with BOTH 'devops' AND 'critical'
apprise -t "Intersection Test" --config apprise.yml \
   --tag "devops,critical"

# Notify only priority-2 'alerts' services
apprise -t "High Alert" --config apprise.yml \
   --tag "2:alerts"

# Notify all 'alerts' services with up to 3 retries on failure
apprise -t "Critical Event" --config apprise.yml \
   --tag "alerts:3"

# Notify only priority-2 'alerts' services with up to 3 retries
apprise -t "Critical Event" --config apprise.yml \
   --tag "2:alerts:3"

# Trigger a configuration stored under the key 'my-alerts' on a local
# Apprise API server using the key 'my-alerts'
apprise -t "Job Finished" \
    "apprise://localhost:8000/my-alerts"

# Trigger a secure remote instance, targeting only the 'devops' tag
apprise -t "Production Issue" \
    --tag devops \
    "apprises://apprise.example.com/234-3242-23-2111-34"

Formatting & Emojis

Input Formats

By default, Apprise treats the body as plain text. You can change this using --input-format.

# Send a Markdown formatted message
apprise -t "Build Status" -b "**Success**: The build passed!" \
    --input-format markdown \
    "discord://..."

Emoji Support

Use --interpret-emojis (-j) to convert emoji shortcodes into actual emojis.

apprise \
  --title "Server Status" \
  --body "The server is on :fire:. Please send help :ambulance:." \
  --interpret-emojis \
  "slack://..."

Escape Sequences

Use --interpret-escapes (-e) when you want \n sequences in your body to become real newlines.

apprise \
  --title "Multi-line" \
  --body "Line 1\\nLine 2\\nLine 3" \
  --interpret-escapes \
  "discord://..."

Using Apprise API

If you are running a self-hosted Apprise API instance, you can use the CLI to trigger it using the apprise:// schema. This allows you to centralize your configuration on the server and keep your local clients simple.

The plugin uses version 2 by default. It sends the configuration key in X-Apprise-Config-ID, keeping it out of the HTTP request path. Add ?v=1 when connecting to an older Apprise API server that requires /notify/{KEY}.

Syntax

• Insecure (HTTP): apprise://hostname/config_key
• Secure (HTTPS): apprises://hostname/config_key

Examples:

No Authentication

# Trigger a configuration stored under the key 'my-alerts' on a local server
apprise -t "Job Finished" \
    "apprise://localhost:8000/my-alerts"

# Trigger a secure remote instance, targeting only the 'devops' tag
apprise -t "Production Issue" \
    --tag devops \
    "apprises://apprise.example.com/production-key"

With Authentication

# Credentials in the URL are sent using Basic Auth.
apprise -t "Job Finished" \
    "apprises://user:password@apprise.example.com/my-alerts"

# A password-only administrator login leaves the username blank.
apprise -t "Job Finished" \
    "apprises://:password@apprise.example.com/my-alerts"

Scripting & Piping

The CLI is designed to work seamlessly with standard system pipes and scripts.

Multi-Line Input

If you omit --body, Apprise reads from stdin.

cat << '_EOF' | apprise --title "Database Status" \
    --notification-type success "discord://..."
Backup started: 10:00 AM
Backup finished: 10:05 AM
Status: SUCCESS
_EOF

Piping from Files

Redirect the contents of a file directly into the message body.

cat ~/notes.txt | apprise --title "Daily Notes" \
   "mailto://user:pass@example.com"

Using Variables

If you have a multi-line variable in your script, wrap it in quotes to preserve newlines.

MULTILINE_VAR="""
This variable has been defined
with multiple lines in it.
"""

apprise --title "Variable Example" \
   --body "$MULTILINE_VAR" \
   "gotify://localhost"

Persistent Storage

Persistent storage writes to the following location by default, unless APPRISE_STORAGE_PATH or --storage-path overrides it:

• ~/.local/share/apprise/cache

Apprise can cache certain lookups and authentication details on disk to reduce repeated API calls. This is enabled by default for the CLI (mode auto).

To interact with storage, use the storage subcommand:

apprise storage

For the full explanation (UIDs, cache locations, screenshots, and cleanup workflows), see Persistent Storage.

Exit Status

The Apprise CLI exits with:

• 0 if every notified service succeeded.
• 1 if every notified service failed, or the notification could not start.
• 2 if there was a command line error (for example, invalid arguments).
• 3 if one or more service URLs were successfully loaded, but none could be notified due to user filtering (tags).
• 4 if some services sent successfully and at least one other did not.
• 5 if no service sent successfully, but the only problem was that one or more services ran out of time (see Timeouts above).

Integrations

Tmux Alert Bell

You can link the tmux alert-bell hook to Apprise to get notifications when long-running commands complete.

# 1. Set your tmux bell-action to 'other'
set-option -g bell-action other

# 2. Trigger Apprise on 'alert-bell'
set-hook -g alert-bell 'run-shell "\
  apprise \
    --title \"Tmux notification on #{host}\" \
    --body \"Session #{session_name} window #{window_index}:#{window_name}\" \
    --notification-type info \
    discord://webhook_id/webhook_token"'