README documents --json as a global flag, but it is per-subcommand and errors on commands that lack it #94
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Observation
The README lists
--jsonas a global flag that works on every command (README.md:177-178):It is not global. Only four flags carry
global = truein the clapClistruct (src/cli/mod.rs:82-99):--host,--debug,--no-pager, and--json-fields.--jsonis declared per-subcommand (incli/pr.rs,cli/repo.rs,cli/issue.rs, etc.), so commands that don't opt in (e.g.fj auth ...) reject it.The binary's own top-level help is correct and omits
--json(src/cli/mod.rs:64):So the README and the in-binary help disagree. A user who trusts the README and runs, say,
fj auth status --jsongetserror: unexpected argument '--json' foundand has no way to know which commands actually accept it.Why it matters
The README sells JSON output as a headline feature "so scripts and AI agents" can consume
fj(README.md:41). Scripters and agents are precisely the audience that reads "global flag (works on every command)" literally and builds it into a wrapper. The contradiction turns a marquee selling point into a trust paper cut on first contact, and--json-fields(which IS global) reads from--jsonoutput, compounding the confusion about where the boundary is.Possible directions (sketches)
--jsonout of the "works on every command" list and state it applies to data-returning commands (list/view/etc.), matching the accurate in-binary help atmod.rs:64.--jsonto aglobal = trueflag and have commands that produce no structured output reject or ignore it explicitly, so the README claim becomes true.global = trueargs inCli, so the two can't drift again.Confidence
High. Both sides verified:
README.md:177-178(claim) vssrc/cli/mod.rs:82-99(only fourglobal = trueflags) andsrc/cli/mod.rs:64(correct in-binary help). The remaining decision (fix docs vs. promote the flag) is a product call, not an open question of fact.fj issue create#97Converted (label
converted). This opportunity became one backlog item:backlog,p3): Correct the README--jsonglobal-flag claim and lock it against drift.Kept open per the product-agent triage convention. Product call recorded: fix the doc to match current behavior (the smaller, accurate change) rather than promoting
--jsonto a real global flag. The in-binary help (src/cli/mod.rs:64) is already correct, so this is a verified doc-vs-code contradiction that produces a real "unexpected argument '--json'" error on a headline feature. Priority is p3: a genuine first-contact trust paper cut, not a blocker-to-purchase. The item also adds a drift-guard test so README and clap cannot diverge again.All derived backlog items are merged: rasterstate/fj#99 closed by PR #100. Closing this opportunity per the issue state machine (operator-approved).