From dff96610cc867afde58275545a0dd915bb74e724 Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Sat, 2 May 2026 10:42:40 -0700
Subject: [PATCH] fix(cli): show tui help without opening the archive

---
 internal/cli/cli.go          |  3 +++
 internal/cli/cli_test.go     | 10 ++++++++++
 internal/cli/query_sync.go   |  9 +++++++++
 internal/cli/tui_commands.go | 29 +++++++++++++++++++----------
 4 files changed, 41 insertions(+), 10 deletions(-)

diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index 359bf83..76f4614 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -157,6 +157,9 @@ func (r *runtime) dispatch(rest []string) error {
 		autoShareUpdate := !hasBoolFlag(rest[1:], "--dm")
 		return r.withLocalStoreDefaultLocked(autoShareUpdate, autoShareUpdate, func() error { return r.runSearch(rest[1:]) })
 	case "tui":
+		if hasHelpArg(rest[1:]) {
+			return r.runTUI(rest[1:])
+		}
 		return r.withLocalStoreReadOnly(func() error { return r.runTUI(rest[1:]) })
 	case "messages":
 		if hasBoolFlag(rest[1:], "--sync") && !hasBoolFlag(rest[1:], "--dm") {
diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go
index 7df7fe8..a7afde3 100644
--- a/internal/cli/cli_test.go
+++ b/internal/cli/cli_test.go
@@ -155,6 +155,16 @@ func TestStatusSearchSQLAndListings(t *testing.T) {
 	require.Equal(t, before, after, "tui --json should not mutate the database")
 }
 
+func TestTUIHelpReturnsUsage(t *testing.T) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	require.NoError(t, Run(context.Background(), []string{"tui", "--help"}, &stdout, &stderr))
+	require.Contains(t, stdout.String(), "Usage of tui:")
+	require.Contains(t, stdout.String(), "-limit")
+	require.Empty(t, stderr.String())
+}
+
 func TestWiretapImportsDesktopDirectMessages(t *testing.T) {
 	ctx := context.Background()
 	dir := t.TempDir()
diff --git a/internal/cli/query_sync.go b/internal/cli/query_sync.go
index 8e01158..87f46ec 100644
--- a/internal/cli/query_sync.go
+++ b/internal/cli/query_sync.go
@@ -96,3 +96,12 @@ func hasBoolFlag(args []string, name string) bool {
 	}
 	return false
 }
+
+func hasHelpArg(args []string) bool {
+	for _, arg := range args {
+		if arg == "help" || arg == "--help" || arg == "-h" {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/cli/tui_commands.go b/internal/cli/tui_commands.go
index 52981bc..7b90681 100644
--- a/internal/cli/tui_commands.go
+++ b/internal/cli/tui_commands.go
@@ -3,7 +3,6 @@ package cli
 import (
 	"errors"
 	"flag"
-	"io"
 	"strings"
 
 	"github.com/vincentkoc/crawlkit/tui"
@@ -13,16 +12,26 @@ import (
 
 func (r *runtime) runTUI(args []string) error {
 	fs := flag.NewFlagSet("tui", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-	channel := fs.String("channel", "", "")
-	author := fs.String("author", "", "")
-	limit := fs.Int("limit", 200, "")
-	includeEmpty := fs.Bool("include-empty", false, "")
-	dm := fs.Bool("dm", false, "")
-	guildsFlag := fs.String("guilds", "", "")
-	guildFlag := fs.String("guild", "", "")
-	jsonOut := fs.Bool("json", false, "")
+	fs.SetOutput(r.stderr)
+	if hasHelpArg(args) {
+		fs.SetOutput(r.stdout)
+	}
+	channel := fs.String("channel", "", "channel id")
+	author := fs.String("author", "", "author/user id")
+	limit := fs.Int("limit", 200, "row limit")
+	includeEmpty := fs.Bool("include-empty", false, "include empty messages")
+	dm := fs.Bool("dm", false, "browse direct messages")
+	guildsFlag := fs.String("guilds", "", "comma-separated guild ids")
+	guildFlag := fs.String("guild", "", "guild id")
+	jsonOut := fs.Bool("json", false, "write browser rows as JSON")
+	if len(args) == 1 && args[0] == "help" {
+		fs.Usage()
+		return nil
+	}
 	if err := fs.Parse(args); err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			return nil
+		}
 		return usageErr(err)
 	}
 	if *jsonOut {