From b0b163d0ef108635c00664853fd8024281a1a893 Mon Sep 17 00:00:00 2001
From: liangshuo-1 <liangshuo.0@bytedance.com>
Date: Tue, 2 Jun 2026 20:11:20 +0800
Subject: [PATCH] fix(cli): stop root --help listing per-command flags as
 global (#1223)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hand-written FLAGS block in `lark-cli --help` listed --params, --data,
--as, --format, --page-all, --page-size, --page-limit, --page-delay, -o,
--jq, -q and --dry-run as if they were global flags. None are registered
on the root command — they all error "unknown flag" at the top level and
exist only on leaf commands (api, service). The block also contradicted
the Cobra-generated "Flags:" section rendered directly below it, which
shows only -h/--help, --profile, -v/--version.

Replace it with a short illustrative example list (common flags first) and
a pointer to `lark-cli <command> --help` for the full per-command set.
Root help stays a discovery signpost without claiming the flags are global
or restating defaults/descriptions that drift from the real flag sets.

Change-Id: Ia1cab889dd70b6b49a61dac468dedfd7fe39043f
---
 cmd/root.go      | 14 ++------------
 cmd/root_test.go | 11 +++++++++++
 2 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/cmd/root.go b/cmd/root.go
index e86ff069..31a97728 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -49,18 +49,8 @@ EXAMPLES:
     lark-cli api GET /open-apis/calendar/v4/calendars
 
 FLAGS:
-    --params <json>       URL/query parameters JSON
-    --data <json>         request body JSON (POST/PATCH/PUT/DELETE)
-    --as <type>           identity type: user | bot
-    --format <fmt>        output format: json (default) | ndjson | table | csv | pretty
-    --page-all            automatically paginate through all pages
-    --page-size <N>       page size (0 = use API default)
-    --page-limit <N>      max pages to fetch with --page-all (default: 10, 0 for unlimited)
-    --page-delay <MS>     delay in ms between pages (default: 200, only with --page-all)
-    -o, --output <path>   output file path for binary responses
-    --jq <expr>           jq expression to filter JSON output
-    -q <expr>             shorthand for --jq
-    --dry-run             print request without executing
+    e.g. --as, --format, -q/--jq, --dry-run ...
+    Run lark-cli <command> --help for the full list.
 
 AI AGENT SKILLS:
     lark-cli pairs with AI agent skills (Claude Code, etc.) that
diff --git a/cmd/root_test.go b/cmd/root_test.go
index 3ab78ceb..ff1e3837 100644
--- a/cmd/root_test.go
+++ b/cmd/root_test.go
@@ -83,6 +83,17 @@ func TestRootLong_AgentSkillsLinkTargetsReadmeSection(t *testing.T) {
 	}
 }
 
+func TestRootLong_FlagsSectionPointsToCommandHelp(t *testing.T) {
+	// The flags shown in root help live on leaf commands (api, service), not
+	// on the root command — every one errors "unknown flag" at the top level.
+	// So the FLAGS section may only list them as examples and must route to
+	// `<command> --help` for the full set, rather than re-list them as if they
+	// were global root flags (which both lies and drifts as flags change).
+	if !strings.Contains(rootLong, "lark-cli <command> --help") {
+		t.Fatalf("root help FLAGS section must point to `lark-cli <command> --help` for the flag list, got:\n%s", rootLong)
+	}
+}
+
 func TestConfigureFlagCompletions(t *testing.T) {
 	t.Cleanup(func() { cmdutil.SetFlagCompletionsEnabled(false) })