feat: generate CLI reference docs on release

.github/workflows/notify-docs.yaml

@@ -0,0 +1,40 @@
+# 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.
+on:
+  release:
+    types: [published]
+
+# The dispatch authenticates with SYNC_DISPATCH_TOKEN; GITHUB_TOKEN isn't used.
+permissions: {}
+
+jobs:
+  dispatch:
+    if: ${{ !github.event.release.prerelease }}
+    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

@@ -128,14 +128,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 and %s is present, uses the ID found there.", 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,
 	}
 
@@ -158,20 +158,20 @@ var (
 
 	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,
 	}
 
@@ -184,32 +184,32 @@ 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: false,
 	}
 
 	deploymentFlag = &cli.StringFlag{
 		Name:     "deployment",
-		Usage:    "Agent deployment",
+		Usage:    "`NAME` of the deployment. Defaults to production.",
 		Required: false,
 		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.",
 	}
 
 	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.",
 	}
 
 	skipSDKCheckFlag = &cli.BoolFlag{
@@ -244,7 +244,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.",
 								Action: func(ctx context.Context, cmd *cli.Command, l string) error {
 									if _, ok := starterTemplateURLs[l]; !ok {
 										return fmt.Errorf("unsupported language: %s", l)
@@ -254,7 +254,7 @@ 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.",
 								Value: false,
 							},
 							templateFlag,
@@ -309,7 +309,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,
 						},
@@ -407,7 +407,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.",
+							Usage:    "`VERSION` to roll back to. Defaults to the most recent version prior to the current.",
 							Value:    "latest",
 							Required: true,
 						},
@@ -487,7 +487,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:    "Overwrite existing secrets.",
 							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.",
 					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. Required. 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 or the Azure Resource ID. Required.",
 					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.",
 					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.",
 					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.",
 	},
 }
 
@@ -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 ID so dev traffic is isolated from production; pass production to explicitly serve production traffic.",
 		},
 	),
 	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,
 						},

cmd/lk/console.go

@@ -74,33 +74,33 @@ conversation one command at a time, use "lk agent debugger" instead.`,
 		&cli.IntFlag{
 			Name:    "port",
 			Aliases: []string{"p"},
-			Usage:   "TCP port for agent communication",
+			Usage:   "TCP `PORT` for agent communication. Defaults to 0 (auto-select).",
 			Value:   0,
 		},
 		&cli.StringFlag{
 			Name:  "input-device",
-			Usage: "Input device index or name substring",
+			Usage: "Input device index or `NAME` substring.",
 		},
 		&cli.StringFlag{
 			Name:  "output-device",
-			Usage: "Output device index or name substring",
+			Usage: "Output device index or `NAME` substring.",
 		},
 		&cli.BoolFlag{
 			Name:  "list-devices",
-			Usage: "List available audio devices and exit",
+			Usage: "List available audio devices and exit.",
 		},
 		&cli.BoolFlag{
 			Name:  "no-aec",
-			Usage: "Disable acoustic echo cancellation",
+			Usage: "Disable acoustic echo cancellation.",
 		},
 		&cli.BoolFlag{
 			Name:    "text",
 			Aliases: []string{"t"},
-			Usage:   "Start in text mode instead of voice (no STT/TTS); ctrl+t toggles later",
+			Usage:   "Start in text mode instead of audio mode.",
 		},
 		&cli.BoolFlag{
 			Name:  "record",
-			Usage: "Record audio and session report to console-recordings/",
+			Usage: "Record audio and a session report to console-recordings/.",
 		},
 	},
 	Action: runConsole,