feat: generate CLI reference docs on release

.github/workflows/notify-docs.yaml

@@ -0,0 +1,41 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Notify docs
+
+# Tells livekit/internal-actions that a release went public. It forwards the
+# event to livekit/web, which regenerates the CLI reference on docs.livekit.io
+# from `lk generate-docs` at this tag and opens a PR. `released` fires when a
+# release is published as a full release or a prerelease is later promoted to
+# one; publishing a prerelease doesn't fire it.
+on:
+  release:
+    types: [released]
+
+# The dispatch authenticates with SYNC_DISPATCH_TOKEN; GITHUB_TOKEN isn't used.
+permissions: {}
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch to internal actions repo
+        env:
+          GH_TOKEN: ${{ secrets.SYNC_DISPATCH_TOKEN }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          gh api -X POST repos/livekit/internal-actions/dispatches \
+            -f event_type=livekit-cli-released \
+            -f client_payload[source_repo]=livekit/livekit-cli \
+            -f client_payload[tag]="$TAG"

cmd/lk/agent.go

@@ -127,14 +127,14 @@ var (
 	idFlag = func(required bool) *cli.StringFlag {
 		return &cli.StringFlag{
 			Name:     "id",
-			Usage:    fmt.Sprintf("`ID` of the agent. If unset, and the %s file is present, will use the id found there.", config.LiveKitTOMLFile),
+			Usage:    fmt.Sprintf("Agent `ID`. If unset, uses the ID in %s; without that file, the CLI prompts you to choose an agent.", config.LiveKitTOMLFile),
 			Required: required,
 		}
 	}
 
 	idSliceFlag = &cli.StringSliceFlag{
 		Name:     "id",
-		Usage:    "`IDs` of agent(s)",
+		Usage:    "Filter to one or more agent `IDs`. Repeatable.",
 		Required: false,
 	}
 
@@ -146,31 +146,41 @@ var (
 
 	attributeFlag = &cli.StringSliceFlag{
 		Name:     "attribute",
-		Usage:    "`KEY=VALUE` attribute pair, may be repeated. Merged with --attributes, taking precedence on conflicting keys.",
+		Usage:    "`KEY=VALUE` attribute to record on the new version. Repeatable. Merged with --attributes, taking precedence on conflicting keys.",
 		Required: false,
 	}
 
+	// versions filters by attributes instead of recording them.
+	versionsAttributesFlag = &cli.StringFlag{
+		Name:  "attributes",
+		Usage: "Show only versions that have every attribute in this `JSON` object of string key-value pairs, given as a literal or file path. Use \"-\" to read from stdin.",
+	}
+	versionsAttributeFlag = &cli.StringSliceFlag{
+		Name:  "attribute",
+		Usage: "Show only versions that have this `KEY=VALUE` attribute. Repeatable; a version must have all of them.",
+	}
+
 	noDefaultAttributesFlag = &cli.BoolFlag{
 		Name:  "no-default-attributes",
-		Usage: `Omit default git attributes from deployment.`,
+		Usage: "Don't record the default git_commit, git_branch, and git_tree attributes, which are added when the working directory is a git repository.",
 	}
 
 	secretsFileFlag = &cli.StringFlag{
 		Name:      "secrets-file",
-		Usage:     "`FILE` containing secret KEY=VALUE pairs, one per line. These will be injected as environment variables into the agent.",
+		Usage:     "`FILE` containing secret KEY=VALUE pairs, one per line. Injected as environment variables into the agent.",
 		TakesFile: true,
 		Required:  false,
 	}
 
 	secretsFlag = &cli.StringSliceFlag{
 		Name:     "secrets",
-		Usage:    "KEY=VALUE comma separated secrets. These will be injected as environment variables into the agent. These take precedence over secrets-file.",
+		Usage:    "One or more `KEY=VALUE` secrets. Repeat the flag for each secret. Injected as environment variables into the agent. Takes precedence over --secrets-file.",
 		Required: false,
 	}
 
 	secretsMountFlag = &cli.StringSliceFlag{
 		Name:     "secret-mount",
-		Usage:    "Local path to a secret file to be mounted on agent environment.",
+		Usage:    "Path to a `FILE` to load as a file-mounted secret in the agent container.",
 		Required: false,
 	}
 
@@ -183,32 +193,62 @@ var (
 
 	logTypeFlag = &cli.StringFlag{
 		Name:     "log-type",
-		Usage:    "Type of logs to retrieve. Valid values are 'deploy' and 'build'.",
+		Usage:    "Log `TYPE` to retrieve. Valid values: deploy, build.",
 		Value:    "deploy",
 		Required: false,
 	}
 
 	regionFlag = &cli.StringFlag{
 		Name:     "region",
-		Usage:    "Region to deploy the agent to. If unset, will deploy to the nearest region.",
+		Usage:    "`REGION` code to deploy the agent to. If unset, the CLI prompts you to select a region. Required in non-interactive mode.",
 		Required: false,
 	}
 
+	initRegionFlag = &cli.StringFlag{
+		Name:  "region",
+		Usage: "`REGION` code to deploy the agent to. Used only with --deploy. If unset, the CLI prompts you to select a region. Required in non-interactive mode.",
+	}
+
 	deploymentFlag = &cli.StringFlag{
 		Name:     "deployment",
-		Usage:    "Agent deployment",
+		Usage:    "`NAME` of the deployment. Defaults to production.",
 		Required: false,
 		Aliases:  []string{"d"},
 	}
 
+	// create always deploys to production and deploy keeps the region the agent
+	// was created in; both still accept these flags so existing scripts keep working.
+	ignoredDeploymentFlag = &cli.StringFlag{
+		Name:    "deployment",
+		Aliases: []string{"d"},
+		Hidden:  true,
+	}
+	ignoredRegionFlag = &cli.StringFlag{
+		Name:   "region",
+		Hidden: true,
+	}
+
+	deleteDeploymentFlag = &cli.StringFlag{
+		Name:    "deployment",
+		Usage:   "`NAME` of the non-production 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.",
+		Usage: "Pre-built `IMAGE` from the local Docker daemon (e.g. myimage:latest). Requires Docker. lk agent deploy ignores --deployment with this flag.",
 	}
 
 	agentPrebuiltImageTarFlag = &cli.StringFlag{
 		Name:  "image-tar",
-		Usage: "Pre-built image from an OCI tar file (e.g. ./image.tar). No Docker daemon required.",
+		Usage: "Pre-built image from an OCI tar `FILE` (e.g. ./image.tar). No Docker daemon required. lk agent deploy ignores --deployment with this flag.",
 	}
 
 	skipSDKCheckFlag = &cli.BoolFlag{
@@ -242,7 +282,7 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 					Flags: []cli.Flag{
 						&cli.StringFlag{
 							Name:  "lang",
-							Usage: "`LANGUAGE` of the starter template, one of \"python\", \"node\".",
+							Usage: "`LANGUAGE` of the starter template. One of python, node. If unset, the CLI asks, with Python preselected. Defaults to Python in non-interactive mode. Ignored with --template or --template-url.",
 							Action: func(ctx context.Context, cmd *cli.Command, l string) error {
 								if _, ok := starterTemplateURLs[l]; !ok {
 									return fmt.Errorf("unsupported language: %s", l)
@@ -252,12 +292,12 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 						},
 						&cli.BoolFlag{
 							Name:  "deploy",
-							Usage: "If set, automatically deploys the agent to LiveKit Cloud after initialization.",
+							Usage: "Deploy the agent to LiveKit Cloud after initialization. Implies --install.",
 							Value: false,
 						},
 						templateFlag,
 						templateURLFlag,
-						regionFlag,
+						initRegionFlag,
 						installFlag,
 						skillsSetupFlag,
 					},
@@ -275,7 +315,7 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 						secretsMountFlag,
 						ignoreEmptySecretsFlag,
 						regionFlag,
-						deploymentFlag,
+						ignoredDeploymentFlag,
 						skipSDKCheckFlag,
 						agentPrebuiltImageFlag,
 						agentPrebuiltImageTarFlag,
@@ -296,7 +336,7 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 					Flags: []cli.Flag{
 						&cli.BoolFlag{
 							Name:     "overwrite",
-							Usage:    "Overwrite existing Dockerfile and/or .dockerignore if they exist.",
+							Usage:    "Overwrite existing Dockerfile and .dockerignore files.",
 							Required: false,
 							Value:    false,
 						},
@@ -326,7 +366,7 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 						secretsFlag,
 						secretsFileFlag,
 						secretsMountFlag,
-						regionFlag,
+						ignoredRegionFlag,
 						deploymentFlag,
 						ignoreEmptySecretsFlag,
 						skipSDKCheckFlag,
@@ -345,7 +385,7 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 					Action: promoteAgent,
 					Flags: []cli.Flag{
 						idFlag(false),
-						deploymentFlag,
+						promoteDeploymentFlag,
 					},
 					ArgsUsage: "[working-dir]",
 				},
@@ -394,8 +434,7 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 					Flags: []cli.Flag{
 						&cli.StringFlag{
 							Name:     "version",
-							Usage:    "Version to rollback to, defaults to most recent previous to current.",
-							Value:    "latest",
+							Usage:    "`VERSION` to roll back to, as listed by lk agent versions.",
 							Required: true,
 						},
 						idFlag(false),
@@ -423,7 +462,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]",
 				},
@@ -434,8 +473,8 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 					Action: listAgentVersions,
 					Flags: []cli.Flag{
 						idFlag(false),
-						attributeFlag,
-						attributesFlag,
+						versionsAttributeFlag,
+						versionsAttributesFlag,
 						jsonFlag,
 					},
 					ArgsUsage: "[working-dir]",
@@ -474,7 +513,7 @@ On LiveKit Cloud: "create" and "deploy" ship it, then "status", "logs",
 						idFlag(false),
 						&cli.BoolFlag{
 							Name:     "overwrite",
-							Usage:    "If set, will overwrite existing secrets.",
+							Usage:    "Replace all of the agent's existing secrets with the ones given, instead of adding to and updating them. Asks for confirmation unless --yes.",
 							Required: false,
 							Value:    false,
 						},

cmd/lk/agent_private_link.go

@@ -28,26 +28,26 @@ var privateLinkCommands = &cli.Command{
 			Flags: []cli.Flag{
 				&cli.StringFlag{
 					Name:     "name",
-					Usage:    "Private link name",
+					Usage:    "`NAME` for the private link.",
 					Required: true,
 				},
 				&cli.StringFlag{
 					Name:  "region",
-					Usage: "LiveKit region. If unset in interactive mode, a picker of available regions is shown.",
+					Usage: "LiveKit agent `REGION` for the link. This is the LiveKit region, not the cloud provider region. If unset in interactive mode, the CLI shows a picker of available regions.",
 				},
 				&cli.UintFlag{
 					Name:     "port",
-					Usage:    "Destination port",
+					Usage:    "TCP `PORT` to reach on the target service. Must match the port your endpoint service listens on.",
 					Required: true,
 				},
 				&cli.StringFlag{
 					Name:     "endpoint",
-					Usage:    "Customer-provided endpoint identifier",
+					Usage:    "The `ENDPOINT` to connect to: the AWS endpoint service name, the Azure Private Link Service alias, or the Azure Resource ID.",
 					Required: true,
 				},
 				&cli.StringFlag{
 					Name:  "cloud-region",
-					Usage: "Cloud provider region (e.g. eastus, us-east-2). Required when --endpoint is an Azure Resource ID",
+					Usage: "Cloud provider `REGION` that hosts the resource. Required when --endpoint is an Azure Resource ID. For AWS, LiveKit derives the region from the endpoint service name, so you can omit it.",
 				},
 				jsonFlag,
 			},
@@ -69,7 +69,7 @@ var privateLinkCommands = &cli.Command{
 			Flags: []cli.Flag{
 				&cli.StringFlag{
 					Name:     "id",
-					Usage:    "Private link ID",
+					Usage:    "Private link `ID`.",
 					Required: true,
 				},
 				jsonFlag,
@@ -83,7 +83,7 @@ var privateLinkCommands = &cli.Command{
 			Flags: []cli.Flag{
 				&cli.StringFlag{
 					Name:     "id",
-					Usage:    "Private link ID",
+					Usage:    "Private link `ID`.",
 					Required: true,
 				},
 				jsonFlag,

cmd/lk/agent_run.go

@@ -99,7 +99,7 @@ func init() {
 var agentRunFlags = []cli.Flag{
 	&cli.StringFlag{
 		Name:  "log-level",
-		Usage: "Log level (TRACE, DEBUG, INFO, WARN, ERROR)",
+		Usage: "Log `LEVEL`. One of TRACE, DEBUG, INFO, WARN, ERROR, plus CRITICAL for Python and FATAL for Node.js.",
 	},
 }
 
@@ -122,12 +122,12 @@ var devCommand = &cli.Command{
 	Flags: append(agentRunFlags,
 		&cli.BoolFlag{
 			Name:  "no-reload",
-			Usage: "Disable auto-reload on file changes",
+			Usage: "Disable auto-reload on file changes.",
 		},
 		&cli.StringFlag{
 			Name:    "deployment",
 			Sources: cli.EnvVars(agentDeploymentEnv),
-			Usage:   "Deployment to register the agent under (default: a random `ID` so dev traffic is isolated from production; pass \"production\" to explicitly serve production traffic)",
+			Usage:   "Deployment `NAME` to register the agent under. Defaults to a random dev- ID so dev traffic is isolated from production; pass production to explicitly serve production traffic. Overrides any value in the agent's .env file.",
 		},
 	),
 	Action: runAgentDev,

cmd/lk/cloud.go

@@ -88,19 +88,20 @@ var (
 						&cli.BoolFlag{
 							Name:        "revoke",
 							Aliases:     []string{"R"},
+							Usage:       "Revoke an authorization for an existing project, selected with --project or the default project. This revokes the API keys that were issued with lk cloud auth, and then removes the project from the CLI.",
 							Destination: &revoke,
 						},
 						&cli.IntFlag{
 							Name:        "timeout",
 							Aliases:     []string{"t"},
-							Usage:       "Number of `SECONDS` to attempt authentication before giving up",
+							Usage:       "Number of `SECONDS` to attempt authentication before giving up.",
 							Destination: &timeout,
 							Value:       60 * 15,
 						},
 						&cli.IntFlag{
 							Name:        "poll-interval",
 							Aliases:     []string{"i"},
-							Usage:       "Number of `SECONDS` between poll requests to verify authentication",
+							Usage:       "Number of `SECONDS` between poll requests while waiting.",
 							Destination: &interval,
 							Value:       4,
 						},