Skip to content

cli: improve command help output - #130

Merged
steipete merged 3 commits into
mainfrom
clawsweeper/issue-openclaw-discrawl-127
Jul 16, 2026
Merged

cli: improve command help output#130
steipete merged 3 commits into
mainfrom
clawsweeper/issue-openclaw-discrawl-127

Conversation

@clawsweeper

@clawsweeper clawsweeper Bot commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Summary

  • add concise descriptions to Discrawl's top-level command help
  • use the existing Kong command model for root, command, and nested-group help
  • handle -h, --help, and help <command> before loading config or touching SQLite, keyrings, snapshots, update checks, or the network
  • add regressions for wiretap help and nested command help

Validation

  • GOWORK=off go test ./internal/cli -count=1
  • GOWORK=off go test ./...

Release note

Discrawl CLI help now describes available commands and provides focused, side-effect-free help for commands and nested command groups.

Fixes #127

@clawsweeper clawsweeper Bot added clawsweeper Tracked by ClawSweeper automation clawsweeper:autogenerated PR created automatically by ClawSweeper clawsweeper:autofix Maintainer opted this PR into bounded ClawSweeper-reviewed autofix without merge labels Jul 14, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jul 14, 2026
Closed
@clawsweeper

clawsweeper Bot commented Jul 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

🦞🧹
ClawSweeper autofix is enabled.

  • Head: 160c6f2c17c0
  • Label: clawsweeper:autofix
  • Action: exact-head review queued (workflow sweep.yml, event repository_dispatch).
  • Flow: review this head, repair/rebase only if needed, then re-review the exact repaired head until no actionable findings remain.

This is fix-only; I will not merge this PR.

Re-review progress:

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. labels Jul 14, 2026
@clawsweeper

clawsweeper Bot commented Jul 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Codex review: needs changes before merge. Reviewed July 15, 2026, 3:20 AM ET / 07:20 UTC.

Summary
The branch replaces static CLI usage output with Kong-generated root, command, and nested-group help, moves help handling before runtime initialization, and expands CLI help regression coverage.

Reproducibility: yes. from source inspection: a command invocation containing -- followed by -h or --help is still scanned by hasHelpFlag(rest[1:]) and can be diverted to help. The path was not executed locally because the read-only shell sandbox failed before command execution.

Review metrics: 3 noteworthy metrics.

  • Patch size: 3 files, 188 additions, 59 deletions. The change is concentrated in CLI parsing, output generation, and regression tests.
  • Remaining blockers: 1 P2 finding. A single argument-parsing compatibility defect remains on the unchanged head.
  • Automated checks: 10 successful checks. The branch passes supplied automation, leaving delimiter semantics as the outstanding review concern.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #127
Summary: This PR is the explicit candidate implementation for the open CLI help-output issue.

Members:

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

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🌊 off-meta tidepool
Patch quality: 🦐 gold shrimp
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P2] Stop help scanning at -- and add focused regression coverage for literal post-delimiter -h and --help.

Risk before merge

  • [P1] Merging as written can change existing command semantics by treating literal -h or --help values after -- as a request for Discrawl help rather than command input.

Maintainer options:

  1. Honor the delimiter before merge (recommended)
    Limit help interception to arguments before the first -- and add a focused regression test for literal post-delimiter help flags.
  2. Pause the help interception change
    If delimiter-safe parsing cannot be added narrowly, retain the existing command dispatch behavior until the help design is revised.
Copy recommended automerge instruction 
@clawsweeper automerge

Special instructions:
Update CLI help detection to stop scanning at the first `--`, add regression coverage showing post-delimiter `-h` and `--help` reach the selected command, and run the focused and full Go test suites.

Next step before merge

  • [P2] The remaining blocker is a narrow mechanical parser-and-test repair on the existing branch, with no product or security decision required.

