fix(cli): stop root --help listing per-command flags as global

[liangshuo-1]

Problem

lark-cli --help printed two flag lists that contradict each other. The hand-written FLAGS: block listed a dozen flags (--params, --data, --format, --page-all, --jq, -o, …) as if they were global — but none are registered on the root command. They all error at the top level and exist only on the leaf commands (api, service):

$ lark-cli --params '{}'
Error: unknown flag: --params

Cobra's own Flags: section, rendered right below, lists the real root flags — only -h/--help, --profile, -v/--version. The static block also flattened away the fact that the flag set varies by command (e.g. contact +search-user has --page-size but no --page-all/--page-limit/--page-delay) and hand-restated defaults that have to be kept in sync manually.

Fix

Before (excerpt — 12 entries, each with description + defaults):

FLAGS:
    --params <json>       URL/query parameters JSON
    --data <json>         request body JSON (POST/PATCH/PUT/DELETE)
    --format <fmt>        output format: json (default) | ndjson | table | csv | pretty
    --page-limit <N>      max pages to fetch with --page-all (default: 10, 0 for unlimited)
    ... 8 more ...

After:

FLAGS:
    e.g. --as, --format, -q/--jq, --dry-run ...
    Run lark-cli <command> --help for the full list.

A short illustrative example list — the cross-cutting flags that work on any command, with ... signalling it is not exhaustive — plus a pointer to the authoritative per-command source. Root help stays a discovery signpost without claiming the flags are global or restating defaults/descriptions that drift from the real flag sets. USAGE:/EXAMPLES: still show the flags in their correct position, after a <command>.

Tests

• go test ./cmd/ -run TestRootLong passes.
• New TestRootLong_FlagsSectionPointsToCommandHelp guards against reverting to a standalone exhaustive root flag table (asserts the section points to lark-cli <command> --help).

Summary by CodeRabbit

• Documentation
  • Updated main help text to streamline information and direct users to command-specific help for complete flag details.
• Tests
  • Added test to verify that help text appropriately points to per-command flag documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

Replace the long embedded FLAGS: section in the rootLong help text with a short note that most flags are per-command and point users to "lark-cli --help"; add a unit test to assert that phrasing is present.

Changes

Help Text and Test

Layer / File(s)	Summary
Update rootLong help text cmd/root.go	Removed the detailed FLAGS: block and replaced it with a brief statement that most flags are per-command and that lark-cli <command> --help contains the authoritative list.
Add unit test for help phrasing cmd/root_test.go	Added TestRootLong_FlagsSectionPointsToCommandHelp to assert rootLong includes the lark-cli <command> --help pointer for the FLAGS section.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• larksuite/cli#299: Both PRs modify the rootLong help text in cmd/root.go—one removes the embedded global FLAGS: section, while the other updates the calendar command example shown in lark-cli --help.
• larksuite/cli#769: Both PRs modify the cmd/root.go root long help text (rootLong)—one changes the FLAGS section to point users to <command> --help, the other adjusts the --as flag wording/default shown in the same help output.

Suggested labels

bug

Poem

🐰 I nudged the help text, trimmed the bulky parts,
Pointed each flag to its command's charts,
A tiny test hops in to check the line,
Now help is tidy and the output's fine,
Carrots for clarity, and a doc that shines.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: removing a misleading FLAGS section from root help that incorrectly listed per-command flags as global options.
Description check	✅ Passed	The description thoroughly explains the problem, solution, and testing approach. It covers all key sections: Problem statement with examples, Fix with before/after comparison, and Tests verifying the change.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/root-help-flags-drift

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@5428ba7843cbb63cd5d31b17bddc4fc46ef696ee

🧩 Skill update

npx skills add larksuite/cli#fix/root-help-flags-drift -y -g

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 69.19%. Comparing base (0aa9e96) to head (5428ba7).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1223   +/-   ##
=======================================
  Coverage   69.19%   69.19%           
=======================================
  Files         634      634           
  Lines       59482    59482           
=======================================
  Hits        41161    41161           
  Misses      15007    15007           
  Partials     3314     3314           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

🧹 Nitpick comments (1)

cmd/root_test.go (1)

86-98: ⚡ Quick win

Also assert the legacy static FLAGS: block is gone.

