fix(cli): match apprise help and option errors (#62)

## What changed

- Render full Apprise-style CLI help for `--help` and `-h`.
- Suppress Go's default `flag` usage dump for unknown options.
- Emit Python Apprise-style unknown-option errors for unsupported flags.
- Add parity coverage for no-args, help, bad-option, and mixed
parse-error CLI workflows.
- Add built-binary E2E coverage to validate real process exit codes and
stdout/stderr wiring.
- Add regression coverage that older accepted flag forms still parse,
including legacy single-dash long aliases.
- Update the parse-error regression to compare Go against installed
Python Apprise for the exact same arguments instead of using
hand-written expected output.

## Why

The CLI request-spec parity tests covered notification behavior, but not
CLI help and parser output. As a result, `apprise-go` diverged from
Python Apprise: `--help` showed only the short usage banner, and invalid
flags dumped Go's full flag table.

The parser change should not break existing `apprise-go` users who were
relying on accepted Go flag spellings, so the PR also locks in
compatibility for those older forms. For mixed parser failures, the test
now uses the installed Python Apprise CLI as the source of truth.

## Validation

- Built and manually ran `/tmp/apprise-cli-parity` from `./cmd/apprise`:
  - `--version`
  - no arguments
  - `--help`
  - `--blah`
- legacy single-dash long aliases such as `-body`, `-title`,
`-notification-type`, `-input-format`, and `-version`
- `go test ./internal/cli -run TestCLIParseErrorsMatchPythonApprise
-count=1`
- `go test ./internal/cli`
- `go test ./...`
- Limetech CodeRabbit final check: `unresolved_coderabbit_threads 0`

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
  * Help flag now displays the full, user-friendly help text.

* **Bug Fixes**
* Unknown options produce a clear custom error message and proper exit
code; parse errors are reported consistently.

* **Tests**
* Added cross-implementation tests validating help, unknown-option
behavior, legacy flag parsing, and parse-error handling.

* **Chores**
* Updated internal run/notes document to reflect the new CLI parity run.

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/unraid/apprise-go/pull/62?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

#59

Author: elibosley

.codex/coderabbit-fixes-wip.md

@@ -3,10 +3,10 @@
 ## Context
 
 - Repo: unraid/apprise-go
-- Branch: codex/telegram-formatting-followup
-- PR: #60
-- PR URL: https://github.com/unraid/apprise-go/pull/60
-- Generated at: 2026-05-21T00:36:00-04:00
+- Branch: codex/cli-help-parity
+- PR: #62
+- PR URL: https://github.com/unraid/apprise-go/pull/62
+- Generated at: 2026-05-21T14:29:52Z
 
 ## Inputs Pulled
 
@@ -18,42 +18,19 @@
 
 | Item ID | Type | File | Line | Summary | Status | Link | Evidence |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| CR-001 | thread | internal/notify/format_convert_test.go | 168 | Add Python parity to the cross-target corpus test. | BLOCKED | https://github.com/unraid/apprise-go/pull/60#discussion_r3278534673 | Skipped: this corpus intentionally validates target format conversion behavior that fixes Telegram behavior beyond current Python Apprise. Adding Python request parity would lock in the upstream bug this PR is fixing. |
-| CR-002 | thread | internal/notify/telegram_format_test.go | 140 | Route new Telegram format tests through Python-vs-Go request-sequence parity. | BLOCKED | https://github.com/unraid/apprise-go/pull/60#discussion_r3278534678 | Skipped: these tests assert corrected Telegram parse payloads that current Python Apprise does not emit. |
-| CR-003 | thread | internal/notify/live/telegram_live_test.go | 101 | Add Python-apprise request parity to the live Telegram test. | BLOCKED | https://github.com/unraid/apprise-go/pull/60#discussion_r3278534680 | Skipped: live test purpose is Bot API acceptance of corrected Go-generated Telegram parse payloads, not matching upstream Python's currently broken formatting. |
-| CR-004 | thread | internal/notify/live/telegram_live_test.go | n/a | Require explicit destination for the live suite. | DONE | https://github.com/unraid/apprise-go/pull/60#discussion_r3278534682 | Addressed in `a3dd48f`; GraphQL reports thread resolved/outdated. |
-| RVW-001 | review-body | internal/notify/live/telegram_live_test.go | 140-149 | Redact bot token from live test transport error logs. | DONE | https://github.com/unraid/apprise-go/pull/60#pullrequestreview-4320292462 | Added redaction helper and regression test; targeted and full Go tests passed. |
+| CR-001 | thread | internal/cli/cli.go | 212 | Unknown-option detection is over-applied and can misclassify non-unknown parse errors. | DONE | https://github.com/unraid/apprise-go/pull/62#discussion_r3281866028 | `go test ./internal/cli` passed; exact `-R not-an-int --blah` behavior is now compared against Python Apprise. |
+| RVW-001 | review-body | top-level | n/a | Review body reports one actionable comment, represented by CR-001. | DONE | https://github.com/unraid/apprise-go/pull/62#pullrequestreview-4337724219 | No separate top-level actionable item beyond CR-001. |
 
 ## Execution Log
 
-### 1. Item: CR-004
-- Action: Required `APPRISE_GO_TELEGRAM_CHAT_ID` for live validation and removed auto-discovery/bot-ID fallback.
-- Validation: `go test ./internal/notify/live -run TestTelegramLiveFormattingAgainstBotAPI -count=1 -v` with explicit live env passed.
-- Result: DONE
-
-### 2. Item: CR-001
-- Action: Verified this asks for parity against Python Apprise behavior that does not include the corrected Telegram conversions under test.
-- Validation: Code/test review.
-- Result: BLOCKED; skipped because it conflicts with the bug fix goal.
-
-### 3. Item: CR-002
-- Action: Verified the requested parity would force the new Telegram unit tests back to current Python output.
-- Validation: Code/test review.
-- Result: BLOCKED; skipped because it conflicts with the bug fix goal.
-
-### 4. Item: CR-003
-- Action: Verified live validation is intentionally testing Bot API acceptance of Go-generated corrected payloads.
-- Validation: Code/test review.
-- Result: BLOCKED; skipped because Python parity is not the purpose of this live suite.
-
-### 5. Item: RVW-001
-- Action: Added token redaction before reporting request creation or transport errors.
-- Validation: `go test ./internal/notify/live -count=1`; `go test ./internal/notify ./internal/notify/live -run 'TestTelegram|TestTargetFormatConversionCorpusAcrossWorkflowTargets' -count=1`; live Bot API test with explicit env; `go test ./...`
+### 1. Item: CR-001
+- Action: Verified the exact installed Python Apprise behavior for `-R not-an-int --blah` and updated the regression test to compare Go against Python instead of asserting a hand-written expected result.
+- Validation: `go test ./internal/cli` passed.
 - Result: DONE
 
 ## Final Checks
 
 - [x] Queue reviewed: no `TODO` left
 - [x] Remaining `BLOCKED` items documented with reason
-- [ ] Re-pulled CodeRabbit threads and reviews
-- [ ] No unhandled top-level review-body comment remains
+- [x] Re-pulled CodeRabbit threads and reviews
+- [x] No unhandled top-level review-body comment remains

internal/cli/cli.go

@@ -18,6 +18,81 @@ const usageText = "" +
 	"   apprise [OPTIONS] [APPRISE_URL [APPRISE_URL2 [APPRISE_URL3]]]\n" +
 	"   apprise storage [OPTIONS] [ACTION] [UID1 [UID2 [UID3]]]\n"
 
+const helpText = usageText + `
+Send a notification to all of the specified servers identified by their URLs
+the content provided within the title, body and notification-type.
+
+For a list of all of the supported services and information on how to use
+them, check out https://github.com/caronc/apprise
+
+Options:
+  -b, --body TEXT                 Specify the message body. If no body is
+                                  specified then content is read from <stdin>.
+  -t, --title TEXT                Specify the message title. This field is
+                                  completely optional.
+  -P, --plugin-path PATH          Specify one or more plugin paths to scan.
+  -S, --storage-path PATH         Specify the path to the persistent storage
+                                  location
+                                  (default=~/.local/share/apprise/cache).
+  -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.
+  -SM, --storage-mode MODE        Specify the persistent storage operational
+                                  mode (default=auto). Possible values are:
+                                  "auto", "flush", "memory".
+  -c, --config CONFIG_URL         Specify one or more configuration locations.
+  -a, --attach ATTACHMENT_URL     Specify one or more attachments.
+  -n, --notification-type TYPE    Specify the message type (default=info).
+                                  Possible values are: "info", "success",
+                                  "warning", "failure".
+  -i, --input-format FORMAT       Specify the message input format
+                                  (default=text). Possible values are: "text",
+                                  "markdown", "html".
+  -T, --theme THEME               Specify the default theme.
+  -g, --tag TAG                   Specify one or more tags to filter which
+                                  services to notify. Use multiple --tag (-g)
+                                  entries to match ANY tag. Use comma
+                                  separators to require ALL tags (strict
+                                  match). Omit to notify untagged services
+                                  only, or use "all" to notify everything.
+  -Da, --disable-async            Send all notifications sequentially
+  -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.
+  -R, --recursion-depth INTEGER   The number of recursive import entries that
+                                  can be loaded from within Apprise
+                                  configuration. By default this is set to 1.
+  -v, --verbose                   Makes the operation more talkative. Use
+                                  multiple v to increase the verbosity. I.e.:
+                                  -vvvv
+  -e, --interpret-escapes         Enable interpretation of backslash escapes
+  -j, --interpret-emojis          Enable interpretation of :emoji: definitions
+  -D, --debug                     Debug mode
+  -V, --version                   Display the apprise version and exit.
+  -h, --help                      Show this message and exit.
+
+Actions:
+  storage             Access the persistent storage disk administration
+    list              List all URL IDs associated with detected URL(s). This
+                      is also the default action run if nothing is provided
+    prune             Eliminates stale entries found based on --storage-prune-
+                      days (-SPD)
+    clean             Removes any persistent data created by Apprise
+`
+
+const commandErrorUsage = "" +
+	"Usage: apprise [OPTIONS] SERVER_URL [SERVER_URL2 [SERVER_URL3]]\n" +
+	"Try 'apprise --help' for help.\n"
+
 type cliOptions struct {
 	body             string
 	title            string
@@ -75,7 +150,8 @@ func Run(args []string, stdout, stderr io.Writer) int {
 	opts := defaultCliOptions()
 	args = normalizeArgs(args)
 	fs := flag.NewFlagSet("apprise", flag.ContinueOnError)
-	fs.SetOutput(stderr)
+	fs.SetOutput(io.Discard)
+	fs.Usage = func() {}
 
 	fs.StringVar(&opts.body, "body", "", "Specify the message body.")
 	fs.StringVar(&opts.body, "b", "", "Specify the message body.")
@@ -127,16 +203,19 @@ func Run(args []string, stdout, stderr io.Writer) int {
 
 	if err := fs.Parse(args); err != nil {
 		if errors.Is(err, flag.ErrHelp) {
-			printUsage(stdout)
+			printHelp(stdout)
 			return 0
 		}
+		if option := unknownOption(args, fs); option != "" {
+			printUnknownOption(stderr, option)
+			return 2
+		}
 		fmt.Fprintln(stderr, err)
-		printUsage(stderr)
 		return 2
 	}
 
 	if opts.showHelp {
-		printUsage(stdout)
+		printHelp(stdout)
 		return 0
 	}
 
@@ -253,6 +332,15 @@ func printUsage(w io.Writer) {
 	fmt.Fprint(w, usageText)
 }
 
+func printHelp(w io.Writer) {
+	fmt.Fprint(w, helpText)
+}
+
+func printUnknownOption(w io.Writer, option string) {
+	fmt.Fprint(w, commandErrorUsage+"\n")
+	fmt.Fprintf(w, "Error: No such option '%s'.\n", option)
+}
+
 func defaultCliOptions() cliOptions {
 	return cliOptions{
 		notificationType: string(notify.NotifyInfo),
@@ -275,6 +363,27 @@ func envInt(name string, fallback int) int {
 	return fallback
 }
 
+func unknownOption(args []string, fs *flag.FlagSet) string {
+	for _, arg := range args {
+		if arg == "--" {
+			return ""
+		}
+		if arg == "-" || !strings.HasPrefix(arg, "-") {
+			continue
+		}
+
+		option := strings.SplitN(arg, "=", 2)[0]
+		name := strings.TrimLeft(option, "-")
+		if name == "" {
+			continue
+		}
+		if fs.Lookup(name) == nil {
+			return option
+		}
+	}
+	return ""
+}
+
 func normalizeArgs(args []string) []string {
 	normalized := []string{}
 	for _, arg := range args {