From bc7aba2b0d9be95d5171fd89b499efbb3c1c1e6a Mon Sep 17 00:00:00 2001 From: Jason Lernerman Date: Thu, 15 Oct 2026 10:23:02 -0400 Subject: [PATCH 1/3] fix: describe --deployment for agent delete and promote agent delete deletes the whole agent when --deployment is unset, and agent promote rejects an unset --deployment, so the shared flag's "Defaults to production" was wrong for both. They now have their own flag, and promote requires it. --- cmd/lk/agent.go | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/cmd/lk/agent.go b/cmd/lk/agent.go index 78b29a9b..f0acc8d2 100644 --- a/cmd/lk/agent.go +++ b/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]", }, From 4ca4df3f3d8f1965891e5bdf22056eace3e86ca4 Mon Sep 17 00:00:00 2001 From: Jason Lernerman Date: Thu, 15 Oct 2026 10:24:30 -0400 Subject: [PATCH 2/3] feat: list command aliases in generate-docs output Each alias gets its own usage line and joins the options label, the way the docs.livekit.io CLI reference wrote them by hand (lk agent logs / lk agent tail). --- cmd/lk/generate_docs.go | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/cmd/lk/generate_docs.go b/cmd/lk/generate_docs.go index 9f5c37a9..489a4d42 100644 --- a/cmd/lk/generate_docs.go +++ b/cmd/lk/generate_docs.go @@ -43,16 +43,11 @@ 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 += " " - } - 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,11 +65,16 @@ 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], " ") } - fmt.Fprintf(&b, "\nOptions for `%s`:\n\n", label) + 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", strings.Join(labels, "/")) for _, f := range flags { b.WriteString(flagDocs(f)) } @@ -82,6 +82,20 @@ func commandDocs(cmd *cli.Command, path []string) string { return b.String() } +func usageLine(cmd *cli.Command, path []string) string { + usage := strings.Join(append([]string{"lk"}, path...), " ") + if len(cmd.VisibleCommands()) > 0 { + usage += " " + } + 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 { From 1496adbd6a4ca930f614e0f911b7f3b0ee194fbd Mon Sep 17 00:00:00 2001 From: Jason Lernerman Date: Thu, 15 Oct 2026 10:25:23 -0400 Subject: [PATCH 3/3] feat: add generate-docs --list Prints every command under a path that the reference documents: commands that are run, and groups with their own options. docs.livekit.io generates a partial for each, so a new command can't go missing from the reference. --- cmd/lk/generate_docs.go | 18 ++++++++++++++++++ cmd/lk/main.go | 6 ++++++ 2 files changed, 24 insertions(+) diff --git a/cmd/lk/generate_docs.go b/cmd/lk/generate_docs.go index 489a4d42..4a86d383 100644 --- a/cmd/lk/generate_docs.go +++ b/cmd/lk/generate_docs.go @@ -35,10 +35,28 @@ 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 diff --git a/cmd/lk/main.go b/cmd/lk/main.go index a986a5c9..5afd8c21 100644 --- a/cmd/lk/main.go +++ b/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,