Gmail search query starting with "-" is parsed as a flag; error gives no hint about `--`

[postoso]

Gmail queries often start with a negation (-in:inbox, -label:x, -from:...). Passed as the positional query, gog parses it as a flag:

v0.43.0, macOS and Linux:

gog gmail search '-in:inbox newer_than:7d' --max 2 --json

{"error":{"class":"usage","code":2,"message":"unknown flag -i, ..."}}

gog gmail search --max 2 --json -- '-in:inbox newer_than:7d' works. That is standard parser behavior, but nothing in the error or docs points at it, and the failure is easy to misread as a bad query.

Could the usage error suggest -- when the unknown flag looks like the start of a Gmail query, or could the search docs mention it? Reordering the terms inside the same quoted query also works (gog gmail search 'newer_than:7d -in:inbox' --max 2 --json), but is less obvious.

[clawsweeper]

Codex review: this still needs some work. Reviewed October 6, 2026, 10:13 PM ET / October 7, 2026, 02:13 UTC.

Summary
Current main and v0.43.0 still lack the requested guidance. The open documentation PR already owns the work, so this issue should remain open until that PR is resolved.

Reproducibility: no. independently executed current-main reproduction was established. The reporter supplies failing and working commands, and source confirms positional query handling and unchanged parser-error wording.

Next step
Review and land or close #1187 before creating another repair, because it already owns this guidance.

Review details

Best possible solution:

Document both thread and message search examples with every flag before --, preserving existing parser and query semantics.

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

No independently executed current-main reproduction was established. The reporter supplies failing and working commands, and source confirms positional query handling and unchanged parser-error wording.

Is this the best way to solve the issue?

Yes. Documenting the existing delimiter directly satisfies the requested alternative without changing parsing, exit codes, or Gmail query semantics.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

No label changes.

Label justifications:

• P2: Common Gmail negation syntax produces confusing CLI errors, with a working delimiter workaround and a bounded documentation remedy.
• impact:ux-friction: Users can complete searches by adding the delimiter or reordering query terms, but current guidance leaves that recovery undiscoverable.

Evidence reviewed

What I checked:

• Current search guidance: Search and Read shows ordinary search examples but does not explain the delimiter for queries beginning with a hyphen; the README also lacks that guidance. (docs/gmail-workflows.md:10, 414e2ff8afa2)
• Production query boundary: Thread and message search declare query text as positional arguments and join those arguments before constructing Gmail requests. (internal/cmd/gmail_search.go:16, 414e2ff8afa2)
• Parse errors retain parser wording: Execute delegates argument parsing to Kong. The parse-error wrapper assigns exit code 2 without adding Gmail-specific delimiter guidance. (internal/cmd/root.go:549, 414e2ff8afa2)
• Existing implementation candidate: docs(gmail): explain option delimiter for negated search queries #1187 explicitly proposes both negated-query examples, a README pointer, and an Unreleased entry. Provided closing-reference context connects it to this issue; a live REST read confirms it remains open and unmerged.
• Release check: The v0.43.0 Gmail workflow document also lacks the requested delimiter guidance. (docs/gmail-workflows.md:10, 3b5122f4c81c)
• Area history and inspection limits: Available file history records Peter Steinberger's recent Gmail workflow documentation and search-count work. Deeper blame and symbol-history searches could not complete because missing historical objects failed to load; feature introduction remains unverified. (docs/gmail-workflows.md, 3f7a22e6e5bb)

Likely related people:

• Peter Steinberger: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

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]

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