Correct the README --json global-flag claim and lock it against drift #99

New issue

Closed

opened 2026-06-10 21:58:33 +00:00 by stephen · 0 comments

stephen commented

2026-06-10 21:58:33 +00:00

Owner

What

Fix README.md:177-178 so --json is no longer listed among the flags that "work on every command." Move it out of the global list and describe it as applying to data-returning commands (list/view/etc.), matching the accurate in-binary top-level help at src/cli/mod.rs:64. The genuinely global flags stay as listed (--host, --debug, --no-pager, --json-fields). Add a test that asserts the README "global flags" line stays in sync with the set of global = true args on the clap Cli struct (src/cli/mod.rs:82-99) so the doc and the code cannot drift apart again.

Why

rasterstate/fj#94: the README sells JSON output as a headline feature "so scripts and AI agents" can consume fj, and lists --json as a global flag, but only four flags are global = true; --json is declared per-subcommand, so fj auth status --json fails with "unexpected argument '--json' found." Scripters and agents are exactly the audience that reads "works on every command" literally and builds it into a wrapper, turning a marquee selling point into a first-contact trust paper cut. The in-binary help is already correct, so this is a verified doc-vs-code contradiction with a real user-facing error, fixed by correcting the doc rather than changing behavior.

Acceptance

README no longer claims --json is global; it documents --json as applying to data-returning commands (list/view/etc.).
A test fails if the README "global flags" list and the set of global = true args in Cli diverge.
cargo fmt --check, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all pass.

Dependencies

none

Out of scope

Promoting --json to a real global flag (the larger alternative direction); this item fixes the doc to match current behavior rather than changing behavior.
Reworking --json-fields or the JSON output format.

Size

## What Fix `README.md:177-178` so `--json` is no longer listed among the flags that "work on every command." Move it out of the global list and describe it as applying to data-returning commands (list/view/etc.), matching the accurate in-binary top-level help at `src/cli/mod.rs:64`. The genuinely global flags stay as listed (`--host`, `--debug`, `--no-pager`, `--json-fields`). Add a test that asserts the README "global flags" line stays in sync with the set of `global = true` args on the clap `Cli` struct (`src/cli/mod.rs:82-99`) so the doc and the code cannot drift apart again. ## Why rasterstate/fj#94: the README sells JSON output as a headline feature "so scripts and AI agents" can consume `fj`, and lists `--json` as a global flag, but only four flags are `global = true`; `--json` is declared per-subcommand, so `fj auth status --json` fails with "unexpected argument '--json' found." Scripters and agents are exactly the audience that reads "works on every command" literally and builds it into a wrapper, turning a marquee selling point into a first-contact trust paper cut. The in-binary help is already correct, so this is a verified doc-vs-code contradiction with a real user-facing error, fixed by correcting the doc rather than changing behavior. ## Acceptance - [ ] README no longer claims `--json` is global; it documents `--json` as applying to data-returning commands (list/view/etc.). - [ ] A test fails if the README "global flags" list and the set of `global = true` args in `Cli` diverge. - [ ] `cargo fmt --check`, `cargo clippy --all-targets --all-features -- -D warnings`, and `cargo test --all` pass. ## Dependencies none ## Out of scope - Promoting `--json` to a real global flag (the larger alternative direction); this item fixes the doc to match current behavior rather than changing behavior. - Reworking `--json-fields` or the JSON output format. ## Size S

stephen added the

backlog

labels

2026-06-10 21:58:54 +00:00

stephen referenced this issue

2026-06-10 21:59:31 +00:00

README documents --json as a global flag, but it is per-subcommand and errors on commands that lack it #94

stephen referenced this issue from a pull request that will close it,

2026-06-10 23:08:26 +00:00

Fix README global flags #100

stephen closed this issue

2026-06-10 23:29:12 +00:00