diff --git a/Troubleshooting.md b/Troubleshooting.md index def9878..447e992 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -7,6 +7,7 @@ * [Too Much Data and Overflow Directive](#too-much-data-and-overflow-directive) * [Special Characters and URL Conflicts](#special-characters-and-url-conflicts) * [Formatting Issues](#formatting-issues) + * [Apprise URLs on Command Line Do Not Behave Correctly](#apprise-urls-on-command-line-do-not-behave-correctly) * [PyInstaller Support](#pyinstaller-support) * [General Exceptions and/or Messages](#general-exceptions-andor-messages) * [RuntimeError: asyncio.run() cannot be called from a running event loop @@ -20,7 +21,7 @@ The best thing you can do when troubleshooting problems with your notification i # In the below example, I am trying to figure out why my mailto:// line # isn't working: apprise -vvv -t "test title" -b "test body" \ - mailto://user:password@gmail.com + "mailto://user:password@gmail.com" ``` The output can help you pinpoint what is wrong with your URL. @@ -157,6 +158,33 @@ The thing with Apprise is it doesn't know what you're feeding it (the format the * Developers can use the `body_format` tag which is telling Apprise what the **INPUT source** is. If a Apprise knows this it can go ahead and make special accommodations for the services that are expecting another format. By default the `body_format` is `None` and no modifications to the data fed to Apprise is touched at all (it's just passed right through to the upstream provider). * End User can modify their URL to specify a `format=` which can be either `text`, `markdown`, or `html` which sets the **OUTPUT source**. Notification Plugins can use this information to accommodate the data it's being fed and behave differently to help accommodate your situation. +## Apprise URLs on Command Line Do Not Behave Correctly +If you are passing a URL on the Command Line Interface (CLI) of your Linux/Windows/Mac shell, it is important that you surround the URL with "quotes". URL's leverage the `&` character which delimits one parameter from another (e.g. `schema://config?parm=value&parm2=value`). + +The problem is that `&` characters are also interpreted by the CLI. The `&` causes the shell to execute everything defined before them into a background process. +```bash +As a result.... This URL would be very problematic without quotes: +apprise -vvv -b "Test Email" \ + mailtos://user:pass@example.com?mode=ssl&smtp=smtp.example.com&from=Chris +# ^ ^^ +# |--------------------------------------|| +# | | +# This is all that gets passed into Apprise | +# | +# This launches the first part into Apprise as a +# background task depending on the CLI handles the +# entries specified after here very differently +# +# This is VERY likely NOT what you expect/want to happen. + +# Instead the same URL could have been written like +apprise -vvv -b "Test Email" \ + "mailtos://user:pass@example.com?mode=ssl&smtp=smtp.example.com&from=Chris" +# |-------------------------------------------------------------------------| +# | +# This is all that gets passed into Apprise +``` + ## Scripting Multi-Line Input/Output with CLI If you're using the `apprise` tool from the command line, you may be trying to script it to send multiple lines. To acomplish this, there are a number of tweaks you can do with `bash`, `sh`, or `ksh` such as: Those who want to deliver multiple line output can use the CLI as follows: @@ -172,7 +200,7 @@ _EOF # Another way is to just redirect the contents of file straight back # into apprise: cat ~/notes.txt | apprise -vv -t "Multi-line cat STDIN Redirect Example 2" \ - email://user:pass@hotmail.com + "email://user:pass@hotmail.com" # You can also use pass content from a multi-line variable you # declared: @@ -182,7 +210,7 @@ with multiple lines in it." # Now send our variable straight into apprise: apprise -vv -t "Multi-line Variable Example" -b "$MULTILINE_VAR" \ - gotify://localhost + "gotify://localhost" # Note: to preserve the new lines, be sure to wrap your # variable in quotes (like example does above).