Skip to content

fix(cli): show the command list in clickclack help, -h and --help - #319

Merged
steipete merged 1 commit into
openclaw:mainfrom
KrasimirKralev:fix/cli-help-lists-commands
Nov 14, 2026
Merged

steipete merged 1 commit into
openclaw:mainfrom
KrasimirKralev:fix/cli-help-lists-commands

Conversation

@KrasimirKralev

Copy link
Copy Markdown
Contributor

What Problem This Solves

Fixes: clickclack --help (and -h) prints only the client flag set, with no list of commands, and clickclack help fails with unknown command "help".

  • A new user or an agent driving the binary has no way to discover serve, migrate, admin, login, messages list and the rest from the binary itself; the command list only exists in docs/cli.md.
  • Scope boundary: no command, flag, default or exit code changes. Subcommand help (serve --help, admin bootstrap --help) and the bad-flag path are untouched; --bogus still exits 2 as before.

User Impact

User impact: clickclack help, clickclack -h and clickclack --help now print the same command list docs/cli.md documents, followed by the client flags, and exit 0. docs/agent-friendly-cli.md already promises that "-h and --help always show help".

Why This Change Was Made

The root client flag set had no Usage function, so Go's default printed Usage of clickclack: plus the flags, and the client dispatcher had no help case. The fix sets one printUsage on that flag set (command block + PrintDefaults) and routes help to it. Help goes to stderr, like every other -h in this binary (Go's flag default). docs/cli.md gains the two commands its block was missing (version, help) and one sentence naming the help entry points; the CHANGELOG has one line under ## Unreleased. A regression test in apps/api/cmd/clickclack/client_config_test.go drives runArgs with help (fails on main with unknown command "help", passes here).

Evidence

  • Behavior or issue addressed: the root clickclack help shows no commands; clickclack help is rejected.
  • Real environment tested: Ubuntu 26.04.1, Go 1.27.3, binary built from upstream/main f7e3ad1 and from this branch with go build -o <scratch>/clickclack ./cmd/clickclack, isolated XDG_CONFIG_HOME.
  • Exact steps or command run after this patch: ./clickclack help, ./clickclack --help, ./clickclack -h, ./clickclack --bogus, each on the main build and on the branch build.
  • Evidence after fix:
# main (f7e3ad18)
$ ./clickclack --help
Usage of clickclack:
  -channel string
    	channel id or name
  -json
    	emit JSON
  ... (only the 10 client flags, no commands)
$ ./clickclack help
2026/11/05 17:10:57 unknown command "help"

# this branch
$ ./clickclack help
Usage: clickclack <command> [flags]

Commands:
  serve      run the HTTP/WebSocket server (default if no command given)
  migrate    apply embedded SQL migrations
  admin      bootstrap, FakeCo seed, user create, member add, invite create, bot create, events prune, magic-link create, webpush keygen
  backup     write a SQLite backup file
  export     write a JSON dump to a file or stdout
  version    print the binary version
  help       show this help
  login      consume a magic-link token and store/print a session token
  logout     revoke the stored session and remove stored client credentials
  whoami     print the current server-side user
  status     print selected server/user/workspace/channel
  canary     prove a human ClickClack -> OpenClaw -> quoted bot reply round trip
  workspaces list
  channels list
  send
  messages send
  messages list
  threads open
  threads reply
  reactions add
  reactions remove

Client flags (before the command or on the command itself):
  -channel string
    	channel id or name
  ... (same 10 flags as before)
exit=0
$ ./clickclack --help    -> same output, exit=0
$ ./clickclack -h        -> exit=0
$ ./clickclack --bogus   -> exit=2 (main: exit=2)
  • Observed result after fix: running the built clickclack binary, help, -h and --help print the command list and the client flags and exit 0; on main help exits with unknown command "help". An unknown flag still exits 2 on both builds. In apps/api, gofmt -l and go vet ./cmd/clickclack/ are clean and go test ./... -count=1 passes.
  • What was not tested: Windows and macOS builds; subcommand help text was not changed and not re-checked beyond --bogus.
  • Proof limitations or environment constraints: none.

@KrasimirKralev
KrasimirKralev requested a review from a team as a code owner November 5, 2026 15:15
@clawsweeper

clawsweeper Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

@clawsweeper clawsweeper Bot added clawsweeper:intake:bug Preliminary submission classification; full source review pending. P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed clawsweeper:intake:bug Preliminary submission classification; full source review pending. labels Nov 5, 2026
@clawsweeper

clawsweeper Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge.

What this changes

Adds a command list to clickclack help, -h, and --help, with matching documentation and regression coverage.

Example: A user runs clickclack help.

  • Before: The binary reports unknown command "help".
  • After: The binary prints commands and client flags to stderr and exits 0.