This only checks the new pointer text. If someone reintroduces the old hand-written FLAGS: section alongside it, the test still passes and the original drift comes back. A negative assertion on the legacy FLAGS: header would pin the actual regression this PR is fixing.

Suggested test tightening

 func TestRootLong_FlagsSectionIsPerCommandPointer(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 must point to `<command> --help` and explicitly say
 	// the flags are per-command, rather than re-list them as if they were
 	// global (which both lies and silently drifts as flags/defaults change).
 	if !strings.Contains(rootLong, "per-command") {
 		t.Fatalf("root help FLAGS section must say flags are per-command, got:\n%s", rootLong)
 	}
 	if !strings.Contains(rootLong, "lark-cli <command> --help") {
 		t.Fatalf("root help FLAGS section must point to `<command> --help` for the authoritative flag list, got:\n%s", rootLong)
 	}
+	if strings.Contains(rootLong, "\nFLAGS:\n") {
+		t.Fatalf("root help must not carry a static FLAGS block anymore, got:\n%s", rootLong)
+	}
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cmd/root_test.go` around lines 86 - 98, The test
TestRootLong_FlagsSectionIsPerCommandPointer only asserts the presence of the
new pointer text but not the absence of the legacy static header; update the
test to also assert that rootLong does NOT contain the legacy "FLAGS:" block by
adding a negative check (using strings.Contains on rootLong and failing with
t.Fatalf) to ensure the old hard-coded "FLAGS:" header is gone alongside the new
pointer checks.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@cmd/root_test.go`:
- Around line 86-98: The test TestRootLong_FlagsSectionIsPerCommandPointer only
asserts the presence of the new pointer text but not the absence of the legacy
static header; update the test to also assert that rootLong does NOT contain the
legacy "FLAGS:" block by adding a negative check (using strings.Contains on
rootLong and failing with t.Fatalf) to ensure the old hard-coded "FLAGS:" header
is gone alongside the new pointer checks.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f82afb6e-5d1f-4f08-948b-454097a868fc

📥 Commits

Reviewing files that changed from the base of the PR and between d991ee4 and 50b10c3.

📒 Files selected for processing (2)

• cmd/root.go
• cmd/root_test.go

🚧 Files skipped from review as they are similar to previous changes (1)

• cmd/root.go

[coderabbitai]

🧹 Nitpick comments (1)

cmd/root_test.go (1)

86-95: ⚡ Quick win

Also assert the stale root-only flag table is gone.

This only checks that the new pointer text exists. It would still pass if rootLong kept the old misleading FLAGS: cheat-sheet and merely appended the pointer, which is the regression this PR is trying to prevent. Add at least one negative assertion for a representative old entry (for example --page-all or --dry-run) or for the old exhaustive block header so the test pins the removal as well as the replacement.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cmd/root_test.go` around lines 86 - 95, Update the
TestRootLong_FlagsSectionPointsToCommandHelp test to also assert that the stale
root-only flag table is gone: in addition to checking that rootLong contains the
pointer "lark-cli <command> --help", add a negative assertion that rootLong does
NOT contain a representative old entry or header (e.g., the string "--page-all"
or the old "FLAGS:" exhaustive block header or "--dry-run") so the test fails if
the old cheat-sheet remains; locate the test function
TestRootLong_FlagsSectionPointsToCommandHelp and add the negative contains check
against the rootLong variable.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@cmd/root_test.go`:
- Around line 86-95: Update the TestRootLong_FlagsSectionPointsToCommandHelp
test to also assert that the stale root-only flag table is gone: in addition to
checking that rootLong contains the pointer "lark-cli <command> --help", add a
negative assertion that rootLong does NOT contain a representative old entry or
header (e.g., the string "--page-all" or the old "FLAGS:" exhaustive block
header or "--dry-run") so the test fails if the old cheat-sheet remains; locate
the test function TestRootLong_FlagsSectionPointsToCommandHelp and add the
negative contains check against the rootLong variable.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 87a60535-ac03-4712-aa71-f859ca284756

📥 Commits

Reviewing files that changed from the base of the PR and between 50b10c3 and 5428ba7.

📒 Files selected for processing (2)

• cmd/root.go
• cmd/root_test.go

✅ Files skipped from review due to trivial changes (1)

• cmd/root.go