!388 · krz/gitbay

.gitbay/wiki/Admin.org +1 −1

	@@ -434,7 +434,7 @@ podman. A runner without it builds trusted commits only.
434	that has polled as a runner: the account, the key's fingerprint, when it	434	that has polled as a runner: the account, the key's fingerprint, when it
435	last polled, the repositories it may claim — its attachments for a runner	435	last polled, the repositories it may claim — its attachments for a runner
436	key, the =-repos= it asked for or =any= for an admin key — and the build	436	key, the =-repos= it asked for or =any= for an admin key — and the build
437	it holds; =admin runners forget <fingerprint>= drops the row for a key	437	it holds; =admin runners remove <fingerprint>= (=forget= until the next release) drops the row for a key
438	that polled by mistake, the key itself untouched. =admin runners= also	438	that polled by mistake, the key itself untouched. =admin runners= also
439	heads the list with the queue: builds	439	heads the list with the queue: builds
440	pending now, and over the last day how many were claimed, how long they	440	pending now, and over the last day how many were claimed, how long they

.gitbay/wiki/Users.org +28

	@@ -656,6 +656,34 @@ someone else.
656	You are never mailed about your own actions, and only verified primary	656	You are never mailed about your own actions, and only verified primary
657	addresses receive anything. Delivery retries on relay failure.	657	addresses receive anything. Delivery retries on relay failure.
658		658
		659	* Output rules
		660
		661	=--json= is the contract; the plain output is for a person at a
		662	terminal, and follows these rules so every noun reads the same way.
		663
		664	- A list command prints one row per item, tab-separated, no header.
		665	Columns run identifier, state, then description; a trailing column
		666	may carry a word (=due 2027-01-01=, =via team=). The =gitbay= CLI pads
		667	the tabs into aligned columns when stdout is a terminal and leaves
		668	them as tabs when piped, so =cut -f= sees the same bytes stock ssh
		669	prints. Under =--json= nothing is touched.
		670	- An empty list prints nothing on stdout and =nothing to list= on
		671	stderr.
		672	- A mutation prints one line: verb, object, identifier
		673	(=created krz/gitbay#7=). A second line appears only for something
		674	to copy: a URL, a token shown once.
		675	- A bad invocation prints =usage:= and the command's registered usage,
		676	the same text =help <noun>= shows. Exit 2.
		677	- A refusal says who may and what to do instead: =only admins of acme
		678	can manage teams; ask one to add you=. Exit 4. A thing that does not
		679	exist, or that you may not know exists, is exit 3.
		680	- stdout is the result; stderr is everything else: progress, a note
		681	that output was truncated, errors.
		682	- Verbs: =create= and =delete= for things with their own identity
		683	(repository, issue, release, team), =add= and =remove= for attaching
		684	something to them (a key, a member, a label on an issue), =set= for
		685	a value, =revoke= for a credential, =show= and =list= for reads.
		686
659	* Scripting	687	* Scripting
660		688
661	Every read command takes =--json= and emits one envelope:	689	Every read command takes =--json= and emits one envelope:

CHANGELOG.org +16

	@@ -4,6 +4,22 @@ Versioning follows semver from v0.1.0. Database migrations run
4	automatically on daemon start; upgrade notes appear per release when	4	automatically on daemon start; upgrade notes appear per release when
5	anything beyond "replace the binary and restart" is needed.	5	anything beyond "replace the binary and restart" is needed.
6		6
		7	* v1.22.0 — unreleased
		8
		9	The CLI output sweep (#183). The rules are on the wiki's Users page,
		10	under "Output rules".
		11
		12	- A bad invocation prints the command's registered usage, the one
		13	source of it; the hand-written copies are gone.
		14	- The =gitbay= CLI pads list rows into aligned columns at a terminal
		15	and leaves the tabs alone when piped.
		16	- An empty list prints nothing on stdout and =nothing to list= on
		17	stderr.
		18	- Every refusal (exit 4) says what to do instead.
		19	- =status list= and =repo topics= print rows.
		20	- =admin runners remove=; =forget= stays as an alias until the next
		21	release.
		22
7	* v1.21.0 — 2026-09-12	23	* v1.21.0 — 2026-09-12
8		24
9	The web UI/UX sweep (#182).	25	The web UI/UX sweep (#182).

cmd/gitbay/main.go +2 −1

 			pass("invite", "issue a registration invite and mail its code: --email <address>", passOpts{server: []string{"admin", "invite"}}),
 			pass("stats", "instance statistics: counts and per-repository disk usage", passOpts{server: []string{"admin", "stats"}}),
 			withSub(pass("runners", "the build queue and runner keys: last poll, scope, the build each holds", passOpts{server: []string{"admin", "runners"}}),
-				pass("forget", "drop a key's heartbeat row: <fingerprint>", passOpts{server: []string{"admin", "runners", "forget"}})),
+				pass("remove", "drop a key's heartbeat row: <fingerprint>", passOpts{server: []string{"admin", "runners", "remove"}}),
+				pass("forget", "alias of remove: <fingerprint>", passOpts{server: []string{"admin", "runners", "forget"}})),
 			group("repo", "any repository, for moderation (audited)",
 				pass("list", "every repository with size and last push: [--owner o] [--visibility v] [--limit n] [--cursor c]", passOpts{server: []string{"admin", "repo", "list"}}),
 				pass("archive", "archive a repository: <owner/name>", passOpts{server: []string{"admin", "repo", "archive"}}),

cmd/gitbay/ssh.go +41

	@@ -1,8 +1,11 @@
1	package main	1	package main
2		2
3	import (	3	import (
		4	"text/tabwriter"
		5
4	"encoding/json"	6	"encoding/json"
5	"fmt"	7	"fmt"
		8	"golang.org/x/term"
6	"io"	9	"io"
7	"os"	10	"os"
8	"os/exec"	11	"os/exec"
	@@ -120,7 +123,15 @@ func runSSH(t target, serverArgv []string, stdin io.Reader) int {
120	cmd.Stdin = stdin	123	cmd.Stdin = stdin
121	cmd.Stdout = os.Stdout	124	cmd.Stdout = os.Stdout
122	cmd.Stderr = os.Stderr	125	cmd.Stderr = os.Stderr
		126	var tw *tabwriter.Writer
		127	if alignColumns(serverArgv) {
		128	tw = tabwriter.NewWriter(os.Stdout, 0, 8, 2, ' ', 0)
		129	cmd.Stdout = tw
		130	}
123	err := cmd.Run()	131	err := cmd.Run()
		132	if tw != nil {
		133	tw.Flush()
		134	}
124	if err == nil {	135	if err == nil {
125	return 0	136	return 0
126	}	137	}
	@@ -193,3 +204,33 @@ func withRepo(t target, args []string) ([]string, error) {
193	}	204	}
194	return append([]string{t.repo}, args...), nil	205	return append([]string{t.repo}, args...), nil
195	}	206	}
		207
		208	// listVerbs are the server commands whose plain output is one row per
		209	// item with tab-separated columns.
		210	var listVerbs = map[string]bool{
		211	"list": true, "runners": true, "deliveries": true, "refs": true,
		212	"revisions": true, "threads": true, "bookmarks": true, "jobs": true,
		213	}
		214
		215	// alignColumns reports whether a command's rows should be padded into
		216	// columns: a list command, printed for a person at a terminal. Piped
		217	// output keeps the server's tabs so cut and awk see the same bytes stock
		218	// ssh prints, and --json is never touched.
		219	func alignColumns(serverArgv []string) bool {
		220	verb := ""
		221	for _, a := range serverArgv {
		222	if strings.HasPrefix(a, "-") {
		223	break
		224	}
		225	if a == "--json" {
		226	return false
		227	}
		228	verb = a
		229	}
		230	for _, a := range serverArgv {
		231	if a == "--json" {
		232	return false
		233	}
		234	}
		235	return listVerbs[verb] && term.IsTerminal(int(os.Stdout.Fd()))
		236	}

internal/control/admin.go +16 −10

 		Summary:  "the build queue and runner accounts: last poll, scope, the build each holds (instance admins)",
 		Usage:    "admin runners",
 		ReadOnly: true, SSHOnly: true, Run: runAdminRunners})
-	register(Command{Path: []string{"admin", "runners", "forget"},
+	register(Command{Path: []string{"admin", "runners", "remove"},
 		Summary: "drop a key's runner heartbeat row, e.g. one that polled once by mistake (instance admins)",
+		Usage:   "admin runners remove <fingerprint>",
+		SSHOnly: true, Run: runAdminRunnersForget})
+	// forget is the name this shipped under in v1.18; remove is the verb
+	// every other noun uses. Both stay for one release.
+	register(Command{Path: []string{"admin", "runners", "forget"},
+		Summary: "alias of admin runners remove",
 		Usage:   "admin runners forget <fingerprint>",
 		SSHOnly: true, Run: runAdminRunnersForget})
 	register(Command{Path: []string{"admin", "repo", "list"},
 // requireInstanceAdmin gates the admin noun. -1 means proceed.
 func requireInstanceAdmin(c *Ctx) int {
 	if !c.User.IsAdmin {
-		return c.fail(protocol.ExitDenied, "admin commands are for instance admins")
+		return c.fail(protocol.ExitDenied, "admin commands are for instance admins; ask one")
 	}
 	return -1
 }
 		return code
 	}
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: admin user show <username>")
+		return c.usage()
 	}
 	name := args[0]
 	u, err := c.Store.UserByUsername(name)
 		verb = "promote"
 	}
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: admin user %s <username>", verb)
+		return c.usage()
 	}
 	u, err := c.Store.UserByUsername(args[0])
 	if errors.Is(err, store.ErrNotFound) {
 		verb = "unarchive"
 	}
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: admin repo %s <owner/name>", verb)
+		return c.usage()
 	}
 	repo, code := adminRepo(c, args[0])
 	if code >= 0 {
 func runAdminRepoVisibility(c *Ctx, args []string) int {
 	if len(args) != 2 || (args[1] != "public" && args[1] != "private") {
-		return c.fail(protocol.ExitUsage, "usage: admin repo visibility <owner/name> public|private")
+		return c.usage()
 	}
 	repo, code := adminRepo(c, args[0])
 	if code >= 0 {
 		} else if path == "" {
 			path = a
 		} else {
-			return c.fail(protocol.ExitUsage, "usage: admin repo delete <owner/name> --yes")
+			return c.usage()
 		}
 	}
 	if path == "" {
-		return c.fail(protocol.ExitUsage, "usage: admin repo delete <owner/name> --yes")
+		return c.usage()
 	}
 	repo, code := adminRepo(c, path)
 	if code >= 0 {
 		return code
 	}
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: admin runners forget <fingerprint>")
+		return c.usage()
 	}
 	if err := c.Store.ForgetRunner(args[0]); err != nil {
 		if errors.Is(err, store.ErrNotFound) {
 		return code
 	}
 	if len(args) != 0 {
-		return c.fail(protocol.ExitUsage, "usage: admin runners")
+		return c.usage()
 	}
 	runners, err := c.Store.ListRunners()
 	if err != nil {

internal/control/adminhost.go +7 −8

 	if code := requireInstanceAdmin(c); code >= 0 {
 		return code
 	}
-	const usage = "usage: admin user create <username> [--admin] [--email <address> [--verified]] [--key -] < key.pub"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--email", "--key"}, Bools: []string{"--admin", "--verified"}, MaxPos: 1, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--email", "--key"}, Bools: []string{"--admin", "--verified"}, MaxPos: 1, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 		return c.fail(protocol.ExitUsage, "--key only supports - (the public key on stdin)")
 	}
 	if username == "" || username[0] == '-' {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	if username == "" || (verified && email == "") {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	if err := policy.ValidateOwnerName(username); err != nil {
 		return c.failInput(err)
 		return store.User{}, code
 	}
 	if len(args) != 1 {
-		return store.User{}, c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return store.User{}, c.usage()
 	}
 	u, err := c.Store.UserByUsername(args[0])
 	if errors.Is(err, store.ErrNotFound) {
 		return code
 	}
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: admin email verify <username> <address>")
+		return c.usage()
 	}
 	u, err := c.Store.UserByUsername(args[0])
 	if errors.Is(err, store.ErrNotFound) {
 		email = args[1]
 	}
 	if email == "" {
-		return c.fail(protocol.ExitUsage, "usage: admin invite --email <address>")
+		return c.usage()
 	}
 	if used, err := c.Store.EmailInUse(email); err != nil {
 		return c.fail(protocol.ExitFailure, "%v", err)
 		return code
 	}
 	if len(args) != 0 {
-		return c.fail(protocol.ExitUsage, "usage: admin stats")
+		return c.usage()
 	}
 	counts, err := c.Store.InstanceCounts()
 	if err != nil {

internal/control/audit.go +2 −4

 		ReadOnly: true, SSHOnly: true, Run: runAudit})
 }