Review scores

Measure Result What it means
Overall readiness 🦞 diamond lobster (5/6) A focused, useful fix with shipped-entry-point terminal evidence and no actionable findings.
Proof confidence 🦞 diamond lobster (5/6) Sufficient (terminal): The supplied Ubuntu transcript exercises built main and branch CLI binaries through help, --help, -h, and an unknown flag, showing command-list output and the expected exit results.
Patch quality 🦞 diamond lobster (5/6) No actionable review findings were identified.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Complete
User problem: Users cannot discover available commands from root help, and the conventional help command fails.
Reason: The change makes the existing command surface discoverable using conventional CLI entry points at low implementation cost.

Merge readiness

✅ Ready for maintainer review

This PR fixes a current CLI discoverability gap with a focused change; no actionable correctness or security findings remain.

Priority: P2
Reviewed head: 2308e640926ad0af61f2773ba30dcdb074c3c33c

Before merge

None.

Findings

None.

Agent review details

How this fits together

The Go binary dispatches server commands directly and sends client commands and root help flags through the client flag parser, which produces terminal help.

flowchart TD
  A[CLI arguments] --> B[Root dispatcher]
  B --> C[Server commands]
  B --> D[Client flag parser]
  D --> E[Shared usage printer]
  D --> F[Client commands]
  E --> G[Terminal stderr]
Loading

Technical review

Best possible solution:

Land the shared usage printer and help dispatch with the accompanying regression test and documentation.

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

Current-main dispatch and flag setup establish both reported paths, corroborated by the contributor's before-and-after binary transcript; no target code was run during this review.

Is this the best way to solve the issue?

The existing flag parser owns the fix, and one usage printer handles both flag help and the help command without adding another dispatch layer.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against f7e3ad188c81.

Provenance checked

  • Root client flag parsing and command dispatch keeps the original intent (a9f86a2: The original agent-friendly client established shared flags and command dispatch; adding discoverable help supports that design.)
  • CLI command documentation keeps the original intent (b925723: The CLI guide documents the implemented command surface; the new terminal list follows that surface and documents the added help entry point.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

  • Current main still needs the fix: The default branch remains f7e3ad1; its client parser has no custom Usage function or help command case. (apps/api/cmd/clickclack/client.go:56, f7e3ad188c81)
  • One help implementation: The introduced diff connects flag help and the help command to the same printer, retaining PrintDefaults and existing flag definitions. (apps/api/cmd/clickclack/client.go:58, 2308e640926a)
  • Shipped CLI evidence: The full PR body supplies Ubuntu terminal output from main and branch binaries: help lists commands after the fix, all three help forms exit 0, and an unknown flag retains exit 2. Discussion contains only automation status comments and no substantive review. (2308e640926a)
  • Feature history: Scoped history and blame identify Peter Steinberger's original client implementation and subsequent CLI repairs by Krasimir Kralev; GitHub verifies both identities. Reading the creation commit's full local diff encountered an unavailable historical object, while current and base blobs were readable. (apps/api/cmd/clickclack/client.go:53, a9f86a21f24c)
  • Applicable policy: The complete root AGENTS.md requires sqlc for SQL changes; this PR changes no SQL. No nested AGENTS.md, maintainer notes, or pr-simplify skill exists in the checkout. (AGENTS.md:3, 2308e640926a)

Likely related people:

  • Peter Steinberger: Raw commit a9f86a2 adds apps/api/cmd/clickclack/client.go:55 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: a9f86a21f24c; files: apps/api/cmd/clickclack/client.go)
  • Krasimir Kralev: Raw commit 66bdc67 adds apps/api/cmd/clickclack/client.go:117 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 66bdc67d6eb6; files: apps/api/cmd/clickclack/client.go)

Preflight source

Source unknown. Source comparison at the observed PR snapshot only. Completion is self-reported; body, policy, tests, execution, and report bytes are not verified.

Labels

Label changes:

  • add P2: Command discovery is impaired, but documented commands remain usable and the runtime is unaffected.
  • add proof: sufficient: Contributor real behavior proof is sufficient.
  • add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

  • P2: Command discovery is impaired, but documented commands remain usable and the runtime is unaffected.
  • rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.
  • proof: sufficient: Contributor real behavior proof is sufficient.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed November 5, 2026, 10:29 AM ET / 15:29 UTC.

@KrasimirKralev
KrasimirKralev force-pushed the fix/cli-help-lists-commands branch from 2308e64 to 11403ed Compare November 6, 2026 11:37

@steipete steipete left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the help dispatch, regression test, and documentation; exact-head CI is green.

@steipete
steipete merged commit 1f1b177 into openclaw:main Nov 14, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants