Improve `-h` help text (including sub-command help)

[0xdevalias]

Currently the help text is pretty sparse; it would be nice if it was more helpful:

⇒ discrawl -h               
discrawl archives Discord guild data into local SQLite.

Usage:
  discrawl [global flags] <command> [args]

Commands:
  metadata
  check-update
  version
  init
  sync
  tail
  tap
  cache-import
  wiretap
  search
  tui
  messages
  digest
  analytics
  dms
  mentions
  attachments
  embed
  sql
  members
  channels
  status
  diagnostics
  coverage
  failures
  remote
  whoami
  report
  doctor
  cloud
  subscribe-cloud

⇒ discrawl wiretap -h
flag: help requested

etc

[clawsweeper]

🦞✅
Implementation PR opened: #130
Status: The implementation PR passed the worker's edit, validation, review, publish, and post-flight gates.
Worker: https://github.com/openclaw/clawsweeper/actions/runs/29336372221

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed July 16, 2026, 1:42 AM ET / 05:42 UTC.

Summary
Current main still exhibits the reported help gap, and the open linked pull request specifically owns the implementation; the issue should remain open until that pull request is merged or closed.

Reproducibility: yes. there is a clear reproduction path: run discrawl wiretap -h on the reviewed main revision and observe flag: help requested; this review did not execute a live binary, so the status remains source-reproducible rather than reproduced.

Root-cause cluster
Relationship: canonical
Canonical: #127
Summary: This issue is the canonical report, and the open linked pull request is its candidate implementation rather than a duplicate report.

Members:

• fixed_by_candidate: cli: improve command help output #130 - The pull request explicitly closes this issue and implements the requested root, subcommand, and nested-command help behavior.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Next step
Do not queue a second fix because the cleanly mergeable open pull request already owns this issue; review, repair if needed, and land or close that candidate first.

Review details

Best possible solution:

Land a focused implementation that renders Kong-derived help before configuration, storage, keyring, update, or network initialization and covers root, subcommand, and nested-command help with regression tests.

Do we have a high-confidence way to reproduce the issue?

Yes, there is a clear reproduction path: run discrawl wiretap -h on the reviewed main revision and observe flag: help requested; this review did not execute a live binary, so the status remains source-reproducible rather than reproduced.

Is this the best way to solve the issue?

Yes in direction: deriving focused help from the existing Kong command model is narrower and more maintainable than maintaining a second command description system, provided early help handling preserves compatibility and avoids initialization side effects.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• The linked pull request currently carries a compatibility-risk label and is waiting on follow-up, so its implementation should be reviewed rather than assumed ready solely because it closes the issue.

Codex review notes: model internal, reasoning high; reviewed against 0dc6a87cad9a.

Label changes

Label justifications:

• P3: The issue is a bounded CLI usability improvement with no data-loss, availability, security, or core-workflow impact.
• impact:ux-friction: Sparse and failing command help makes CLI discovery unnecessarily confusing, although users can still operate the tool through documentation or known commands.

Evidence reviewed

What I checked:

• Concrete reproduction: The report provides a direct reproduction: discrawl wiretap -h returns flag: help requested instead of command help, while top-level help lists commands without descriptions. (0dc6a87cad9a)
• Current implementation surface: The CLI command model and help behavior are implemented under internal/cli; the linked branch is based directly on the reviewed current-main SHA and changes this surface to add the missing help behavior. (internal/cli/cli_kong.go, 0dc6a87cad9a)
• Open closing pull request: cli: improve command help output #130 remains open and cleanly mergeable, explicitly links this issue with closing syntax, and adds command descriptions, early help handling, and regression coverage. (internal/cli/cli_kong.go, 160c6f2c17c0)
• Release check: The latest release, v0.11.5, predates the linked implementation branch; no merged commit or released version currently resolves the reported behavior. (CHANGELOG.md, 6dbb9e2c5e8e)
• CLI history provenance: The relevant command parsing is part of the Kong-based CLI introduced and maintained through the repository's CLI refactors; recent adjacent CLI work includes version-command and lint maintenance. (internal/cli/cli_kong.go, b52eefaa400f)

Likely related people:

• Peter Steinberger: The repository history associates Peter Steinberger with the Kong CLI migration and broad recent maintenance of the command and release surfaces. (role: CLI feature owner and recent area contributor; confidence: medium; commits: b52eefaa400f; files: internal/cli/cli_kong.go, CHANGELOG.md)
• Vincent Koc: Recent merged history credits Vincent Koc for work on the version command and related CLI/release behavior, making him a useful secondary reviewer for command-help consistency. (role: recent adjacent CLI contributor; confidence: medium; commits: 562025b; files: internal/cli, CHANGELOG.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this issue: Improve -h help text (including sub-command help) This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.