-const auditUsage = "usage: audit [--actor <user>|-] [--action <prefix>] [--since <duration|date>] [--limit <n>]"
 func runAudit(c *Ctx, args []string) int {
 	if !c.User.IsAdmin {
-		return c.fail(protocol.ExitDenied, "the audit log is for instance admins")
+		return c.fail(protocol.ExitDenied, "the audit log is for instance admins; ask one")
 	}
 	f := store.AuditFilter{Limit: 100}
-	fl, err := parseFlags(args, flagSpec{Values: []string{"--limit", "--actor", "--action", "--since"}, MaxPos: 0, Usage: auditUsage})
+	fl, err := parseFlags(args, flagSpec{Values: []string{"--limit", "--actor", "--action", "--since"}, MaxPos: 0, Usage: c.Cmd.Usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}

internal/control/build.go +12 −12

	@@ -104,7 +104,7 @@ func buildRef(c *Ctx, args []string) (store.Repo, store.Build, int) {
104		104
105	func runBuildList(c *Ctx, args []string) int {	105	func runBuildList(c *Ctx, args []string) int {
106	if len(args) != 1 {	106	if len(args) != 1 {
107	return c.fail(protocol.ExitUsage, "usage: build list <owner/name>")	107	return c.usage()
108	}	108	}
109	repo, code := resolveRepo(c, args[0], policy.CanRead)	109	repo, code := resolveRepo(c, args[0], policy.CanRead)
110	if code >= 0 {	110	if code >= 0 {
	@@ -182,7 +182,7 @@ func repoJobs(c *Ctx, repo store.Repo) ([]ci.Job, string, int) {
182	// that can read the repository's git could offer the choice.	182	// that can read the repository's git could offer the choice.
183	func runBuildJobs(c *Ctx, args []string) int {	183	func runBuildJobs(c *Ctx, args []string) int {
184	if len(args) != 1 {	184	if len(args) != 1 {
185	return c.fail(protocol.ExitUsage, "usage: build jobs <owner/name>")	185	return c.usage()
186	}	186	}
187	repo, code := resolveRepo(c, args[0], policy.CanRead)	187	repo, code := resolveRepo(c, args[0], policy.CanRead)
188	if code >= 0 {	188	if code >= 0 {
	@@ -212,7 +212,7 @@ func runBuildJobs(c *Ctx, args []string) int {
212		212
213	func runBuildTrigger(c *Ctx, args []string) int {	213	func runBuildTrigger(c *Ctx, args []string) int {
214	if len(args) != 2 {	214	if len(args) != 2 {
215	return c.fail(protocol.ExitUsage, "usage: build trigger <owner/name> <job>")	215	return c.usage()
216	}	216	}
217	repo, code := resolveRepo(c, args[0], policy.CanWrite)	217	repo, code := resolveRepo(c, args[0], policy.CanWrite)
218	if code >= 0 {	218	if code >= 0 {
	@@ -246,7 +246,7 @@ var secretName = regexp.MustCompile(`^[A-Z_][A-Z0-9_]{0,63}$`)
246		246
247	func runSecretSet(c *Ctx, args []string) int {	247	func runSecretSet(c *Ctx, args []string) int {
248	if len(args) != 2 {	248	if len(args) != 2 {
249	return c.fail(protocol.ExitUsage, "usage: repo secret set <owner/name> <NAME> (value on stdin)")	249	return c.usage()
250	}	250	}
251	if !secretName.MatchString(args[1]) {	251	if !secretName.MatchString(args[1]) {
252	return c.fail(protocol.ExitUsage, "secret names are env-var shaped: uppercase letters, digits, _")	252	return c.fail(protocol.ExitUsage, "secret names are env-var shaped: uppercase letters, digits, _")
	@@ -273,7 +273,7 @@ func runSecretSet(c *Ctx, args []string) int {
273		273
274	func runSecretRemove(c *Ctx, args []string) int {	274	func runSecretRemove(c *Ctx, args []string) int {
275	if len(args) != 2 {	275	if len(args) != 2 {
276	return c.fail(protocol.ExitUsage, "usage: repo secret remove <owner/name> <NAME>")	276	return c.usage()
277	}	277	}
278	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	278	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
279	if code >= 0 {	279	if code >= 0 {
	@@ -292,7 +292,7 @@ func runSecretRemove(c *Ctx, args []string) int {
292		292
293	func runSecretList(c *Ctx, args []string) int {	293	func runSecretList(c *Ctx, args []string) int {
294	if len(args) != 1 {	294	if len(args) != 1 {
295	return c.fail(protocol.ExitUsage, "usage: repo secret list <owner/name>")	295	return c.usage()
296	}	296	}
297	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	297	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
298	if code >= 0 {	298	if code >= 0 {
	@@ -376,7 +376,7 @@ func runRunnerNext(c *Ctx, args []string) int {
376	return c.fail(protocol.ExitFailure, "%v", err)	376	return c.fail(protocol.ExitFailure, "%v", err)
377	}	377	}
378	if !ok {	378	if !ok {
379	return c.fail(protocol.ExitDenied, "this key is not attached to %s", repo.Path())	379	return c.fail(protocol.ExitDenied, "this key is not attached to %s; a repository admin attaches it with repo runner add", repo.Path())
380	}	380	}
381	repoIDs = append(repoIDs, repo.ID)	381	repoIDs = append(repoIDs, repo.ID)
382	}	382	}
	@@ -464,7 +464,7 @@ func runRunnerLog(c *Ctx, args []string) int {
464	return code	464	return code
465	}	465	}
466	if len(args) != 1 {	466	if len(args) != 1 {
467	return c.fail(protocol.ExitUsage, "usage: runner log <build-id> (chunk on stdin)")	467	return c.usage()
468	}	468	}
469	id, err := strconv.ParseInt(args[0], 10, 64)	469	id, err := strconv.ParseInt(args[0], 10, 64)
470	if err != nil {	470	if err != nil {
	@@ -475,7 +475,7 @@ func runRunnerLog(c *Ctx, args []string) int {
475	} else if ok, err := runnerMayBuild(c, key, b.RepoID); err != nil {	475	} else if ok, err := runnerMayBuild(c, key, b.RepoID); err != nil {
476	return c.fail(protocol.ExitFailure, "%v", err)	476	return c.fail(protocol.ExitFailure, "%v", err)
477	} else if !ok {	477	} else if !ok {
478	return c.fail(protocol.ExitDenied, "this key is not attached to the build's repository")	478	return c.fail(protocol.ExitDenied, "this key is not attached to the build's repository; a repository admin attaches it with repo runner add")
479	}	479	}
480	// Stream stdin into the log in chunks so long builds appear live. An	480	// Stream stdin into the log in chunks so long builds appear live. An
481	// append that fails drops its chunk and the loop keeps draining: ending	481	// append that fails drops its chunk and the loop keeps draining: ending
	@@ -542,7 +542,7 @@ func runRunnerDone(c *Ctx, args []string) int {
542	return code	542	return code
543	}	543	}
544	if len(args) != 2 \|\| (args[1] != "success" && args[1] != "failure") {	544	if len(args) != 2 \|\| (args[1] != "success" && args[1] != "failure") {
545	return c.fail(protocol.ExitUsage, "usage: runner done <build-id> success\|failure")	545	return c.usage()
546	}	546	}
547	id, err := strconv.ParseInt(args[0], 10, 64)	547	id, err := strconv.ParseInt(args[0], 10, 64)
548	if err != nil {	548	if err != nil {
	@@ -555,7 +555,7 @@ func runRunnerDone(c *Ctx, args []string) int {
555	if ok, err := runnerMayBuild(c, key, b.RepoID); err != nil {	555	if ok, err := runnerMayBuild(c, key, b.RepoID); err != nil {
556	return c.fail(protocol.ExitFailure, "%v", err)	556	return c.fail(protocol.ExitFailure, "%v", err)
557	} else if !ok {	557	} else if !ok {
558	return c.fail(protocol.ExitDenied, "this key is not attached to the build's repository")	558	return c.fail(protocol.ExitDenied, "this key is not attached to the build's repository; a repository admin attaches it with repo runner add")
559	}	559	}
560	// Cancelled underneath the runner: its report is late, not wrong.	560	// Cancelled underneath the runner: its report is late, not wrong.
561	// The row, the status and the log were settled by the cancel.	561	// The row, the status and the log were settled by the cancel.
	@@ -829,7 +829,7 @@ func runBuildCancel(c *Ctx, args []string) int {
829	return c.fail(protocol.ExitFailure, "%v", err)	829	return c.fail(protocol.ExitFailure, "%v", err)
830	}	830	}
831	if !policy.CanWrite(c.User, repo, grant) {	831	if !policy.CanWrite(c.User, repo, grant) {
832	return c.fail(protocol.ExitDenied, "cancelling a build needs write access to %s", repo.Path())	832	return c.fail(protocol.ExitDenied, "cancelling a build needs write access to %s; ask its owner", repo.Path())
833	}	833	}
834	if b.Status != "pending" && b.Status != "running" {	834	if b.Status != "pending" && b.Status != "running" {
835	return c.fail(protocol.ExitUsage, "build %d is %s; only a queued or running build can be cancelled", b.Number, b.Status)	835	return c.fail(protocol.ExitUsage, "build %d is %s; only a queued or running build can be cancelled", b.Number, b.Status)

internal/control/commitfile.go +3 −4

 // A repository that requires verified signatures therefore refuses the
 // command rather than writing a commit its own policy would reject.
 func runCommitFile(c *Ctx, args []string) int {
-	const usage = "repo commit-file <owner/name> <path> --ref <branch> [--message <m>] [--file -]"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--ref", "--message", "--file"}, MaxPos: -1, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--ref", "--message", "--file"}, MaxPos: -1, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	rest := f.Pos
 	ref, message, file := f.Value("--ref"), f.Value("--message"), f.Value("--file")
 	if len(rest) != 2 || ref == "" {
-		return c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, rest[0], policy.CanWrite)
 	if code >= 0 {
 		return c.fail(protocol.ExitUsage, "path must stay inside the repository")
 	}
 	if repo.Settings.RequireMR && slices.Contains(repo.Settings.ProtectedBranches, ref) {
-		return c.fail(protocol.ExitDenied, "branch %s accepts changes through merge requests only", ref)
+		return c.fail(protocol.ExitDenied, "branch %s accepts changes through merge requests only; push another branch and open one", ref)
 	}
 	// The server authors this commit, so it cannot sign it.
 	if repo.Settings.RequireSignedCommits {

internal/control/control.go +22 −5

 	// Source identifies the credential behind this session for the audit
 	// log: an SSH key fingerprint, or "api" for token requests.
 	Source string
+	// Cmd is the command being run, set by Dispatch, so a usage error can
+	// print the registered usage rather than a copy of it.
+	Cmd Command
+}
+// usage reports a bad invocation with the command's registered usage,
+// the one source of it.
+func (c *Ctx) usage() int {
+	return c.fail(protocol.ExitUsage, "usage: %s", c.Cmd.Usage)
 }
 type Command struct {
 		return c.fail(protocol.ExitUsage, "no command given; try: ssh <host> help")
 	}
 	cmd, rest, ok := Lookup(argv)
+	c.Cmd = cmd
 	if !ok {
 		return c.fail(protocol.ExitUsage, "unknown command %q", argv[0])
 	}
 	// A runner-scoped key reaches the runner protocol and nothing else, so
 	// the key a CI host holds cannot administer the instance.
 	if c.Scope != "full" && !(c.Scope == "runner" && cmd.Path[0] == "runner") {
-		return c.fail(protocol.ExitDenied, "this key's scope (%s) does not allow control commands", c.Scope)
+		return c.fail(protocol.ExitDenied, "this key's scope (%s) does not allow control commands; use a key added with --scope full", c.Scope)
 	}
 	if c.ViaAPI && cmd.SSHOnly {
 		return c.fail(protocol.ExitDenied, "%s is only available over SSH", joinPath(cmd.Path))
 	}
 	if c.ReadOnly && !cmd.ReadOnly {
-		return c.fail(protocol.ExitDenied, "this token is read-only; %s modifies state", joinPath(cmd.Path))
+		return c.fail(protocol.ExitDenied, "this token is read-only; %s modifies state — mint one with --scope full", joinPath(cmd.Path))
 	}
 	// The SSH listener refuses a disabled account before it gets here; the
 	// API and the web reach Dispatch directly, so the check lives here too.
 	if c.User.Disabled {
-		return c.fail(protocol.ExitDenied, "this account is disabled")
+		return c.fail(protocol.ExitDenied, "this account is disabled; ask an instance admin to enable it")
 	}
 	// The admin noun is gated here as well as in each handler, so a new
 	// admin command that forgets requireInstanceAdmin is still refused.
 	if cmd.Path[0] == "admin" && !c.User.IsAdmin {
-		return c.fail(protocol.ExitDenied, "admin commands are for instance admins")
+		return c.fail(protocol.ExitDenied, "admin commands are for instance admins; ask one")
 	}
 	if c.User.Pending && !pendingAllowed(cmd.Path) {
 		return c.fail(protocol.ExitDenied,
 // otherwise via the plain formatter.
 func (c *Ctx) emit(data any, plain func(w io.Writer)) int {
 	// A nil slice would serialize as null; consumers should see [].
-	if v := reflect.ValueOf(data); v.Kind() == reflect.Slice && v.IsNil() {
+	v := reflect.ValueOf(data)
+	if v.Kind() == reflect.Slice && v.IsNil() {
 		data = reflect.MakeSlice(v.Type(), 0, 0).Interface()
 	}
+	// An empty list prints nothing a script would read; the person at
+	// the terminal hears about it on stderr.
+	if !c.JSON && v.Kind() == reflect.Slice && v.Len() == 0 {
+		fmt.Fprintln(c.Stderr, "nothing to list")
+		return protocol.ExitOK
+	}
 	if c.JSON {
 		enc := json.NewEncoder(c.Stdout)
 		enc.SetEscapeHTML(false)

internal/control/dashboard.go +2 −2

	@@ -84,7 +84,7 @@ type DashboardOut struct {
84		84
85	func runDashboard(c *Ctx, args []string) int {	85	func runDashboard(c *Ctx, args []string) int {
86	if len(args) != 0 {	86	if len(args) != 0 {
87	return c.fail(protocol.ExitUsage, "usage: dashboard")	87	return c.usage()
88	}	88	}
89	d := DashboardOut{	89	d := DashboardOut{
90	Reviews: []DashboardItem{}, Assigned: []DashboardItem{}, MRs: []DashboardItem{},	90	Reviews: []DashboardItem{}, Assigned: []DashboardItem{}, MRs: []DashboardItem{},
	@@ -260,7 +260,7 @@ func runFeed(c *Ctx, args []string) int {
260	return code	260	return code
261	}	261	}
262	if len(rest) != 0 {	262	if len(rest) != 0 {
263	return c.fail(protocol.ExitUsage, "usage: feed [--limit <n>] [--cursor <c>]")	263	return c.usage()
264	}	264	}
265	if p.limit == 0 {	265	if p.limit == 0 {
266	p.limit = feedDefaultLimit	266	p.limit = feedDefaultLimit

internal/control/deploykey.go +4 −4

	@@ -34,13 +34,13 @@ func runDeployKeyAdd(c *Ctx, args []string) int {
34	mode = "rw"	34	mode = "rw"
35	default:	35	default:
36	if path != "" {	36	if path != "" {
37	return c.fail(protocol.ExitUsage, "usage: repo deploy-key add <owner/name> [--rw] < key.pub")	37	return c.usage()
38	}	38	}
39	path = a	39	path = a
40	}	40	}
41	}	41	}
42	if path == "" {	42	if path == "" {
43	return c.fail(protocol.ExitUsage, "usage: repo deploy-key add <owner/name> [--rw] < key.pub")	43	return c.usage()
44	}	44	}
45	repo, code := resolveRepo(c, path, policy.CanAdmin)	45	repo, code := resolveRepo(c, path, policy.CanAdmin)
46	if code >= 0 {	46	if code >= 0 {
	@@ -73,7 +73,7 @@ func runDeployKeyAdd(c *Ctx, args []string) int {
73		73
74	func runDeployKeyList(c *Ctx, args []string) int {	74	func runDeployKeyList(c *Ctx, args []string) int {
75	if len(args) != 1 {	75	if len(args) != 1 {
76	return c.fail(protocol.ExitUsage, "usage: repo deploy-key list <owner/name>")	76	return c.usage()
77	}	77	}
78	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	78	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
79	if code >= 0 {	79	if code >= 0 {
	@@ -106,7 +106,7 @@ func runDeployKeyList(c *Ctx, args []string) int {
106		106
107	func runDeployKeyRemove(c *Ctx, args []string) int {	107	func runDeployKeyRemove(c *Ctx, args []string) int {
108	if len(args) != 2 {	108	if len(args) != 2 {
109	return c.fail(protocol.ExitUsage, "usage: repo deploy-key remove <owner/name> <fingerprint>")	109	return c.usage()
110	}	110	}
111	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	111	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
112	if code >= 0 {	112	if code >= 0 {

internal/control/deps.go +3 −3

	@@ -46,7 +46,7 @@ type DepBehind struct {
46		46
47	func runDepsEnable(c *Ctx, args []string) int {	47	func runDepsEnable(c *Ctx, args []string) int {
48	if len(args) != 1 {	48	if len(args) != 1 {
49	return c.fail(protocol.ExitUsage, "usage: repo deps enable <owner/name>")	49	return c.usage()
50	}	50	}
51	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	51	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
52	if code >= 0 {	52	if code >= 0 {
	@@ -62,7 +62,7 @@ func runDepsEnable(c *Ctx, args []string) int {
62		62
63	func runDepsDisable(c *Ctx, args []string) int {	63	func runDepsDisable(c *Ctx, args []string) int {
64	if len(args) != 1 {	64	if len(args) != 1 {
65	return c.fail(protocol.ExitUsage, "usage: repo deps disable <owner/name>")	65	return c.usage()
66	}	66	}
67	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	67	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
68	if code >= 0 {	68	if code >= 0 {
	@@ -78,7 +78,7 @@ func runDepsDisable(c *Ctx, args []string) int {
78		78
79	func runDepsStatus(c *Ctx, args []string) int {	79	func runDepsStatus(c *Ctx, args []string) int {
80	if len(args) != 1 {	80	if len(args) != 1 {
81	return c.fail(protocol.ExitUsage, "usage: repo deps status <owner/name>")	81	return c.usage()
82	}	82	}
83	repo, code := resolveRepo(c, args[0], policy.CanRead)	83	repo, code := resolveRepo(c, args[0], policy.CanRead)
84	if code >= 0 {	84	if code >= 0 {

internal/control/diffcomment.go +2 −2

	@@ -143,7 +143,7 @@ func runMRThreads(c *Ctx, args []string) int {
143	return code	143	return code
144	}	144	}
145	if len(args) != 2 {	145	if len(args) != 2 {
146	return c.fail(protocol.ExitUsage, "usage: mr threads <owner/name> <n>")	146	return c.usage()
147	}	147	}
148	comments, err := c.Store.ListDiffComments(mr.ID, c.User.ID)	148	comments, err := c.Store.ListDiffComments(mr.ID, c.User.ID)
149	if err != nil {	149	if err != nil {
	@@ -202,7 +202,7 @@ func runMRThreads(c *Ctx, args []string) int {
202		202
203	func setThreadResolved(c *Ctx, args []string, resolved bool) int {	203	func setThreadResolved(c *Ctx, args []string, resolved bool) int {
204	if len(args) != 3 {	204	if len(args) != 3 {
205	return c.fail(protocol.ExitUsage, "usage: mr resolve\|unresolve <owner/name> <n> <thread-id>")	205	return c.usage()
206	}	206	}
207	repo, mr, code := mrRef(c, args[:2], policy.CanRead)	207	repo, mr, code := mrRef(c, args[:2], policy.CanRead)
208	if code >= 0 {	208	if code >= 0 {

internal/control/explore.go +3 −4

 		return code
 	}
 	if len(rest) != 0 {
-		return c.fail(protocol.ExitUsage, "usage: explore [--limit <n>] [--cursor <c>]")
+		return c.usage()
 	}
 	repos, err := c.Store.ListPublicRepos()
 	if err != nil {
 // release asset get writes an asset. The web's /archive route is the
 // same bytes with a Content-Disposition on them.
 func runRepoDownload(c *Ctx, args []string) int {
-	const usage = "repo download <owner/name> [--ref <r>] > repo.tar.gz"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--ref"}, MaxPos: -1, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--ref"}, MaxPos: -1, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	rest, ref := f.Pos, f.Value("--ref")
 	if len(rest) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, rest[0], policy.CanRead)
 	if code >= 0 {

internal/control/ghimport.go +1 −1

	@@ -149,7 +149,7 @@ func runImportIssues(c *Ctx, args []string) int {
149	}	149	}
150	path, from, apiBase, tokenStdin := f.pos(0), f.Value("--from"), f.Value("--api-base"), f.Has("--token-stdin")	150	path, from, apiBase, tokenStdin := f.pos(0), f.Value("--from"), f.Value("--api-base"), f.Has("--token-stdin")
151	if path == "" \|\| from == "" {	151	if path == "" \|\| from == "" {
152	return c.fail(protocol.ExitUsage, "usage: repo import-issues <owner/name> --from <owner/repo> [--token-stdin] [--api-base <url>]")	152	return c.usage()
153	}	153	}
154	if apiBase == "" {	154	if apiBase == "" {
155	apiBase = "https://api.github.com"	155	apiBase = "https://api.github.com"

internal/control/identity.go +4 −4

	@@ -51,7 +51,7 @@ func init() {
51		51
52	func runWhoami(c *Ctx, args []string) int {	52	func runWhoami(c *Ctx, args []string) int {
53	if len(args) != 0 {	53	if len(args) != 0 {
54	return c.fail(protocol.ExitUsage, "usage: whoami [--json]")	54	return c.usage()
55	}	55	}
56	type out struct {	56	type out struct {
57	Username string `json:"username"`	57	Username string `json:"username"`
	@@ -66,7 +66,7 @@ func runWhoami(c *Ctx, args []string) int {
66		66
67	func runKeysList(c *Ctx, args []string) int {	67	func runKeysList(c *Ctx, args []string) int {
68	if len(args) != 0 {	68	if len(args) != 0 {
69	return c.fail(protocol.ExitUsage, "usage: keys list [--json]")	69	return c.usage()
70	}	70	}
71	keys, err := c.Store.ListSSHKeys(c.User.ID)	71	keys, err := c.Store.ListSSHKeys(c.User.ID)
72	if err != nil {	72	if err != nil {
	@@ -161,7 +161,7 @@ func runKeysAdd(c *Ctx, args []string) int {
161		161
162	func runKeysLabel(c *Ctx, args []string) int {	162	func runKeysLabel(c *Ctx, args []string) int {
163	if len(args) < 1 \|\| len(args) > 2 {	163	if len(args) < 1 \|\| len(args) > 2 {
164	return c.fail(protocol.ExitUsage, "usage: keys label <fingerprint> [<text>]")	164	return c.usage()
165	}	165	}
166	label := ""	166	label := ""
167	if len(args) == 2 {	167	if len(args) == 2 {
	@@ -189,7 +189,7 @@ func runKeysLabel(c *Ctx, args []string) int {
189		189
190	func runKeysRemove(c *Ctx, args []string) int {	190	func runKeysRemove(c *Ctx, args []string) int {
191	if len(args) != 1 {	191	if len(args) != 1 {
192	return c.fail(protocol.ExitUsage, "usage: keys remove <fingerprint>")	192	return c.usage()
193	}	193	}
194	if err := c.Store.RemoveSSHKey(c.User.ID, args[0]); err != nil {	194	if err := c.Store.RemoveSSHKey(c.User.ID, args[0]); err != nil {
195	if errors.Is(err, store.ErrNotFound) {	195	if errors.Is(err, store.ErrNotFound) {

internal/control/import.go +2 −2

	@@ -40,11 +40,11 @@ func runRepoImport(c *Ctx, args []string) int {
40	}	40	}
41	path, from, private, tokenStdin := f.pos(0), f.Value("--from"), f.Has("--private"), f.Has("--token-stdin")	41	path, from, private, tokenStdin := f.pos(0), f.Value("--from"), f.Has("--private"), f.Has("--token-stdin")
42	if path == "" \|\| from == "" {	42	if path == "" \|\| from == "" {
43	return c.fail(protocol.ExitUsage, "usage: repo import <owner/name> --from <url> [--private] [--token-stdin]")	43	return c.usage()
44	}	44	}
45	owner, name, ok := strings.Cut(path, "/")	45	owner, name, ok := strings.Cut(path, "/")
46	if !ok {	46	if !ok {
47	return c.fail(protocol.ExitUsage, "usage: repo import <owner/name> --from <url>")	47	return c.usage()
48	}	48	}
49	if err := policy.ValidateName(name); err != nil {	49	if err := policy.ValidateName(name); err != nil {
50	return c.failInput(err)	50	return c.failInput(err)

internal/control/issue.go +8 −9

 	}
 	path, title, body, file, format := f.pos(0), f.Value("--title"), f.Value("--body"), f.Value("--file"), f.Value("--format")
 	if path == "" || title == "" {
-		return c.fail(protocol.ExitUsage, "usage: issue create <owner/name> --title <t> [--body <b> | --file -] [--format md|org]")
+		return c.usage()
 	}
 	fmtName, err := markupFormat(format)
 	if err != nil {
 	if code >= 0 {
 		return code
 	}
-	const usage = "usage: issue list <owner/name> [--state open|closed|all] [--label <l>] [--assignee <user>] [--author <user>] [--milestone <title>|none] [--search <text>] [--limit <n>] [--cursor <c>]"
 	f := store.IssueFilter{State: "open"}
-	fl, err := parseFlags(args, flagSpec{Values: []string{"--state", "--label", "--assignee", "--author", "--milestone", "--search"}, MaxPos: 1, Usage: usage})
+	fl, err := parseFlags(args, flagSpec{Values: []string{"--state", "--label", "--assignee", "--author", "--milestone", "--search"}, MaxPos: 1, Usage: c.Cmd.Usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 		}
 	}
 	if path == "" || (f.State != "open" && f.State != "closed" && f.State != "all") {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, path, policy.CanRead)
 	if code >= 0 {
 		return code
 	}
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: issue show <owner/name> <n>")
+		return c.usage()
 	}
 	comments, err := c.Store.ListIssueComments(issue.ID)
 	if err != nil {
 		return code
 	}
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: issue %s <owner/name> <n>", state)
+		return c.usage()
 	}
 	if code := authorOrWrite(c, repo, issue.Author, map[string]string{"open": "reopen", "closed": "close"}[state]+" this issue"); code >= 0 {
 		return code
 		return nil, nil, nil, nil, c.failInput(err)
 	}
 	if !haveTitle && !haveBody && fmtName == "" {
-		return nil, nil, nil, nil, c.fail(protocol.ExitUsage, "usage: %s edit <owner/name> <n> [--title <t>] [--body <b> | --file -] [--format md|org]", kind)
+		return nil, nil, nil, nil, c.usage()
 	}
 	if haveTitle {
 		if strings.TrimSpace(titleV) == "" {
 		return c.failInput(err)
 	}
 	if len(adds)+len(removes) == 0 {
-		return c.fail(protocol.ExitUsage, "usage: issue label <owner/name> <n> [--add <l>]... [--remove <l>]...")
+		return c.usage()
 	}
 	repo, issue, code := issueRef(c, rest, policy.CanWrite)
 	if code >= 0 {
 		return c.failInput(err)
 	}
 	if len(adds)+len(removes) == 0 {
-		return c.fail(protocol.ExitUsage, "usage: issue assign <owner/name> <n> [--add <user>]... [--remove <user>]...")
+		return c.usage()
 	}
 	repo, issue, code := issueRef(c, rest, policy.CanWrite)
 	if code >= 0 {

internal/control/label.go +4 −5

 func runLabelList(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: label list <owner/name>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanRead)
 	if code >= 0 {
 }
 func runLabelSet(c *Ctx, args []string) int {
-	const usage = "usage: label set <owner/name> <label> [--color #rrggbb|'']"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--color"}, MaxPos: -1, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--color"}, MaxPos: -1, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	rest := f.Pos
 	color, colorSet := strings.ToLower(f.Value("--color")), f.Has("--color")
 	if len(rest) != 2 {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	if colorSet && color != "" {
 		if !labelColorPat.MatchString(color) {
 func runLabelRemove(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: label remove <owner/name> <label>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanWrite)
 	if code >= 0 {

internal/control/migrate.go +1 −1

	@@ -81,7 +81,7 @@ type bundle struct {
81		81
82	func runAccountExport(c *Ctx, args []string) int {	82	func runAccountExport(c *Ctx, args []string) int {
83	if len(args) != 0 {	83	if len(args) != 0 {
84	return c.fail(protocol.ExitUsage, "usage: account export > bundle.json")	84	return c.usage()
85	}	85	}
86	b := bundle{Bundle: bundleVersion, Username: c.User.Username}	86	b := bundle{Bundle: bundleVersion, Username: c.User.Username}
87	b.Profile, _ = c.Store.OwnerProfile("user", c.User.ID)	87	b.Profile, _ = c.Store.OwnerProfile("user", c.User.ID)

internal/control/milestone.go +6 −6

	@@ -48,7 +48,7 @@ func runMilestoneCreate(c *Ctx, args []string) int {
48	}	48	}
49	path, title, description, due := f.pos(0), f.pos(1), f.Value("--description"), f.Value("--due")	49	path, title, description, due := f.pos(0), f.pos(1), f.Value("--description"), f.Value("--due")
50	if path == "" \|\| title == "" {	50	if path == "" \|\| title == "" {
51	return c.fail(protocol.ExitUsage, "usage: milestone create <owner/name> <title> [--description <d>] [--due YYYY-MM-DD]")	51	return c.usage()
52	}	52	}
53	if due != "" && !duePat.MatchString(due) {	53	if due != "" && !duePat.MatchString(due) {
54	return c.fail(protocol.ExitUsage, "--due must be YYYY-MM-DD")	54	return c.fail(protocol.ExitUsage, "--due must be YYYY-MM-DD")
	@@ -81,7 +81,7 @@ func runMilestoneList(c *Ctx, args []string) int {
81	state = f.Value("--state")	81	state = f.Value("--state")
82	}	82	}
83	if path == "" \|\| (state != "open" && state != "closed" && state != "all") {	83	if path == "" \|\| (state != "open" && state != "closed" && state != "all") {
84	return c.fail(protocol.ExitUsage, "usage: milestone list <owner/name> [--state open\|closed\|all]")	84	return c.usage()
85	}	85	}
86	repo, code := resolveRepo(c, path, policy.CanRead)	86	repo, code := resolveRepo(c, path, policy.CanRead)
87	if code >= 0 {	87	if code >= 0 {
	@@ -137,7 +137,7 @@ func setMilestoneState(c *Ctx, args []string, state string) int {
137	verb = "reopen"	137	verb = "reopen"
138	}	138	}
139	if len(args) != 2 {	139	if len(args) != 2 {
140	return c.fail(protocol.ExitUsage, "usage: milestone %s <owner/name> <title>", verb)	140	return c.usage()
141	}	141	}
142	repo, code := resolveRepo(c, args[0], policy.CanWrite)	142	repo, code := resolveRepo(c, args[0], policy.CanWrite)
143	if code >= 0 {	143	if code >= 0 {
	@@ -177,7 +177,7 @@ func runIssueMilestone(c *Ctx, args []string) int {
177	return code	177	return code
178	}	178	}
179	if len(args) != 3 {	179	if len(args) != 3 {
180	return c.fail(protocol.ExitUsage, "usage: issue milestone <owner/name> <n> <title\|none>")	180	return c.usage()
181	}	181	}
182	return setItemMilestone(c, repo, "issue", issue.Number, args[2], func(id int64) error {	182	return setItemMilestone(c, repo, "issue", issue.Number, args[2], func(id int64) error {
183	return c.Store.SetIssueMilestone(issue.ID, id)	183	return c.Store.SetIssueMilestone(issue.ID, id)
	@@ -193,7 +193,7 @@ func runMRMilestone(c *Ctx, args []string) int {
193	return code	193	return code
194	}	194	}
195	if len(args) != 3 {	195	if len(args) != 3 {
196	return c.fail(protocol.ExitUsage, "usage: mr milestone <owner/name> <n> <title\|none>")	196	return c.usage()
197	}	197	}
198	return setItemMilestone(c, repo, "mr", mr.Number, args[2], func(id int64) error {	198	return setItemMilestone(c, repo, "mr", mr.Number, args[2], func(id int64) error {
199	return c.Store.SetMRMilestone(mr.ID, id)	199	return c.Store.SetMRMilestone(mr.ID, id)
	@@ -232,7 +232,7 @@ func setItemMilestone(c *Ctx, repo store.Repo, noun string, number int64, title
232	// runIssueTemplates lists .gitbay/issue-template*.md at the default branch.	232	// runIssueTemplates lists .gitbay/issue-template*.md at the default branch.
233	func runIssueTemplates(c *Ctx, args []string) int {	233	func runIssueTemplates(c *Ctx, args []string) int {
234	if len(args) != 1 {	234	if len(args) != 1 {
235	return c.fail(protocol.ExitUsage, "usage: issue templates <owner/name>")	235	return c.usage()
236	}	236	}
237	repo, code := resolveRepo(c, args[0], policy.CanRead)	237	repo, code := resolveRepo(c, args[0], policy.CanRead)
238	if code >= 0 {	238	if code >= 0 {

internal/control/mirrorcmd.go +4 −4

	@@ -39,7 +39,7 @@ func runMirrorAdd(c *Ctx, args []string) int {
39	path, urlArg := f.pos(0), f.pos(1)	39	path, urlArg := f.pos(0), f.pos(1)
40	direction, username, tokenStdin := f.Value("--direction"), f.Value("--username"), f.Has("--token-stdin")	40	direction, username, tokenStdin := f.Value("--direction"), f.Value("--username"), f.Has("--token-stdin")
41	if path == "" \|\| urlArg == "" \|\| (direction != "push" && direction != "pull") {	41	if path == "" \|\| urlArg == "" \|\| (direction != "push" && direction != "pull") {
42	return c.fail(protocol.ExitUsage, "usage: repo mirror add <owner/name> <https-url> --direction push\|pull [--username <u>] [--token-stdin]")	42	return c.usage()
43	}	43	}
44	// The worker's git process dials this URL from the server: same SSRF	44	// The worker's git process dials this URL from the server: same SSRF
45	// surface as a webhook target, same rules.	45	// surface as a webhook target, same rules.
	@@ -76,7 +76,7 @@ func runMirrorAdd(c *Ctx, args []string) int {
76		76
77	func runMirrorList(c *Ctx, args []string) int {	77	func runMirrorList(c *Ctx, args []string) int {
78	if len(args) != 1 {	78	if len(args) != 1 {
79	return c.fail(protocol.ExitUsage, "usage: repo mirror list <owner/name>")	79	return c.usage()
80	}	80	}
81	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	81	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
82	if code >= 0 {	82	if code >= 0 {
	@@ -123,7 +123,7 @@ func orDash(s string) string {
123		123
124	func runMirrorRemove(c *Ctx, args []string) int {	124	func runMirrorRemove(c *Ctx, args []string) int {
125	if len(args) != 2 {	125	if len(args) != 2 {
126	return c.fail(protocol.ExitUsage, "usage: repo mirror remove <owner/name> <id>")	126	return c.usage()
127	}	127	}
128	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	128	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
129	if code >= 0 {	129	if code >= 0 {
	@@ -146,7 +146,7 @@ func runMirrorRemove(c *Ctx, args []string) int {
146		146
147	func runMirrorSync(c *Ctx, args []string) int {	147	func runMirrorSync(c *Ctx, args []string) int {
148	if len(args) != 1 {	148	if len(args) != 1 {
149	return c.fail(protocol.ExitUsage, "usage: repo mirror sync <owner/name>")	149	return c.usage()
150	}	150	}
151	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	151	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
152	if code >= 0 {	152	if code >= 0 {

internal/control/mr.go +19 −26

 	}
 	path, name := f.pos(0), f.Value("--name")
 	if path == "" {
-		return c.fail(protocol.ExitUsage, "usage: repo fork <owner/name> [--name <n>]")
+		return c.usage()
 	}
 	src, code := resolveRepo(c, path, policy.CanRead)
 	if code >= 0 {
 func runRequireApprovals(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: repo settings require-approvals <owner/name> <n>")
+		return c.usage()
 	}
 	n, err := strconv.Atoi(args[1])
 	if err != nil || n < 0 || n > 20 {
 func runRequireResolved(c *Ctx, args []string) int {
 	if len(args) != 2 || (args[1] != "on" && args[1] != "off") {
-		return c.fail(protocol.ExitUsage, "usage: repo settings require-resolved <owner/name> on|off")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runRequireCodeowners(c *Ctx, args []string) int {
 	if len(args) != 2 || (args[1] != "on" && args[1] != "off") {
-		return c.fail(protocol.ExitUsage, "usage: repo settings require-codeowners <owner/name> on|off")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runRequireChecks(c *Ctx, args []string) int {
 	if len(args) != 2 || (args[1] != "on" && args[1] != "off") {
-		return c.fail(protocol.ExitUsage, "usage: repo settings require-checks <owner/name> on|off")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runRequireMR(c *Ctx, args []string) int {
 	if len(args) != 2 || (args[1] != "on" && args[1] != "off") {
-		return c.fail(protocol.ExitUsage, "usage: repo settings require-mr <owner/name> on|off")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runRequireSigned(c *Ctx, args []string) int {
 	if len(args) != 2 || (args[1] != "on" && args[1] != "off") {
-		return c.fail(protocol.ExitUsage, "usage: repo settings require-signed <owner/name> on|off")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 	path, source, target := f.pos(0), f.Value("--source"), f.Value("--target")
 	title, body, file, format := f.Value("--title"), f.Value("--body"), f.Value("--file"), f.Value("--format")
 	if path == "" || source == "" || title == "" {
-		return c.fail(protocol.ExitUsage, "usage: mr create <target owner/name> --source [owner/name:]<branch> --target <branch> --title <t> [--draft]")
+		return c.usage()
 	}
 	fmtName, err := markupFormat(format)
 	if err != nil {
 	if code >= 0 {
 		return code
 	}
-	const usage = "usage: mr list <owner/name> [--state open|merged|closed|source_gone|all] [--author <user>] [--milestone <title>|none] [--search <text>] [--limit <n>] [--cursor <c>]"
 	f := store.MRFilter{State: "open"}
-	fl, err := parseFlags(args, flagSpec{Values: []string{"--state", "--author", "--milestone", "--search"}, MaxPos: 1, Usage: usage})
+	fl, err := parseFlags(args, flagSpec{Values: []string{"--state", "--author", "--milestone", "--search"}, MaxPos: 1, Usage: c.Cmd.Usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	}
 	valid := map[string]bool{"open": true, "merged": true, "closed": true, "source_gone": true, "all": true}
 	if path == "" || !valid[f.State] {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, path, policy.CanRead)
 	if code >= 0 {
 		return code
 	}
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: mr show <owner/name> <n>")
+		return c.usage()
 	}
 	comments, err := c.Store.ListMRComments(mr.ID)
 	if err != nil {
 // same repository.
 func runMRRetarget(c *Ctx, args []string) int {
 	if len(args) != 3 {
-		return c.fail(protocol.ExitUsage, "usage: mr retarget <owner/name> <n> <branch>")
+		return c.usage()
 	}
 	repo, mr, code := mrRef(c, args[:2], policy.CanRead)
 	if code >= 0 {
 			rest = append(rest, a)
 		}
 	}
-	const usage = "mr review <owner/name> <n> --approve|--request-changes|--comment|--discard"
 	if discard && verdict != "" {
 		return c.fail(protocol.ExitUsage, "--discard throws the batch away; it takes no verdict")
 	}
 	if verdict == "" && !discard {
-		return c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return c.usage()
 	}
 	repo, mr, code := mrRef(c, rest, policy.CanRead)
 	if code >= 0 {
 		return c.failInput(err)
 	}
 	if len(adds)+len(removes) == 0 {
-		return c.fail(protocol.ExitUsage, "usage: mr review request <owner/name> <n> [--add <user>]... [--remove <user>]...")
+		return c.usage()
 	}
 	repo, mr, code := mrRef(c, rest, policy.CanWrite)
 	if code >= 0 {
 func runMRReady(c *Ctx, args []string) int { return setMRDraft(c, args, false) }
 func setMRDraft(c *Ctx, args []string, draft bool) int {
-	verb := "ready"
-	if draft {
-		verb = "draft"
-	}
 	repo, mr, code := mrRef(c, args, policy.CanRead)
 	if code >= 0 {
 		return code
 		return code
 	}
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: mr %s <owner/name> <n>", verb)
+		return c.usage()
 	}
 	if code := authorOrWrite(c, repo, mr.Author, "change this merge request"); code >= 0 {
 		return code
 		return code
 	}
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: mr close <owner/name> <n>")
+		return c.usage()
 	}
 	if code := authorOrWrite(c, repo, mr.Author, "close this merge request"); code >= 0 {
 		return code
 		return code
 	}
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: mr revisions <owner/name> <n>")
+		return c.usage()
 	}
 	revs, err := mrRevisions(c, mr)
 	if err != nil {
 }
 func runMRRangeDiff(c *Ctx, args []string) int {
-	const usage = "mr range-diff <owner/name> <n> [--from <sha>] [--to <sha>]"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--from", "--to"}, MaxPos: 2, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--from", "--to"}, MaxPos: 2, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 		return code
 	}
 	if len(f.Pos) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return c.usage()
 	}
 	revs, err := mrRevisions(c, mr)
 	if err != nil {

internal/control/notifications.go +7 −9

 func runNotificationsSettingsShow(c *Ctx, args []string) int {
 	if len(args) != 0 {
-		return c.fail(protocol.ExitUsage, "usage: notifications settings show")
+		return c.usage()
 	}
 	return emitNotificationSettings(c)
 }
 // inbox is filed either way, the mail half consults it (#194).
 func runNotificationsSettingsMail(c *Ctx, args []string) int {
 	if len(args) != 1 || (args[0] != "on" && args[0] != "off") {
-		return c.fail(protocol.ExitUsage, "usage: notifications settings mail on|off")
+		return c.usage()
 	}
 	if err := c.Store.SetMailEnabled(c.User.ID, args[0] == "on"); err != nil {
 		return c.fail(protocol.ExitFailure, "%v", err)
 // delivered, so a grant or a revoke needs no watch row of its own (#194).
 func runNotificationsSettingsWatch(c *Ctx, args []string) int {
 	if len(args) != 1 || (args[0] != "on" && args[0] != "off") {
-		return c.fail(protocol.ExitUsage, "usage: notifications settings watch on|off")
+		return c.usage()
 	}
 	if err := c.Store.SetWatchEnabled(c.User.ID, args[0] == "on"); err != nil {
 		return c.fail(protocol.ExitFailure, "%v", err)
 const noticesDefaultLimit = 50
 func runNotificationsList(c *Ctx, args []string) int {
-	const usage = "notifications list [--all] [--limit <n>] [--cursor <c>]"
 	rest, p, code := parsePageFlags(c, args, "notifications", true)
 	if code >= 0 {
 		return code
 	}
-	fl, err := parseFlags(rest, flagSpec{Bools: []string{"--all"}, Usage: usage})
+	fl, err := parseFlags(rest, flagSpec{Bools: []string{"--all"}, Usage: c.Cmd.Usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 }
 func runNotificationsRead(c *Ctx, args []string) int {
-	const usage = "notifications read <id>... | --all"
+	fl, err := parseFlags(args, flagSpec{Bools: []string{"--all"}, MaxPos: -1, Usage: c.Cmd.Usage})
-	fl, err := parseFlags(args, flagSpec{Bools: []string{"--all"}, MaxPos: -1, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	// --all and a list of ids are two ways of saying which rows: taking
 	// both would leave which one won unstated.
 	if fl.Has("--all") == (len(fl.Pos) > 0) {
-		return c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return c.usage()
 	}
 	var ids []int64
 	for _, a := range fl.Pos {
 // same way.
 func setWatch(c *Ctx, args []string, verb, state string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: repo %s <owner/name>", verb)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanRead)
 	if code >= 0 {

internal/control/org.go +9 −9

	@@ -53,14 +53,14 @@ func orgAdmin(c *Ctx, name string) (store.Org, int) {
53	return org, c.fail(protocol.ExitFailure, "%v", err)	53	return org, c.fail(protocol.ExitFailure, "%v", err)
54	}	54	}
55	if role != "admin" {	55	if role != "admin" {
56	return org, c.fail(protocol.ExitDenied, "only admins of %s can do that", name)	56	return org, c.fail(protocol.ExitDenied, "only admins of %s can do that; ask one", name)
57	}	57	}
58	return org, -1	58	return org, -1
59	}	59	}
60		60
61	func runOrgCreate(c *Ctx, args []string) int {	61	func runOrgCreate(c *Ctx, args []string) int {
62	if len(args) != 1 {	62	if len(args) != 1 {
63	return c.fail(protocol.ExitUsage, "usage: org create <name>")	63	return c.usage()
64	}	64	}
65	if err := policy.ValidateOwnerName(args[0]); err != nil {	65	if err := policy.ValidateOwnerName(args[0]); err != nil {
66	return c.failInput(err)	66	return c.failInput(err)
	@@ -95,7 +95,7 @@ func runOrgList(c *Ctx, args []string) int {
95		95
96	func runOrgShow(c *Ctx, args []string) int {	96	func runOrgShow(c *Ctx, args []string) int {
97	if len(args) != 1 {	97	if len(args) != 1 {
98	return c.fail(protocol.ExitUsage, "usage: org show <name>")	98	return c.usage()
99	}	99	}
100	org, err := c.Store.OrgByName(args[0])	100	org, err := c.Store.OrgByName(args[0])
101	if errors.Is(err, store.ErrNotFound) {	101	if errors.Is(err, store.ErrNotFound) {
	@@ -130,7 +130,7 @@ func runOrgShow(c *Ctx, args []string) int {
130		130
131	func runOrgRename(c *Ctx, args []string) int {	131	func runOrgRename(c *Ctx, args []string) int {
132	if len(args) != 2 {	132	if len(args) != 2 {
133	return c.fail(protocol.ExitUsage, "usage: org rename <old> <new>")	133	return c.usage()
134	}	134	}
135	org, code := orgAdmin(c, args[0])	135	org, code := orgAdmin(c, args[0])
136	if code >= 0 {	136	if code >= 0 {
	@@ -170,11 +170,11 @@ func runOrgDelete(c *Ctx, args []string) int {
170	} else if name == "" {	170	} else if name == "" {
171	name = a	171	name = a
172	} else {	172	} else {
173	return c.fail(protocol.ExitUsage, "usage: org delete <name> --yes")	173	return c.usage()
174	}	174	}
175	}	175	}
176	if name == "" {	176	if name == "" {
177	return c.fail(protocol.ExitUsage, "usage: org delete <name> --yes")	177	return c.usage()
178	}	178	}
179	org, code := orgAdmin(c, name)	179	org, code := orgAdmin(c, name)
180	if code >= 0 {	180	if code >= 0 {
	@@ -201,7 +201,7 @@ func runOrgMembersAdd(c *Ctx, args []string) int {
201	role = f.Value("--role")	201	role = f.Value("--role")
202	}	202	}
203	if len(rest) != 2 \|\| (role != "member" && role != "admin") {	203	if len(rest) != 2 \|\| (role != "member" && role != "admin") {
204	return c.fail(protocol.ExitUsage, "usage: org members add <org> <user> [--role member\|admin]")	204	return c.usage()
205	}	205	}
206	org, code := orgAdmin(c, rest[0])	206	org, code := orgAdmin(c, rest[0])
207	if code >= 0 {	207	if code >= 0 {
	@@ -224,7 +224,7 @@ func runOrgMembersAdd(c *Ctx, args []string) int {
224		224
225	func runOrgMembersRemove(c *Ctx, args []string) int {	225	func runOrgMembersRemove(c *Ctx, args []string) int {
226	if len(args) != 2 {	226	if len(args) != 2 {
227	return c.fail(protocol.ExitUsage, "usage: org members remove <org> <user>")	227	return c.usage()
228	}	228	}
229	org, code := orgAdmin(c, args[0])	229	org, code := orgAdmin(c, args[0])
230	if code >= 0 {	230	if code >= 0 {
	@@ -250,7 +250,7 @@ func runOrgMembersRemove(c *Ctx, args []string) int {
250		250
251	func runOrgMembersList(c *Ctx, args []string) int {	251	func runOrgMembersList(c *Ctx, args []string) int {
252	if len(args) != 1 {	252	if len(args) != 1 {
253	return c.fail(protocol.ExitUsage, "usage: org members list <org>")	253	return c.usage()
254	}	254	}
255	return runOrgShow(c, args)	255	return runOrgShow(c, args)
256	}	256	}

internal/control/orglabel.go +9 −11

 		return org, nil, c.fail(protocol.ExitFailure, "%v", err)
 	}
 	if role == "" && len(readable) == 0 {
-		return org, nil, c.fail(protocol.ExitDenied, "labels and milestones of %s are visible to its members", name)
+		return org, nil, c.fail(protocol.ExitDenied, "labels and milestones of %s are visible to its members; ask an admin to add you", name)
 	}
 	return org, readable, -1
 }
 func runOrgLabelSet(c *Ctx, args []string) int {
-	const usage = "usage: org label set <org> <label> [--color rrggbb|'']"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--color"}, MaxPos: 2, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--color"}, MaxPos: 2, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	orgName, name := f.pos(0), f.pos(1)
 	color, colorSet := strings.ToLower(f.Value("--color")), f.Has("--color")
 	if orgName == "" || name == "" {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	if name == "" || len(name) > 50 {
 		return c.fail(protocol.ExitUsage, "a label is 1 to 50 characters")
 func runOrgLabelList(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: org label list <org>")
+		return c.usage()
 	}
 	org, readable, code := orgReader(c, args[0])
 	if code >= 0 {
 func runOrgLabelRemove(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: org label remove <org> <label>")
+		return c.usage()
 	}
 	org, code := orgAdmin(c, args[0])
 	if code >= 0 {
 }
 func runOrgMilestoneCreate(c *Ctx, args []string) int {
-	const usage = "usage: org milestone create <org> <title> [--description <d>] [--due YYYY-MM-DD]"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--description", "--due"}, MaxPos: 2, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--description", "--due"}, MaxPos: 2, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	orgName, title, description, due := f.pos(0), f.pos(1), f.Value("--description"), f.Value("--due")
 	if orgName == "" || title == "" {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	if due != "" && !duePat.MatchString(due) {
 		return c.fail(protocol.ExitUsage, "--due must be YYYY-MM-DD")
 		state = f.Value("--state")
 	}
 	if orgName == "" || (state != "open" && state != "closed" && state != "all") {
-		return c.fail(protocol.ExitUsage, "usage: org milestone list <org> [--state open|closed|all]")
+		return c.usage()
 	}
 	org, readable, code := orgReader(c, orgName)
 	if code >= 0 {
 		verb = "reopen"
 	}
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: org milestone %s <org> <title>", verb)
+		return c.usage()
 	}
 	org, code := orgAdmin(c, args[0])
 	if code >= 0 {

internal/control/pagescmd.go +4 −4

	@@ -70,7 +70,7 @@ func challengeRecord(domain, token string) (name, value string) {
70		70
71	func runDomainAdd(c *Ctx, args []string) int {	71	func runDomainAdd(c *Ctx, args []string) int {
72	if len(args) != 2 {	72	if len(args) != 2 {
73	return c.fail(protocol.ExitUsage, "usage: repo domain add <owner/name> <domain>")	73	return c.usage()
74	}	74	}
75	domain := strings.ToLower(args[1])	75	domain := strings.ToLower(args[1])
76	if err := validatePageDomain(c, domain); err != nil {	76	if err := validatePageDomain(c, domain); err != nil {
	@@ -121,7 +121,7 @@ func lookupTXT(name string) ([]string, error) {
121		121
122	func runDomainVerify(c *Ctx, args []string) int {	122	func runDomainVerify(c *Ctx, args []string) int {
123	if len(args) != 2 {	123	if len(args) != 2 {
124	return c.fail(protocol.ExitUsage, "usage: repo domain verify <owner/name> <domain>")	124	return c.usage()
125	}	125	}
126	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	126	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
127	if code >= 0 {	127	if code >= 0 {
	@@ -167,7 +167,7 @@ func runDomainVerify(c *Ctx, args []string) int {
167		167
168	func runDomainRemove(c *Ctx, args []string) int {	168	func runDomainRemove(c *Ctx, args []string) int {
169	if len(args) != 2 {	169	if len(args) != 2 {
170	return c.fail(protocol.ExitUsage, "usage: repo domain remove <owner/name> <domain>")	170	return c.usage()
171	}	171	}
172	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	172	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
173	if code >= 0 {	173	if code >= 0 {
	@@ -187,7 +187,7 @@ func runDomainRemove(c *Ctx, args []string) int {
187		187
188	func runDomainList(c *Ctx, args []string) int {	188	func runDomainList(c *Ctx, args []string) int {
189	if len(args) != 1 {	189	if len(args) != 1 {
190	return c.fail(protocol.ExitUsage, "usage: repo domain list <owner/name>")	190	return c.usage()
191	}	191	}
192	repo, code := resolveRepo(c, args[0], policy.CanRead)	192	repo, code := resolveRepo(c, args[0], policy.CanRead)
193	if code >= 0 {	193	if code >= 0 {

internal/control/profile.go +3 −5

 	if len(args) == 1 {
 		name = args[0]
 	} else if len(args) > 1 {
-		return c.fail(protocol.ExitUsage, "usage: profile show [name]")
+		return c.usage()
 	}
 	kind, id := "", int64(0)
 	if u, err := c.Store.UserByUsername(name); err == nil {
 		return c.failInput(err)
 	}
 	if len(rest) != 0 {
-		return c.fail(protocol.ExitUsage,
+		return c.usage()
-			"usage: profile set [--description <d>] [--website <url>] [--about <text>|--file -] [--about-format md|org] [--link <label|url>]...")
 	}
 	if e.empty() {
 		return c.fail(protocol.ExitUsage, "nothing to set: pass --description, --website, --about and/or --link")
 		return c.failInput(err)
 	}
 	if len(rest) != 1 {
-		return c.fail(protocol.ExitUsage,
+		return c.usage()
-			"usage: org profile <org> [--description <d>] [--website <url>] [--about <text>|--file -] [--about-format md|org] [--link <label|url>]...")
 	}
 	name := rest[0]
 	if e.empty() {

internal/control/quota.go +2 −2

	@@ -93,7 +93,7 @@ func runAdminUserLimits(c *Ctx, args []string) int {
93	return code	93	return code
94	}	94	}
95	if len(args) < 1 {	95	if len(args) < 1 {
96	return c.fail(protocol.ExitUsage, "usage: admin user limits <username> [--repos <n>\|default] [--bytes <n>\|default]")	96	return c.usage()
97	}	97	}
98	u, err := c.Store.UserByUsername(args[0])	98	u, err := c.Store.UserByUsername(args[0])
99	if err != nil {	99	if err != nil {
	@@ -116,7 +116,7 @@ func runAdminUserLimits(c *Ctx, args []string) int {
116	case "--bytes":	116	case "--bytes":
117	target = &l.Bytes	117	target = &l.Bytes
118	default:	118	default:
119	return c.fail(protocol.ExitUsage, "usage: admin user limits <username> [--repos <n>\|default] [--bytes <n>\|default]")	119	return c.usage()
120	}	120	}
121	if v == "default" {	121	if v == "default" {
122	*target = nil	122	*target = nil

internal/control/read.go +8 −11

 func runRepoRefs(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: repo refs <owner/name>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanRead)
 	if code >= 0 {
 const BlameSpan = 1000
 func runRepoBlame(c *Ctx, args []string) int {
-	const usage = "repo blame <owner/name> <path> [--ref <ref>] [--from <n>] [--to <n>]"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--ref", "--from", "--to"}, MaxPos: -1, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--ref", "--from", "--to"}, MaxPos: -1, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 		*dst = n
 	}
 	if len(rest) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, rest[0], policy.CanRead)
 	if code >= 0 {
 // off argv. Positionals are returned in order so each command can name them
 // in its own usage message.
 func readArgs(c *Ctx, args []string, usage string, maxPos int) (pos []string, ref string, code int) {
-	f, err := parseFlags(args, flagSpec{Values: []string{"--ref"}, MaxPos: maxPos, Usage: usage})
+	f, err := parseFlags(args, flagSpec{Values: []string{"--ref"}, MaxPos: maxPos, Usage: c.Cmd.Usage})
 	if err != nil {
 		return nil, "", c.fail(protocol.ExitUsage, "%v", err)
 	}
 }
 func runRepoTree(c *Ctx, args []string) int {
-	const usage = "repo tree <owner/name> [<path>] [--ref <ref>]"
+	pos, ref, code := readArgs(c, args, c.Cmd.Usage, 2)
-	pos, ref, code := readArgs(c, args, usage, 2)
 	if code >= 0 {
 		return code
 	}
 	if len(pos) == 0 {
-		return c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, pos[0], policy.CanRead)
 	if code >= 0 {
 }
 func runRepoCat(c *Ctx, args []string) int {
-	const usage = "repo cat <owner/name> <path> [--ref <ref>]"
+	pos, ref, code := readArgs(c, args, c.Cmd.Usage, 2)
-	pos, ref, code := readArgs(c, args, usage, 2)
 	if code >= 0 {
 		return code
 	}
 	if len(pos) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, pos[0], policy.CanRead)
 	if code >= 0 {

internal/control/register.go +5 −5

	@@ -45,7 +45,7 @@ func init() {
45		45
46	func runEmailList(c *Ctx, args []string) int {	46	func runEmailList(c *Ctx, args []string) int {
47	if len(args) != 0 {	47	if len(args) != 0 {
48	return c.fail(protocol.ExitUsage, "usage: email list [--json]")	48	return c.usage()
49	}	49	}
50	emails, err := c.Store.ListEmails(c.User.ID)	50	emails, err := c.Store.ListEmails(c.User.ID)
51	if err != nil {	51	if err != nil {
	@@ -89,7 +89,7 @@ func emailErr(c *Ctx, verb string, err error) int {
89		89
90	func runEmailRemove(c *Ctx, args []string) int {	90	func runEmailRemove(c *Ctx, args []string) int {
91	if len(args) != 1 {	91	if len(args) != 1 {
92	return c.fail(protocol.ExitUsage, "usage: email remove <address>")	92	return c.usage()
93	}	93	}
94	if err := c.Store.RemoveEmail(c.User.ID, args[0]); err != nil {	94	if err := c.Store.RemoveEmail(c.User.ID, args[0]); err != nil {
95	return emailErr(c, "removing address", err)	95	return emailErr(c, "removing address", err)
	@@ -101,7 +101,7 @@ func runEmailRemove(c *Ctx, args []string) int {
101		101
102	func runEmailPrimary(c *Ctx, args []string) int {	102	func runEmailPrimary(c *Ctx, args []string) int {
103	if len(args) != 1 {	103	if len(args) != 1 {
104	return c.fail(protocol.ExitUsage, "usage: email primary <address>")	104	return c.usage()
105	}	105	}
106	if err := c.Store.SetPrimaryEmail(c.User.ID, args[0]); err != nil {	106	if err := c.Store.SetPrimaryEmail(c.User.ID, args[0]); err != nil {
107	return emailErr(c, "setting primary", err)	107	return emailErr(c, "setting primary", err)
	@@ -136,7 +136,7 @@ const maxEmailAddsPerHour = 5
136		136
137	func runEmailAdd(c *Ctx, args []string) int {	137	func runEmailAdd(c *Ctx, args []string) int {
138	if len(args) != 1 \|\| !strings.Contains(args[0], "@") {	138	if len(args) != 1 \|\| !strings.Contains(args[0], "@") {
139	return c.fail(protocol.ExitUsage, "usage: email add <address>")	139	return c.usage()
140	}	140	}
141	if c.Cfg.Mail.SMTPHost == "" {	141	if c.Cfg.Mail.SMTPHost == "" {
142	return c.fail(protocol.ExitFailure, "this instance has no SMTP configured; ask an admin to verify the address (gitbayd admin email verify)")	142	return c.fail(protocol.ExitFailure, "this instance has no SMTP configured; ask an admin to verify the address (gitbayd admin email verify)")
	@@ -161,7 +161,7 @@ func runEmailAdd(c *Ctx, args []string) int {
161		161
162	func runEmailVerify(c *Ctx, args []string) int {	162	func runEmailVerify(c *Ctx, args []string) int {
163	if len(args) != 1 {	163	if len(args) != 1 {
164	return c.fail(protocol.ExitUsage, "usage: email verify <code>")	164	return c.usage()
165	}	165	}
166	hash := store.HashToken(args[0])	166	hash := store.HashToken(args[0])
167	address, err := c.Store.ConsumeEmailToken(c.User.ID, hash)	167	address, err := c.Store.ConsumeEmailToken(c.User.ID, hash)

internal/control/release.go +8 −10

 }
 func runReleaseCreate(c *Ctx, args []string) int {
-	const usage = "usage: release create <owner/name> <tag> [--title <t>] [--notes <n> | --file -] [--format md|org]"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--title", "--notes", "--file", "--format"}, MaxPos: 2, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--title", "--notes", "--file", "--format"}, MaxPos: 2, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	path, tag := f.pos(0), f.pos(1)
 	title, notes, file, format := f.Value("--title"), f.Value("--notes"), f.Value("--file"), f.Value("--format")
 	if path == "" || tag == "" {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	fmtName, err := markupFormat(format)
 	if err != nil {
 }
 func runReleaseEdit(c *Ctx, args []string) int {
-	const usage = "usage: release edit <owner/name> <tag> [--title <t>] [--notes <n> | --file -] [--format md|org]"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--title", "--notes", "--file", "--format"}, MaxPos: 2, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--title", "--notes", "--file", "--format"}, MaxPos: 2, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 		return c.failInput(err)
 	}
 	if path == "" || tag == "" || (!setTitle && !setNotes && fmtName == "") {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, path, policy.CanWrite)
 	if code >= 0 {
 func runReleaseList(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: release list <owner/name>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanRead)
 	if code >= 0 {
 func runAssetAdd(c *Ctx, args []string) int {
 	if len(args) != 3 {
-		return c.fail(protocol.ExitUsage, "usage: release asset add <owner/name> <tag> <filename> < file")
+		return c.usage()
 	}
 	repo, rel, code := releaseRef(c, args[:2], policy.CanWrite)
 	if code >= 0 {
 func runAssetGet(c *Ctx, args []string) int {
 	if len(args) != 3 {
-		return c.fail(protocol.ExitUsage, "usage: release asset get <owner/name> <tag> <filename> > file")
+		return c.usage()
 	}
 	repo, rel, code := releaseRef(c, args[:2], policy.CanRead)
 	if code >= 0 {
 func runAssetRemove(c *Ctx, args []string) int {
 	if len(args) != 3 {
-		return c.fail(protocol.ExitUsage, "usage: release asset remove <owner/name> <tag> <filename>")
+		return c.usage()
 	}
 	repo, rel, code := releaseRef(c, args[:2], policy.CanWrite)
 	if code >= 0 {

internal/control/repo.go +32 −38

 // stay available so an archived repo can be managed and unarchived.
 func refuseArchived(c *Ctx, repo store.Repo) int {
 	if repo.Settings.Archived {
-		return c.fail(protocol.ExitDenied, "%s is archived and read-only", repo.Path())
+		return c.fail(protocol.ExitDenied, "%s is archived and read-only; unarchive it first", repo.Path())
 	}
 	return -1
 }
 			// Invisible repos 404, per the enumeration rule.
 			return repo, c.fail(protocol.ExitNotFound, "repository %s not found", path)
 		}
-		return repo, c.fail(protocol.ExitDenied, "permission denied on %s", path)
+		return repo, c.fail(protocol.ExitDenied, "permission denied on %s; ask its owner for access", path)
 	}
 	return repo, -1
 }
 	}
 	owner, name, ok := strings.Cut(path, "/")
 	if !ok {
-		return c.fail(protocol.ExitUsage, "usage: repo create <owner/name> [--private]")
+		return c.usage()
 	}
 	if err := policyValidateRepoName(name); err != nil {
 		return c.failInput(err)
 		return code
 	}
 	if len(args) != 0 {
-		return c.fail(protocol.ExitUsage, "usage: repo list [--limit <n>] [--cursor <c>]")
+		return c.usage()
 	}
 	repos, err := c.Store.ListReposForUser(c.User.ID, p.queryLimit(), p.key)
 	if err != nil {
 func runRepoShow(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: repo show <owner/name>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanRead)
 	if code >= 0 {
 func runRepoTransfer(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: repo transfer <owner/name> <new-owner>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runRepoRename(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: repo rename <owner/name> <new-name>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 		} else if path == "" {
 			path = a
 		} else {
-			return c.fail(protocol.ExitUsage, "usage: repo delete <owner/name> --yes")
+			return c.usage()
 		}
 	}
 	if path == "" {
-		return c.fail(protocol.ExitUsage, "usage: repo delete <owner/name> --yes")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, path, policy.CanAdmin)
 	if code >= 0 {
 func runAccessGrant(c *Ctx, args []string) int {
 	if len(args) != 3 || !slices.Contains([]string{"read", "write", "admin"}, args[2]) {
-		return c.fail(protocol.ExitUsage, "usage: repo access grant <owner/name> <user> read|write|admin")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runAccessRevoke(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: repo access revoke <owner/name> <user>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runAccessList(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: repo access list <owner/name>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runSettingsShow(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: repo settings show <owner/name>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runSetDescription(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: repo settings description <owner/name> <text>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runSetDefaultBranch(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: repo settings default-branch <owner/name> <branch>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runSetWebsite(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: repo settings website <owner/name> <url>")
+		return c.usage()
 	}
 	site := strings.TrimSpace(args[1])
 	if err := validateWebsite(site); err != nil {
 func runSetVisibility(c *Ctx, args []string) int {
 	if len(args) != 2 || (args[1] != "public" && args[1] != "private") {
-		return c.fail(protocol.ExitUsage, "usage: repo settings visibility <owner/name> public|private")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runGitDaemon(c *Ctx, args []string) int {
 	if len(args) != 2 || (args[1] != "on" && args[1] != "off") {
-		return c.fail(protocol.ExitUsage, "usage: repo settings git-daemon <owner/name> on|off")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runUnarchive(c *Ctx, args []string) int { return setArchived(c, args, false) }
 func setArchived(c *Ctx, args []string, archived bool) int {
-	verb := "archive"
-	if !archived {
-		verb = "unarchive"
-	}
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: repo %s <owner/name>", verb)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runTopicsList(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: repo topics <owner/name>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanRead)
 	if code >= 0 {
 func runTopicsRemove(c *Ctx, args []string) int { return editTopics(c, args, false) }
 func editTopics(c *Ctx, args []string, add bool) int {
-	verb := "add"
-	if !add {
-		verb = "remove"
-	}
 	if len(args) < 2 {
-		return c.fail(protocol.ExitUsage, "usage: repo topics %s <owner/name> <topic>...", verb)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 		return c.fail(protocol.ExitFailure, "%v", err)
 	}
 	return c.emit(now, func(w io.Writer) {
-		fmt.Fprintf(w, "topics on %s: %s\n", repo.Path(), strings.Join(now, ", "))
+		for _, t := range now {
+			fmt.Fprintln(w, t)
+		}
 	})
 }
 // and topics of every repository the caller can see.
 func runRepoSearch(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: repo search <query>")
+		return c.usage()
 	}
 	if err := validQuery(args[0]); err != nil {
 		return c.failInput(err)
 	}
 	path, query, ref := f.pos(0), f.pos(1), f.Value("--ref")
 	if path == "" || query == "" {
-		return c.fail(protocol.ExitUsage, "usage: repo grep <owner/name> <query> [--ref <ref>]")
+		return c.usage()
 	}
 	if err := validQuery(query); err != nil {
 		return c.failInput(err)
 		verb = "unpin"
 	}
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: repo %s <owner/name>", verb)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanRead)
 	if code >= 0 {
 		verb = "unbookmark"
 	}
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: repo %s <owner/name>", verb)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanRead)
 	if code >= 0 {
 func runRepoBookmarks(c *Ctx, args []string) int {
 	if len(args) != 0 {
-		return c.fail(protocol.ExitUsage, "usage: repo bookmarks")
+		return c.usage()
 	}
 	repos, err := c.Store.ListBookmarks(c.User.ID)
 	if err != nil {
 func setProtectTag(c *Ctx, args []string, protect bool) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: repo settings protect-tag|unprotect-tag <owner/name> <glob>")
+		return c.usage()
 	}
 	glob := args[1]
 	if _, err := path.Match(glob, "x"); err != nil || glob == "" {
 func setProtect(c *Ctx, args []string, protect bool) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: repo settings protect|unprotect <owner/name> <branch>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
 	if code >= 0 {
 func runRepoDiff(c *Ctx, args []string) int {
 	f, err := parseFlags(args, flagSpec{MaxPos: 3, Usage: "repo diff <owner/name> <base> <head>"})
 	if err != nil || len(f.Pos) != 3 {
-		return c.fail(protocol.ExitUsage, "usage: repo diff <owner/name> <base> <head>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, f.pos(0), policy.CanRead)
 	if code >= 0 {

internal/control/runnerrepo.go +3 −3

	@@ -33,7 +33,7 @@ func init() {
33	func runRepoRunnerAdd(c *Ctx, args []string) int {	33	func runRepoRunnerAdd(c *Ctx, args []string) int {
34	f, err := parseFlags(args, flagSpec{MaxPos: 1, Usage: "repo runner add <owner/name> < key.pub"})	34	f, err := parseFlags(args, flagSpec{MaxPos: 1, Usage: "repo runner add <owner/name> < key.pub"})
35	if err != nil \|\| len(f.Pos) != 1 {	35	if err != nil \|\| len(f.Pos) != 1 {
36	return c.fail(protocol.ExitUsage, "usage: repo runner add <owner/name> < key.pub")	36	return c.usage()
37	}	37	}
38	repo, code := resolveRepo(c, f.Pos[0], policy.CanAdmin)	38	repo, code := resolveRepo(c, f.Pos[0], policy.CanAdmin)
39	if code >= 0 {	39	if code >= 0 {
	@@ -95,7 +95,7 @@ func runRepoRunnerAdd(c *Ctx, args []string) int {
95		95
96	func runRepoRunnerList(c *Ctx, args []string) int {	96	func runRepoRunnerList(c *Ctx, args []string) int {
97	if len(args) != 1 {	97	if len(args) != 1 {
98	return c.fail(protocol.ExitUsage, "usage: repo runner list <owner/name>")	98	return c.usage()
99	}	99	}
100	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	100	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
101	if code >= 0 {	101	if code >= 0 {
	@@ -125,7 +125,7 @@ func runRepoRunnerList(c *Ctx, args []string) int {
125		125
126	func runRepoRunnerRemove(c *Ctx, args []string) int {	126	func runRepoRunnerRemove(c *Ctx, args []string) int {
127	if len(args) != 2 {	127	if len(args) != 2 {
128	return c.fail(protocol.ExitUsage, "usage: repo runner remove <owner/name> <fingerprint>")	128	return c.usage()
129	}	129	}
130	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	130	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
131	if code >= 0 {	131	if code >= 0 {

internal/control/search.go +2 −3

 }
 func runSearch(c *Ctx, args []string) int {
-	const usage = "search <query> [--kind repo|issue|mr]"
+	f, err := parseFlags(args, flagSpec{Multi: []string{"--kind"}, MaxPos: 1, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Multi: []string{"--kind"}, MaxPos: 1, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	if len(f.Pos) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return c.usage()
 	}
 	if err := validQuery(f.Pos[0]); err != nil {
 		return c.failInput(err)

internal/control/sig.go +4 −5

 func runPGPAdd(c *Ctx, args []string) int {
 	if len(args) != 0 {
-		return c.fail(protocol.ExitUsage, "usage: pgp add < key.asc")
+		return c.usage()
 	}
 	raw, err := io.ReadAll(io.LimitReader(c.Stdin, 1<<20))
 	if err != nil {
 func runPGPRemove(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: pgp remove <fingerprint>")
+		return c.usage()
 	}
 	if err := c.Store.RemovePGPKey(c.User.ID, args[0]); err != nil {
 		if errors.Is(err, store.ErrNotFound) {
 		limit = n
 	}
 	if path == "" {
-		return c.fail(protocol.ExitUsage, "usage: repo log <owner/name> [--ref <r>] [--limit n] [--path <file>]")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, path, policy.CanRead)
 	if code >= 0 {
 // statuses, and its patch. The web's commit page read these straight from
 // git, which is why no other surface could open a commit.
 func runRepoCommit(c *Ctx, args []string) int {
-	const usage = "repo commit <owner/name> <sha>"
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: %s", usage)
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanRead)
 	if code >= 0 {

internal/control/snippet.go +11 −13

 		return sn, c.fail(protocol.ExitNotFound, "no snippet %q", id)
 	}
 	if write && !policy.CanWriteSnippet(c.User, sn) {
-		return sn, c.fail(protocol.ExitDenied, "snippet %s belongs to %s", id, sn.OwnerName)
+		return sn, c.fail(protocol.ExitDenied, "snippet %s belongs to %s; only they can change it", id, sn.OwnerName)
 	}
 	return sn, -1
 }
 }
 func runSnippetCreate(c *Ctx, args []string) int {
-	const usage = "usage: snippet create <filename> [--description <d>] [--visibility public|unlisted|private] < file"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--description", "--visibility"}, MaxPos: 1, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--description", "--visibility"}, MaxPos: 1, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	name := f.pos(0)
 	if name == "" {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	if code := checkSnippetFileName(c, name); code >= 0 {
 		return code
 func runSnippetShow(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: snippet show <id>")
+		return c.usage()
 	}
 	sn, code := snippetRef(c, args[0], false)
 	if code >= 0 {
 		return code
 	}
 	if len(rest) > 1 {
-		return c.fail(protocol.ExitUsage, "usage: snippet list [<owner>] [--limit n] [--cursor c]")
+		return c.usage()
 	}
 	owner := c.User
 	if len(rest) == 1 {
 }
 func runSnippetEdit(c *Ctx, args []string) int {
-	const usage = "usage: snippet edit <id> [--description <d>] [--visibility public|unlisted|private]"
+	f, err := parseFlags(args, flagSpec{Values: []string{"--description", "--visibility"}, MaxPos: 1, Usage: c.Cmd.Usage})
-	f, err := parseFlags(args, flagSpec{Values: []string{"--description", "--visibility"}, MaxPos: 1, Usage: usage})
 	if err != nil {
 		return c.fail(protocol.ExitUsage, "%v", err)
 	}
 	if f.pos(0) == "" || (!f.Has("--description") && !f.Has("--visibility")) {
-		return c.fail(protocol.ExitUsage, usage)
+		return c.usage()
 	}
 	sn, code := snippetRef(c, f.pos(0), true)
 	if code >= 0 {
 func runSnippetDelete(c *Ctx, args []string) int {
 	if len(args) != 1 {
-		return c.fail(protocol.ExitUsage, "usage: snippet delete <id>")
+		return c.usage()
 	}
 	sn, code := snippetRef(c, args[0], true)
 	if code >= 0 {
 func runSnippetFileSet(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: snippet file set <id> <filename> < file")
+		return c.usage()
 	}
 	sn, code := snippetRef(c, args[0], true)
 	if code >= 0 {
 func runSnippetFileGet(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: snippet file get <id> <filename> > file")
+		return c.usage()
 	}
 	sn, code := snippetRef(c, args[0], false)
 	if code >= 0 {
 func runSnippetFileRemove(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: snippet file remove <id> <filename>")
+		return c.usage()
 	}
 	sn, code := snippetRef(c, args[0], true)
 	if code >= 0 {

internal/control/status.go +4 −8

 		}
 	}
 	if path == "" || sha == "" || context == "" || !validStatusState[state] {
-		return c.fail(protocol.ExitUsage, "usage: status set <owner/name> <sha> --context <c> --state pending|success|failure|error")
+		return c.usage()
 	}
 	if url != "" && !strings.HasPrefix(url, "https://") && !strings.HasPrefix(url, "http://") {
 		return c.fail(protocol.ExitUsage, "--url must be http(s)")
 func runStatusList(c *Ctx, args []string) int {
 	if len(args) != 2 {
-		return c.fail(protocol.ExitUsage, "usage: status list <owner/name> <sha>")
+		return c.usage()
 	}
 	repo, code := resolveRepo(c, args[0], policy.CanRead)
 	if code >= 0 {
 		Statuses []out  `json:"statuses"`
 	}{full, combinedOf(statuses), ds}
 	return c.emit(d, func(w io.Writer) {
-		fmt.Fprintf(w, "%.10s: %s\n", d.SHA, orNone(d.Combined))
+		fmt.Fprintf(w, "combined\t%s\t%.10s\n", orNone(d.Combined), d.SHA)
 		for _, x := range ds {
-			extra := ""
+			fmt.Fprintf(w, "%s\t%s\t%s\n", x.Context, x.State, x.Description)
-			if x.Description != "" {
-				extra = "\t" + x.Description
-			}
-			fmt.Fprintf(w, "  %s\t%s%s\n", x.Context, x.State, extra)
 		}
 	})
 }

internal/control/teams.go +10 −10

	@@ -53,7 +53,7 @@ func orgAdminRef(c *Ctx, name string) (store.Org, int) {
53	return org, c.fail(protocol.ExitFailure, "%v", err)	53	return org, c.fail(protocol.ExitFailure, "%v", err)
54	}	54	}
55	if role != "admin" {	55	if role != "admin" {
56	return org, c.fail(protocol.ExitDenied, "only admins of %s can manage teams", name)	56	return org, c.fail(protocol.ExitDenied, "only admins of %s can manage teams; ask one to add you", name)
57	}	57	}
58	return org, -1	58	return org, -1
59	}	59	}
	@@ -71,7 +71,7 @@ func orgMemberRef(c *Ctx, name string) (store.Org, int) {
71	return org, c.fail(protocol.ExitFailure, "%v", err)	71	return org, c.fail(protocol.ExitFailure, "%v", err)
72	}	72	}
73	if role == "" {	73	if role == "" {
74	return org, c.fail(protocol.ExitDenied, "teams of %s are visible to its members", name)	74	return org, c.fail(protocol.ExitDenied, "teams of %s are visible to its members; ask an admin to add you", name)
75	}	75	}
76	return org, -1	76	return org, -1
77	}	77	}
	@@ -89,7 +89,7 @@ func teamRef(c *Ctx, org store.Org, name string) (store.Team, int) {
89		89
90	func runTeamCreate(c *Ctx, args []string) int {	90	func runTeamCreate(c *Ctx, args []string) int {
91	if len(args) != 2 {	91	if len(args) != 2 {
92	return c.fail(protocol.ExitUsage, "usage: org team create <org> <team>")	92	return c.usage()
93	}	93	}
94	org, code := orgAdminRef(c, args[0])	94	org, code := orgAdminRef(c, args[0])
95	if code >= 0 {	95	if code >= 0 {
	@@ -108,7 +108,7 @@ func runTeamCreate(c *Ctx, args []string) int {
108		108
109	func runTeamDelete(c *Ctx, args []string) int {	109	func runTeamDelete(c *Ctx, args []string) int {
110	if len(args) != 2 {	110	if len(args) != 2 {
111	return c.fail(protocol.ExitUsage, "usage: org team delete <org> <team>")	111	return c.usage()
112	}	112	}
113	org, code := orgAdminRef(c, args[0])	113	org, code := orgAdminRef(c, args[0])
114	if code >= 0 {	114	if code >= 0 {
	@@ -128,7 +128,7 @@ func runTeamDelete(c *Ctx, args []string) int {
128		128
129	func runTeamList(c *Ctx, args []string) int {	129	func runTeamList(c *Ctx, args []string) int {
130	if len(args) != 1 {	130	if len(args) != 1 {
131	return c.fail(protocol.ExitUsage, "usage: org team list <org>")	131	return c.usage()
132	}	132	}
133	org, code := orgMemberRef(c, args[0])	133	org, code := orgMemberRef(c, args[0])
134	if code >= 0 {	134	if code >= 0 {
	@@ -151,7 +151,7 @@ func runTeamList(c *Ctx, args []string) int {
151		151
152	func runTeamShow(c *Ctx, args []string) int {	152	func runTeamShow(c *Ctx, args []string) int {
153	if len(args) != 2 {	153	if len(args) != 2 {
154	return c.fail(protocol.ExitUsage, "usage: org team show <org> <team>")	154	return c.usage()
155	}	155	}
156	org, code := orgMemberRef(c, args[0])	156	org, code := orgMemberRef(c, args[0])
157	if code >= 0 {	157	if code >= 0 {
	@@ -191,7 +191,7 @@ func editTeamMembers(c *Ctx, args []string, add bool) int {
191	verb = "remove"	191	verb = "remove"
192	}	192	}
193	if len(args) < 3 {	193	if len(args) < 3 {
194	return c.fail(protocol.ExitUsage, "usage: org team %s <org> <team> <user>...", verb)	194	return c.usage()
195	}	195	}
196	org, code := orgAdminRef(c, args[0])	196	org, code := orgAdminRef(c, args[0])
197	if code >= 0 {	197	if code >= 0 {
	@@ -233,7 +233,7 @@ func editTeamMembers(c *Ctx, args []string, add bool) int {
233		233
234	func runTeamGrant(c *Ctx, args []string) int {	234	func runTeamGrant(c *Ctx, args []string) int {
235	if len(args) != 4 \|\| !slices.Contains([]string{"read", "write", "admin"}, args[3]) {	235	if len(args) != 4 \|\| !slices.Contains([]string{"read", "write", "admin"}, args[3]) {
236	return c.fail(protocol.ExitUsage, "usage: org team grant <org> <team> <owner/name> read\|write\|admin")	236	return c.usage()
237	}	237	}
238	org, code := orgAdminRef(c, args[0])	238	org, code := orgAdminRef(c, args[0])
239	if code >= 0 {	239	if code >= 0 {
	@@ -257,7 +257,7 @@ func runTeamGrant(c *Ctx, args []string) int {
257		257
258	func runTeamRevoke(c *Ctx, args []string) int {	258	func runTeamRevoke(c *Ctx, args []string) int {
259	if len(args) != 3 {	259	if len(args) != 3 {
260	return c.fail(protocol.ExitUsage, "usage: org team revoke <org> <team> <owner/name>")	260	return c.usage()
261	}	261	}
262	org, code := orgAdminRef(c, args[0])	262	org, code := orgAdminRef(c, args[0])
263	if code >= 0 {	263	if code >= 0 {
	@@ -284,7 +284,7 @@ func runTeamRevoke(c *Ctx, args []string) int {
284		284
285	func runOrgMembersRole(c *Ctx, args []string) int {	285	func runOrgMembersRole(c *Ctx, args []string) int {
286	if len(args) != 2 \|\| !slices.Contains([]string{"write", "read", "none"}, args[1]) {	286	if len(args) != 2 \|\| !slices.Contains([]string{"write", "read", "none"}, args[1]) {
287	return c.fail(protocol.ExitUsage, "usage: org settings members-role <org> write\|read\|none")	287	return c.usage()
288	}	288	}
289	org, code := orgAdminRef(c, args[0])	289	org, code := orgAdminRef(c, args[0])
290	if code >= 0 {	290	if code >= 0 {

internal/control/token.go +2 −2

	@@ -48,7 +48,7 @@ func runTokenCreate(c *Ctx, args []string) int {
48	scope = f.Value("--scope")	48	scope = f.Value("--scope")
49	}	49	}
50	if name == "" \|\| (scope != "full" && scope != "read") {	50	if name == "" \|\| (scope != "full" && scope != "read") {
51	return c.fail(protocol.ExitUsage, "usage: token create --name <n> [--scope full\|read] [--ttl 30d]")	51	return c.usage()
52	}	52	}
53	var expires *time.Time	53	var expires *time.Time
54	if ttl != "" {	54	if ttl != "" {
	@@ -108,7 +108,7 @@ func runTokenList(c *Ctx, args []string) int {
108		108
109	func runTokenRevoke(c *Ctx, args []string) int {	109	func runTokenRevoke(c *Ctx, args []string) int {
110	if len(args) != 1 {	110	if len(args) != 1 {
111	return c.fail(protocol.ExitUsage, "usage: token revoke <name>")	111	return c.usage()
112	}	112	}
113	if err := c.Store.RevokeAPIToken(c.User.ID, args[0]); err != nil {	113	if err := c.Store.RevokeAPIToken(c.User.ID, args[0]); err != nil {
114	if errors.Is(err, store.ErrNotFound) {	114	if errors.Is(err, store.ErrNotFound) {

internal/control/web.go +3 −3

	@@ -26,7 +26,7 @@ func init() {
26		26
27	func runWebSessionsList(c *Ctx, args []string) int {	27	func runWebSessionsList(c *Ctx, args []string) int {
28	if len(args) != 0 {	28	if len(args) != 0 {
29	return c.fail(protocol.ExitUsage, "usage: web sessions list")	29	return c.usage()
30	}	30	}
31	sessions, err := c.Store.ListWebSessions(c.User.ID)	31	sessions, err := c.Store.ListWebSessions(c.User.ID)
32	if err != nil {	32	if err != nil {
	@@ -41,7 +41,7 @@ func runWebSessionsList(c *Ctx, args []string) int {
41		41
42	func runWebSessionsRevoke(c *Ctx, args []string) int {	42	func runWebSessionsRevoke(c *Ctx, args []string) int {
43	if len(args) != 1 {	43	if len(args) != 1 {
44	return c.fail(protocol.ExitUsage, "usage: web sessions revoke <id>\|--all")	44	return c.usage()
45	}	45	}
46	if args[0] == "--all" {	46	if args[0] == "--all" {
47	n, err := c.Store.RevokeAllWebSessions(c.User.ID)	47	n, err := c.Store.RevokeAllWebSessions(c.User.ID)
	@@ -65,7 +65,7 @@ func runWebSessionsRevoke(c *Ctx, args []string) int {
65		65
66	func runWebLogin(c *Ctx, args []string) int {	66	func runWebLogin(c *Ctx, args []string) int {
67	if len(args) != 0 {	67	if len(args) != 0 {
68	return c.fail(protocol.ExitUsage, "usage: web login [--json]")	68	return c.usage()
69	}	69	}
70	if c.Cfg.Web.Mode != "accounts" {	70	if c.Cfg.Web.Mode != "accounts" {
71	return c.fail(protocol.ExitDenied,	71	return c.fail(protocol.ExitDenied,

internal/control/webhook.go +5 −5

	@@ -40,7 +40,7 @@ func runWebhookAdd(c *Ctx, args []string) int {
40	events = f.Value("--events")	40	events = f.Value("--events")
41	}	41	}
42	if path == "" \|\| url == "" {	42	if path == "" \|\| url == "" {
43	return c.fail(protocol.ExitUsage, "usage: webhook add <owner/name> <url> [--secret <s>] [--events <k1,k2>\|*]")	43	return c.usage()
44	}	44	}
45	repo, code := resolveRepo(c, path, policy.CanAdmin)	45	repo, code := resolveRepo(c, path, policy.CanAdmin)
46	if code >= 0 {	46	if code >= 0 {
	@@ -68,7 +68,7 @@ func runWebhookAdd(c *Ctx, args []string) int {
68		68
69	func runWebhookList(c *Ctx, args []string) int {	69	func runWebhookList(c *Ctx, args []string) int {
70	if len(args) != 1 {	70	if len(args) != 1 {
71	return c.fail(protocol.ExitUsage, "usage: webhook list <owner/name>")	71	return c.usage()
72	}	72	}
73	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	73	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
74	if code >= 0 {	74	if code >= 0 {
	@@ -98,7 +98,7 @@ func runWebhookList(c *Ctx, args []string) int {
98		98
99	func runWebhookRemove(c *Ctx, args []string) int {	99	func runWebhookRemove(c *Ctx, args []string) int {
100	if len(args) != 2 {	100	if len(args) != 2 {
101	return c.fail(protocol.ExitUsage, "usage: webhook remove <owner/name> <id>")	101	return c.usage()
102	}	102	}
103	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	103	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
104	if code >= 0 {	104	if code >= 0 {
	@@ -133,7 +133,7 @@ func runWebhookDeliveries(c *Ctx, args []string) int {
133	limit = n	133	limit = n
134	}	134	}
135	if path == "" {	135	if path == "" {
136	return c.fail(protocol.ExitUsage, "usage: webhook deliveries <owner/name> [--limit n]")	136	return c.usage()
137	}	137	}
138	repo, code := resolveRepo(c, path, policy.CanAdmin)	138	repo, code := resolveRepo(c, path, policy.CanAdmin)
139	if code >= 0 {	139	if code >= 0 {
	@@ -169,7 +169,7 @@ func runWebhookDeliveries(c *Ctx, args []string) int {
169		169
170	func runWebhookRedeliver(c *Ctx, args []string) int {	170	func runWebhookRedeliver(c *Ctx, args []string) int {
171	if len(args) != 2 {	171	if len(args) != 2 {
172	return c.fail(protocol.ExitUsage, "usage: webhook redeliver <owner/name> <delivery-id>")	172	return c.usage()
173	}	173	}
174	repo, code := resolveRepo(c, args[0], policy.CanAdmin)	174	repo, code := resolveRepo(c, args[0], policy.CanAdmin)
175	if code >= 0 {	175	if code >= 0 {

internal/control/wiki.go +2 −2

	@@ -79,7 +79,7 @@ func wikiPages(dir, branch string) []string {
79		79
80	func runWikiList(c *Ctx, args []string) int {	80	func runWikiList(c *Ctx, args []string) int {
81	if len(args) != 1 {	81	if len(args) != 1 {
82	return c.fail(protocol.ExitUsage, "usage: wiki list <owner/name>")	82	return c.usage()
83	}	83	}
84	repo, dir, branch, code := wikiDir(c, args[0])	84	repo, dir, branch, code := wikiDir(c, args[0])
85	if code >= 0 {	85	if code >= 0 {
	@@ -120,7 +120,7 @@ func wikiHome(pages []string) string {
120		120
121	func runWikiShow(c *Ctx, args []string) int {	121	func runWikiShow(c *Ctx, args []string) int {
122	if len(args) < 1 \|\| len(args) > 2 {	122	if len(args) < 1 \|\| len(args) > 2 {
123	return c.fail(protocol.ExitUsage, "usage: wiki show <owner/name> [<page>]")	123	return c.usage()
124	}	124	}
125	repo, dir, branch, code := wikiDir(c, args[0])	125	repo, dir, branch, code := wikiDir(c, args[0])
126	if code >= 0 {	126	if code >= 0 {

CLI output sweep (#183) !388