Security
Cleared: The supplied diff is limited to CLI parsing, help rendering, and tests, with no concrete security or supply-chain regression identified.

Review findings

  • [P2] Stop help scanning at the -- delimiter — internal/cli/cli.go:69
Review details

Best possible solution:

Keep the side-effect-free Kong help path, but stop help-flag scanning at the first -- and add regression coverage proving post-delimiter help-like values are dispatched normally.

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

Yes from source inspection: a command invocation containing -- followed by -h or --help is still scanned by hasHelpFlag(rest[1:]) and can be diverted to help. The path was not executed locally because the read-only shell sandbox failed before command execution.

Is this the best way to solve the issue?

No, not yet. Kong-generated early help is a maintainable direction, but the scanner must preserve standard -- delimiter semantics before the patch is safe to merge.

Full review comments:

  • [P2] Stop help scanning at the -- delimiter — internal/cli/cli.go:69
    Limit the new hasHelpFlag interception to arguments before the first --. As written, inputs such as a search query or other command argument containing literal -h or --help after the delimiter are diverted to help instead of reaching the command; add a regression covering both forms. This is the previously reported blocker and remains unchanged on the current head.
    Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: unclear because the file could not be read completely.

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

Label changes

Label justifications:

  • P3: This is low-risk CLI help ergonomics with a narrow compatibility defect rather than a broken core workflow.
  • merge-risk: 🚨 compatibility: The new pre-dispatch help scanner can reinterpret existing post-delimiter command arguments during an upgrade.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This is a ClawSweeper bot-authored repair PR, so the external-contributor real-behavior proof gate does not apply; the supplied automated checks are supplemental validation.
Evidence reviewed

Acceptance criteria:

  • [P1] GOWORK=off go test ./internal/cli -count=1.
  • [P1] GOWORK=off go test ./...

What I checked:

  • Prior finding remains applicable: The current head is still 160c6f2, the same SHA reviewed previously for the unresolved delimiter-scanning finding. (internal/cli/cli.go:69, 160c6f2c17c0)
  • Help interception scans the full command tail: The new Run path calls hasHelpFlag on rest[1:] without first limiting the scan to arguments before --, allowing help-like literal arguments after the delimiter to trigger help output. (internal/cli/cli.go:69, 160c6f2c17c0)
  • Regression coverage omits delimiter semantics: The added help tests cover root, command, wiretap, and nested-group help but do not verify that -h or --help after -- remains a command argument. (internal/cli/cli_test.go:4065, 160c6f2c17c0)
  • Automated validation is green: All supplied GitHub checks completed successfully, including test, lint, analyze, release-check, secrets scanning, and CodeQL; the delimiter defect is a semantic gap not caught by those checks. (160c6f2c17c0)
  • Linked canonical issue: The PR explicitly proposes to fix the still-open CLI help request at Improve -h help text (including sub-command help) #127. (160c6f2c17c0)

Likely related people:

  • joshka: The PR timeline explicitly routes this CLI help review toward joshka, but local git-history inspection was unavailable in this review environment, so the ownership signal remains tentative. (role: likely CLI area contributor; confidence: low; files: internal/cli/cli.go, internal/cli/cli_test.go, internal/cli/output.go)
  • steipete: The PR timeline explicitly routes the item toward steipete alongside the CLI-area candidate, but commit-level provenance could not be confirmed locally. (role: adjacent project owner; confidence: low; files: internal/cli/cli.go, internal/cli/output.go)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

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.
Review history (27 earlier review cycles; latest 8 shown)
  • reviewed 2026-07-14T23:57:35.616Z sha 160c6f2 :: needs changes before merge. :: [P2] Stop help interception at the -- delimiter
  • reviewed 2026-07-15T00:13:52.280Z sha 160c6f2 :: needs changes before merge. :: [P2] Stop help interception at the -- delimiter
  • reviewed 2026-07-15T00:39:41.249Z sha 160c6f2 :: needs changes before merge. :: [P2] Stop help interception at the -- delimiter
  • reviewed 2026-07-15T01:10:55.501Z sha 160c6f2 :: needs changes before merge. :: [P2] Stop help interception at the -- delimiter
  • reviewed 2026-07-15T02:24:10.426Z sha 160c6f2 :: needs changes before merge. :: [P2] Stop help interception at the -- delimiter
  • reviewed 2026-07-15T03:39:14.342Z sha 160c6f2 :: needs changes before merge. :: [P2] Stop help scanning at the -- delimiter
  • reviewed 2026-07-15T04:53:03.159Z sha 160c6f2 :: needs changes before merge. :: [P2] Stop help scanning at the -- delimiter
  • reviewed 2026-07-15T06:06:38.281Z sha 160c6f2 :: needs changes before merge. :: [P2] Stop help scanning at the -- delimiter

