help: filter by prefix, and surface flags through the CLI #57

closed cmc opened this on 2026-08-31 01:47 UTC · bug · assigned to cmc

Discussion

cmc 2026-08-31 01:47 UTC

gitbay <noun> --help lists subcommands and their one-line summaries but no flags. pass() sets DisableFlagParsing and intercepts --help before the server sees it (cmd/gitbay/main.go:117), so the only flag documentation that exists is the registry's Summary string.

Reaching that is awkward:

  • help ignores its arguments and prints all 149 entries (internal/control/control.go:164). help issue dumps the whole registry.
  • Output is in registration order, so related commands are not adjacent — build, repo secret, runner, help, dashboard appear in sequence.
  • ssh git@gitbay.org help | grep '^issue ' works, but only if you already know to do it.

Consequence: anything driving the CLI without prior knowledge — a new user, a script author, an assistant — either guesses flags or reads 149 lines to find one. Running a command bare prints its usage and exits 2, which is the current escape hatch and is not discoverable either.

Asks, in order of value:

  1. help <prefix>... filters to matching commands, so help issue prints the 11 issue commands.
  2. gitbay <cmd> --help forwards to the server and prints that command's real usage line instead of cobra's Short.
  3. Sort or group the unfiltered listing.

Summary currently carries a description and a usage string joined by ": ". Splitting it into Summary + Usage on Command would let 1 and 2 render cleanly, and would let the JSON envelope expose usage to API consumers.

closed by commit dca7370cd1 by cmc: help: filter by prefix, and document every command's arguments

2026-08-31 05:16 UTC