Top-level args (--project / --schemas) aren't `global` — `rivet validate --project X` errors instead of working in any position

[avrabe]

Friction (hit while implementing #488)

--project / -p (and --schemas) are declared on the top-level Cli struct without global = true, so they only parse before the subcommand:

• ✅ rivet --project /path validate
• ❌ rivet validate --project /path → clap error, and with --format json the run produces empty stdout (the error goes to stderr), which is a confusing failure mode for anything shelling out to rivet.

This cost me a debug cycle in the --new-since feature (#488): a subprocess rivet validate --format json --project <dir> returned empty JSON → EOF while parsing a value, with no hint that the arg position was the problem. Many users (and tools) reasonably expect rivet <subcommand> --project X to work, since --project reads as a global option.

Suggested fix

Mark the top-level path args global = true:

#[arg(short, long, default_value = ".", global = true)]
project: PathBuf,
#[arg(long, global = true)]
schemas_dir: Option<PathBuf>,  // (or whatever the schemas arg is)

Then --project/--schemas work in any position. Low-risk (additive — the pre-subcommand form still works); worth a quick check that global args with a default_value behave as expected in clap derive.

(Workaround that finally helped: put --project before the subcommand.)

Found in the hourly dogfooding loop.

[avrabe]

Reopening — my attempted fix (REQ-209/#501, mark --project/--schemas global = true) broke main and has been reverted (#502).

Why it can't be done that way: clap debug-asserts when a global arg coexists with subcommands that take positionals — and rivet has several (next-id <type>, link <src> <tgt>, snapshot diff <baseline>, …). Making the path args global made rivet next-id <type> etc. panic in clap_builder debug_asserts (caught by 3 cli_commands tests once the full suite ran; my pre-merge check only hit validate, which has no positional, so it passed — lesson learned).

So the options for #500 are:

1. Document the convention (recommended, cheap): --project/--schemas precede the subcommand (rivet -p X validate), like git -C <dir> <cmd>. Add a note to the help/README. This is the standard pattern and avoids the clap limitation entirely.
2. Per-subcommand --project (define it on each subcommand instead of globally) — verbose, and changes help layout, but avoids the global/positional clash. Bigger change.
3. A clap upgrade or args_conflicts_with_subcommands-style workaround — needs investigation; clap's restriction is intentional.

Recommend (1). The empty-stdout-on-arg-error confusion I hit is real, but the root cause is "global path args + positional subcommands is a clap no-go", not a rivet bug per se. Leaving open for the maintainer to pick the doc/UX direction.

[avrabe]

Triage pass (issue-triage agent run 2026-06-06).

Premise still valid against main: top-level --project / --schemas aren't global = true, so rivet validate --project X errors instead of working in any position; with --format json the error goes to stderr and stdout is empty, exactly the confusing failure mode the body describes. Your reopening comment is right on the why the naive fix can't land — clap debug-asserts when a global arg coexists with subcommand positionals (next-id <type>, link <src> <tgt>, snapshot diff <baseline>, …), which the #501 attempt didn't catch because the pre-merge check only exercised validate (no positional). #501 was reverted in #502, main is back at baseline, so this issue is still open and needs a different shape of fix than the original "mark them global" sketch.

The three options in your reopening comment are well-scoped:

1. Document the convention (--project precedes the subcommand, git -C <dir> <cmd> pattern) + improve the failure mode for tools shelling out with --format json.
2. Per-subcommand --project (define it on each subcommand).
3. A args_conflicts_with_subcommands-style workaround / clap upgrade investigation.

Per "one PR per issue, keep PRs focused", picking which lands first is the maintainer call. Could you lift the chosen slice into an explicit ## Acceptance Criteria block? Sketch for your recommended path (option 1 — document + de-trap):

## Acceptance Criteria — option 1 (document the convention)
- [ ] README.md / AGENTS.md grow a short "global path args" note: `--project` / `--schemas` precede the subcommand (the `git -C <dir> <cmd>` pattern); covers the JSON-tool case explicitly
- [ ] Address the empty-stdout-on-arg-error trap that cost a debug cycle in #488: when `--format json` is in argv *anywhere* and clap errors on arg position, emit a single-line JSON error envelope (e.g. `{"error":"argument '--project' must precede the subcommand","hint":"rivet --project X <subcommand>"}`) on **stdout** instead of an empty payload. JSON consumers no longer get `EOF while parsing a value`; the hint points at the convention
- [ ] Subcommand `--help` text (at least `validate`, `list`, `add`, `next-id`, `link`) mentions where `--project` / `--schemas` belong — one-liner each, so a tool author sees it from `rivet <subcmd> --help`
- [ ] Regression test (`cli_commands` or a new `cli_global_args` test): `rivet validate --project X --format json` (wrong position) produces non-empty, parseable JSON on stdout matching the envelope; `rivet -p X validate --format json` (correct position) is byte-for-byte unchanged
- [ ] Regression test: all subcommands with positionals continue to parse correctly (the clap-debug-assert that bit #501 stays absent — guarded by the existing `cli_commands` matrix that caught it the first time)
- [ ] `rivet validate` PASS unchanged; `cargo test -p rivet-cli` green; `cargo fmt --check` / `clippy --all-targets -- -D warnings` clean
- [ ] Commit trailers: `Implements: REQ-NNN` (file a new REQ for the `--project` UX clarification) + `Refs: #488, #501, #502`
- [ ] **Explicitly out of scope (file separately if wanted):** option 2 (per-subcommand `--project` — verbose, changes help layout); option 3 (clap upgrade / `args_conflicts_with_subcommands` workaround — needs a feasibility spike before AC is meaningful)

If you'd rather start with option 2 or 3, the AC shape changes — option 2 needs the bullets to enumerate the subcommands that gain the flag and the help-layout regression check; option 3 needs a feasibility-spike bullet (find the clap idiom that resolves the global+positional clash without debug_asserts panicking) before implementation AC is meaningful.

Process side-rail (same as every other open triage thread this week): https://pulseengine.eu/blog/ is still HTTP 503 (the expired-TLS symptom flagged on #420 and re-noted on #468 / #456 / #436 / #431 / #422 / #479 / #490). The binding workflow guidance can't be consulted, so no PR will land from this triage run regardless. Comment is the AC ask only.

Not implemented this run.

---

Generated by Claude Code — issue-triage agent run 2026-06-06.

---

Generated by Claude Code

[avrabe]

Shipped a small docs clarity fix in #503: --help for --project/--schemas now states the actionable convention (pass them BEFORE the subcommand, like git -C <dir> <cmd>) instead of the clap-internals jargon the revert left behind. This surfaces the workaround at the point of confusion. Leaving this issue open for your call on whether to also support per-subcommand --project (option 2) — the global approach is a clap no-go (it debug-asserts with positional subcommands), but per-subcommand definition would work if the ergonomic win is worth the verbosity.