fix: accurate --deployment help, aliases, and --list for generate-docs

cmd/lk/agent.go

@@ -202,6 +202,19 @@ var (
 		Aliases:  []string{"d"},
 	}
 
+	deleteDeploymentFlag = &cli.StringFlag{
+		Name:    "deployment",
+		Usage:   "`NAME` of the deployment to delete. If unset, deletes the entire agent, including production.",
+		Aliases: []string{"d"},
+	}
+
+	promoteDeploymentFlag = &cli.StringFlag{
+		Name:     "deployment",
+		Usage:    "`NAME` of the non-production deployment whose image is promoted to production.",
+		Required: true,
+		Aliases:  []string{"d"},
+	}
+
 	agentPrebuiltImageFlag = &cli.StringFlag{
 		Name:  "image",
 		Usage: "Pre-built `IMAGE` from the local Docker daemon (e.g. myimage:latest). Requires Docker.",
@@ -358,7 +371,7 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 					Action: promoteAgent,
 					Flags: []cli.Flag{
 						idFlag(false),
-						deploymentFlag,
+						promoteDeploymentFlag,
 					},
 					ArgsUsage: "[working-dir]",
 				},
@@ -436,7 +449,7 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 					Aliases: []string{"destroy"},
 					Flags: []cli.Flag{
 						idFlag(false),
-						deploymentFlag,
+						deleteDeploymentFlag,
 					},
 					ArgsUsage: "[working-dir]",
 				},

cmd/lk/generate_docs.go

@@ -35,24 +35,37 @@ func generateDocs(ctx context.Context, cmd *cli.Command) error {
 			return fmt.Errorf("unknown command: lk %s", strings.Join(path, " "))
 		}
 	}
+	if cmd.Bool("list") {
+		out.Result(strings.Join(documentedPaths(target, path), "\n"))
+		return nil
+	}
 	out.Result(commandDocs(target, path))
 	return nil
 }
 
+// documentedPaths is every command in cmd's subtree that the reference documents:
+// commands that are run (no subcommands), and groups that take their own options.
+func documentedPaths(cmd *cli.Command, path []string) []string {
+	subs := cmd.VisibleCommands()
+	var paths []string
+	if len(subs) == 0 || len(docFlags(cmd)) > 0 {
+		paths = append(paths, strings.Join(path, " "))
+	}
+	for _, sub := range subs {
+		paths = append(paths, documentedPaths(sub, append(path[:len(path):len(path)], sub.Name))...)
+	}
+	return paths
+}
+
 func commandDocs(cmd *cli.Command, path []string) string {
 	var b strings.Builder
 	usage := cmd.UsageText
 	if usage == "" {
-		usage = strings.Join(append([]string{"lk"}, path...), " ")
-		if len(cmd.VisibleCommands()) > 0 {
-			usage += " <command>"
-		}
-		if len(docFlags(cmd)) > 0 {
-			usage += " [options]"
-		}
-		if cmd.ArgsUsage != "" {
-			usage += " " + cmd.ArgsUsage
+		var lines []string
+		for _, name := range append([]string{cmd.Name}, cmd.Aliases...) {
+			lines = append(lines, usageLine(cmd, append(path[:len(path)-1:len(path)-1], name)))
 		}
+		usage = strings.Join(lines, "\n# or\n")
 	}
 	fmt.Fprintf(&b, "```shell\n%s\n```\n", strings.TrimSpace(usage))
 
@@ -70,18 +83,37 @@ func commandDocs(cmd *cli.Command, path []string) string {
 	if flags := docFlags(cmd); len(flags) > 0 {
 		// Each docs page covers one top-level command group, so options are
 		// labelled by the path below it: "Options for `deploy`".
-		label := strings.Join(path, " ")
+		// Aliases are joined into one label: "Options for `logs`/`tail`".
+		parent := strings.Join(path[:len(path)-1], " ")
 		if len(path) > 1 {
-			label = strings.Join(path[1:], " ")
+			parent = strings.Join(path[1:len(path)-1], " ")
+		}
+		var labels []string
+		for _, name := range append([]string{cmd.Name}, cmd.Aliases...) {
+			labels = append(labels, "`"+strings.TrimSpace(parent+" "+name)+"`")
 		}
-		fmt.Fprintf(&b, "\nOptions for `%s`:\n\n", label)
+		fmt.Fprintf(&b, "\nOptions for %s:\n\n", strings.Join(labels, "/"))
 		for _, f := range flags {
 			b.WriteString(flagDocs(f))
 		}
 	}
 	return b.String()
 }
 
+func usageLine(cmd *cli.Command, path []string) string {
+	usage := strings.Join(append([]string{"lk"}, path...), " ")
+	if len(cmd.VisibleCommands()) > 0 {
+		usage += " <command>"
+	}
+	if len(docFlags(cmd)) > 0 {
+		usage += " [options]"
+	}
+	if cmd.ArgsUsage != "" {
+		usage += " " + cmd.ArgsUsage
+	}
+	return usage
+}
+
 // docFlags is the command's own visible flags, without the --help flag urfave
 // copies into every command.
 func docFlags(cmd *cli.Command) []cli.Flag {

cmd/lk/main.go

@@ -79,6 +79,12 @@ Docs: https://docs.livekit.io/intro/basics/cli/`,
 				ArgsUsage: "[command path...]",
 				Action:    generateDocs,
 				Hidden:    true,
+				Flags: []cli.Flag{
+					&cli.BoolFlag{
+						Name:  "list",
+						Usage: "Print the path of every command below the given one that has a reference entry, instead of its docs",
+					},
+				},
 			},
 		},
 		Before: initLogger,