@clawsweeper clawsweeper Bot removed the clawsweeper:autofix Maintainer opted this PR into bounded ClawSweeper-reviewed autofix without merge label Jul 14, 2026
@clawsweeper

clawsweeper Bot commented Jul 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

🦞🔧
ClawSweeper picked up the repair feedback.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper marker: fix-required (finding=review-feedback sha=160c6f2c17c0ad3bd334bd1177f0ae9e8280f2a7)
Action: repair worker queued. Run: https://github.com/openclaw/clawsweeper/actions/runs/29379863362

I will update this PR branch, or open a safe credited replacement, if the repair worker finds a narrow fix.

Automerge progress:

  • 2026-07-15 00:41:40 UTC review requested repair 160c6f2c17c0 (structured ClawSweeper marker: fix-required (finding=review-feedback sha=160c6f...)

@clawsweeper clawsweeper Bot added rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. 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. labels Jul 14, 2026
@0xdevalias

0xdevalias commented Jul 15, 2026

Copy link
Copy Markdown

Rank-up moves:

  • [P2] Stop help scanning at -- and add focused regression coverage for literal post-delimiter -h and --help.

I definitely think that would be worth fixing.

@steipete

steipete commented Jul 16, 2026

Copy link
Copy Markdown
Collaborator

Maintainer verification on exact head 52e485545c740592dd541162324a01d127bfe3a1:

  • Current-main reproduction: built ./cmd/discrawl; root -h listed bare command names, while wiretap -h exited 2 with flag: help requested.
  • PR live proof: built the real binary and ran root, top-level, alias, and nested help under isolated HOME/XDG directories with no config. Root help included command descriptions; wiretap -h, sync --full --help, search term --help, analytics quiet --help, attachments fetch --help, remote login --endpoint https://example.invalid --help, cloud publish --help, and update --help all exited 0 with focused usage and no config, store, keyring, update, or network access.
  • Delimiter proof: version -- --help printed the version rather than help.
  • Focused test: GOWORK=off go test ./internal/cli -count=1 passed.
  • Full suite: GOWORK=off go test ./... passed.
  • AutoReview: accepted and fixed the delimiter, missing command-flag, nested-topic, post-argument help, and usage-accuracy findings. Final .agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main --stream-engine-output reported no accepted/actionable findings.
  • Added the required 0.11.6 - Unreleased changelog entry, crediting @0xdevalias.

No merge performed; ready for maintainer landing after hosted checks complete.

@steipete
steipete force-pushed the clawsweeper/issue-openclaw-discrawl-127 branch from 52e4855 to e584bb6 Compare July 16, 2026 19:41
@steipete
steipete merged commit 658c51f into main Jul 16, 2026
14 of 15 checks passed
@steipete
steipete deleted the clawsweeper/issue-openclaw-discrawl-127 branch July 16, 2026 19:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

clawsweeper:autogenerated PR created automatically by ClawSweeper clawsweeper Tracked by ClawSweeper automation merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

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

2 participants

@0xdevalias @steipete