cli: help and usage print the command as typed #267

closed cmc opened this on 2026-09-28 03:18 UTC · cli ux

Discussion

cmc 2026-09-28 03:18 UTC

CLI help and usage show the server's command path, not the one typed.

  • gitbay auth keys --help prints USAGE ssh git@gitbay.org keys <verb> ...; gitbay auth token --help prints ssh git@gitbay.org token <verb>.
  • gitbay auth keys remove with no argument prints usage: keys remove <fingerprint>.
  • Every verb's usage shows <owner/name> as required, though the CLI infers it inside a clone.
  • gitbay auth keys add --help and pgp add --help print unknown flag "--help" and exit 2: their RunE closures in cmd/gitbay/main.go (around lines 432 and 452) go straight to stdinPayload without the --help check pass() has.
  • Two help layouts: gitbay auth --help is cobra's, gitbay notifications --help is the registry's.
  • Some summaries are bare nouns (issue assign → "assignees", issue comment → "comment").

Decided: when the call comes from the CLI, help and usage print the CLI form.

  • The CLI sends its invoking path with --term; the server prints gitbay auth keys remove <fingerprint> for it and the ssh git@host keys remove form for stock OpenSSH.
  • [<owner/name>] shown as optional from the CLI.
  • --help check in the keys add and pgp add closures.
  • Render the auth group with the registry layout.
  • Verb-phrase summaries: "add or remove assignees", "add a comment", "add or remove labels".

referenced in commit 4e0958a163 by cmc: plans: open issues from the architecture and UX reviews

2026-09-28 05:43 UTC

referenced in commit b711b70da5 by cmc: plans: apply decisions on the open questions

2026-09-28 06:16 UTC

referenced in commit bc76b6f008 by cmc: changelog: usage refusals name ssh git@ outside the CLI

2026-09-28 22:05 UTC

referenced in commit fd270da6d7 by cmc: help: no auth usage or footer over stock ssh

2026-09-28 22:05 UTC

closed by cmc in commit ba0a7d33f3: changelog: #267 and the --path= upgrade note

2026-09-28 22:05 UTC

referenced in commit 004ff6f433 by cmc: control, cmd/gitbay: guard nounAliases and aliasGroupNames against drift

2026-09-28 22:05 UTC

referenced in commit d5968a849e by cmc: summaries: verb phrases instead of bare nouns

2026-09-28 22:05 UTC

referenced in commit 7664da8384 by cmc: auth --help: force --path= for a bare CLI-only alias group

2026-09-28 22:05 UTC

referenced in commit 4eb0f95ce5 by cmc: help: auth (and any future CLI-only grouping) renders with the registry layout, in the CLI's own paths

2026-09-28 22:05 UTC

referenced in commit 44191b1a52 by cmc: auth keys add, pgp add: check --help before reading stdin

2026-09-28 22:05 UTC

referenced in commit d905c69753 by cmc: flags: print a bad-flag usage line the way a usage refusal does

2026-09-28 22:05 UTC

referenced in commit a1e67e455d by cmc: e2e: usage prints the CLI's own path, stock ssh the registered one

2026-09-28 22:05 UTC

referenced in commit a8523b10b1 by cmc: cli: send --path= where the CLI path differs from the server path

2026-09-28 22:05 UTC

referenced in commit a3fa0f0777 by cmc: usage, help: print the program and the CLI's own path for the command

2026-09-28 22:05 UTC