feat: point unknown-flag errors at the command's help

cmd/execute_test.go

@@ -370,6 +370,23 @@ func TestHelpJSONIncludesFlags(t *testing.T) {
 	}
 }
 
+// TestUnknownFlagPointsAtHelp asserts an unknown flag's error points at the
+// command's help, mirroring the unknown-command path (the raw stdlib message is
+// a dead end otherwise).
+func TestUnknownFlagPointsAtHelp(t *testing.T) {
+	t.Chdir(t.TempDir())
+	err := byName["status"].Run([]string{"--nope"})
+	if err == nil {
+		t.Fatal("unknown flag should error")
+	}
+	if !strings.Contains(err.Error(), `provided but not defined`) {
+		t.Errorf("expected the stdlib flag error, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), `run "st help status"`) {
+		t.Errorf("unknown-flag error should point at st help status: %v", err)
+	}
+}
+
 func TestSuggestCommand(t *testing.T) {
 	cases := []struct{ in, want string }{
 		{"creat", "create"},   // distance 1

cmd/util.go

@@ -133,10 +133,19 @@ func parseFlagSet(fs *flag.FlagSet, args []string) error {
 		fs.Usage = usage
 	}()
 	err := fs.Parse(args)
-	if errors.Is(err, flag.ErrHelp) && !jsonRequested(args) {
-		fs.SetOutput(os.Stdout)
-		fs.Usage = usage
-		fs.Usage()
+	if errors.Is(err, flag.ErrHelp) {
+		if !jsonRequested(args) {
+			fs.SetOutput(os.Stdout)
+			fs.Usage = usage
+			fs.Usage()
+		}
+		return err
+	}
+	if err != nil && fs.Name() != "" {
+		// An unknown/malformed flag otherwise dead-ends on the raw stdlib message;
+		// point at the command's help, like unknownCommandErr does for commands.
+		// %w preserves the sentinel chain and the "provided but not defined" text.
+		return fmt.Errorf("%w (run \"st help %s\" for usage)", err, fs.Name())
 	}
 	return err
 }