Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command line

mercurio --help:

Apprise-compatible Rust library, CLI and HTTP server to send notifications to 150+ services via a single URL.

Usage: mercurio [OPTIONS] [URL]... [COMMAND]

Commands:
  services  List the supported services
  check     Validate URLs or configuration; send nothing
  serve     Run the HTTP notification server
  storage   Show (`list`) or clean (`prune`, `clear`) the persistent storage

Arguments:
  [URL]...  Notification URLs

Options:
  -b, --body <TEXT>                Message body [default: read stdin]
  -t, --title <TEXT>               Message title
  -n, --notification-type <TYPE>   `info`, `success`, `warning` or `failure` [default: info]
  -i, --input-format <FORMAT>      Markup of the body: `text`, `html` or `markdown`
  -a, --attach <PATH|URL>          Attach a file: path, `file://`, `http(s)://` or `memory://` (repeatable)
  -c, --config <PATH|URL>          Load a TEXT or YAML configuration (repeatable)
  -g, --tag <TAG>                  Notify services tagged TAG; `a,b` needs both, repeat for either, `all` notifies everything
      --template-var <NAME=VALUE>  Value for `${NAME}` in a YAML configuration (`-tv`, repeatable)
  -R, --recursion-depth <N>        Configuration `include` levels to follow [default: 1]
  -e, --interpret-escapes          Turn `\n`, `\r`, `\t` and `\\` in the title and body into the characters
  -T, --theme <THEME>              Image theme, the `{THEME}` of image URLs [default: default]
  -j, --interpret-emojis           Replace `:shortcode:` emoji in the title and body (a URL's `?emojis=no` still wins)
  -d, --dry-run                    Show what would be notified; send nothing
      --disable-async              Notify services one after another (`-Da`)
  -S, --storage-path <PATH>        Persistent storage directory [env: APPRISE_STORAGE_PATH=] [default: ~/.local/share/mercurio/cache]
      --storage-prune-days <N>     `storage prune` removes files older than N days (`-SPD`) [env: APPRISE_STORAGE_PRUNE_DAYS=] [default: 30]
      --storage-uid-length <N>     Characters of the URL ids naming persistent storage, at least 2 (`-SUL`) [env: APPRISE_STORAGE_UID_LENGTH=] [default: 8]
      --storage-mode <MODE>        When persistent storage is written: `auto` (after each send), `flush` (also before each step) or `memory` (never) (`-SM`) [default: auto]
  -l, --details                    Same as `mercurio services`
      --json                       With `services`: print JSON
      --bind <ADDR>                With `serve`: address to listen on [default: 127.0.0.1:8000]
  -v, --verbose...                 More log output on stderr (repeat for more)
  -h, --help                       Print help
  -V, --version                    Print version

Environment:
  APPRISE_URLS               URLs to notify when none are given and there is no -c
  APPRISE_CONFIG_PATH        configuration files instead of the defaults (separated by ; or newlines)
  APPRISE_TEMPLATE_<NAME>    value for ${NAME} when -tv and the configuration give none

Exit codes:
  0  every selected service was notified (or -d, check, services, storage succeeded)
  1  every selected service failed, or a source, attachment or stdin could not be read
  2  usage error, or no URLs given or configured
  3  services were loaded but none matched the tags (-g)
  4  some services were notified and some failed

Default configuration files (.yaml instead of .conf for YAML):
  ~/.config/apprise/apprise.conf
  /etc/apprise/apprise.conf

The short flags are the usual ones for notification tools: -t title, -b body, -n type, -c configuration, -g tag. Compatibility notes are in the README.

Sending

mercurio -t "Backup" -b "Finished in 42s" ntfy://my-topic "discord://ID/TOKEN"
echo "disk 91% full" | mercurio -n warning tgram://BOT_TOKEN/CHAT_ID
mercurio -c ~/alerts.yml -g devops -b "deploy done"
  • Without -b, the body is read from standard input until end of file. A dry run (-d) does not read it.
  • The title is optional. Services without a title field get it merged into the body (see Messages).
  • All matching services are notified concurrently. -Da sends one after another.
  • A word send before the URLs is accepted and ignored (mercurio send -b hi ntfy://topic).

Verbosity

Without -v only errors are printed; -v adds warnings (skipped configuration entries, retries), -vv informational messages, -vvv debug and -vvvv trace output. Log lines look like WARNING - ....

Where services come from

The first of these sources that gives anything is used; the rest are ignored:

  1. URLs on the command line. When -c is also given, the URLs win and a warning is logged (visible with -v).
  2. -c / --config files and URLs.
  3. $APPRISE_URLS: URLs separated by commas or whitespace.
  4. The default configuration files. Every one that exists is loaded.

Put a user configuration in ~/.config/apprise/apprise.conf and a system-wide one in /etc/apprise/apprise.conf (.yaml for YAML), the locations --help shows. For compatibility with older Apprise setups, every one of these is read, in this order ({a,b} is each of a and b, the empty entry meaning no extension):

~/.apprise{,.conf,.yml,.yaml}
~/.config/apprise{,.conf,.yml,.yaml}
~/.apprise/apprise{,.conf,.yml,.yaml}
~/.config/apprise/apprise{,.conf,.yml,.yaml}
/etc/apprise{,.yml,.yaml}
/etc/apprise/apprise{,.conf,.yml,.yaml}

On Windows they are Apprise\apprise{,.conf,.yml,.yaml} under %APPDATA%, %LOCALAPPDATA%, %ALLUSERSPROFILE%, %PROGRAMFILES% and %COMMONPROGRAMFILES%.

Directories are skipped. $APPRISE_CONFIG_PATH replaces the whole list (paths separated by ; or newlines).

The format of each file (TEXT or YAML) is detected; see Configuration files.

Tags and dry run

-g selects configuration entries by tag (Tags); URLs given on the command line are always notified without -g. With -g they are filtered by their ?tag= values. -d loads every source, applies the tags and prints what would be notified, without sending or reading a body:

$ mercurio -c alerts.yml -g all -d
   1. json://localhost:9/...
      tags: devops
   2. ntfys://ntfy.sh/...
      tags: critical, devops
   3. gotify://${GOTIFY_HOST}/...
       uid: - template; unresolved, would not send -
      tags: home
  template: gotify_host (required)

1 of 3 matched entries could not be resolved and would not be sent.

Sending to an unresolved entry fails it; entries that fail to load are skipped with a warning (-v shows them). See Templates.

Output is redacted to the scheme and host. For services whose token sits in the host position (tgram://BOT_TOKEN/...) the token is printed; do not paste dry-run or storage output of such URLs in public places.

URL check

mercurio check parses every URL or configuration entry and prints one line per service (ok ntfy:// (ntfy), error: ...), without applying tags. Exit code 1 when any URL or configuration source is invalid.

Available services

mercurio services lists the services compiled into the binary:

$ mercurio services
46elks                             46elks:// elks://
800.com                            eight00com://
Africas Talking                    atalk://
...

--json prints details for each service.

Exit codes

The exit codes are listed at the end of --help above.

A URL that fails to parse is reported and skipped; the other URLs are still notified. The exit code only counts them. Use check first to catch typos.

Environment variables

The ones the command line reads are in --help above. APPRISE_CONFIG_DIR, APPRISE_STATELESS_URLS and APPRISE_RECURSION_MAX are for mercurio serve only, see HTTP server.