feat: generate CLI reference docs on release

[u9g]

docs.livekit.io's CLI reference is hand-written, so every flag or subcommand change in lk has to be re-documented separately and drifts almost immediately. This makes the CLI's own help text the source of truth for that reference.

• lk generate-docs <command path> (hidden) prints a command's usage line, its subcommands, and its options as markdown, in the format the docs.livekit.io CLI reference already uses:

  ```shell
  lk agent deploy [options] [working-dir]
  ```
  
  Options for `deploy`:
  
  - `--deployment NAME` (alias `-d`): NAME of the deployment. Defaults to production.
  

  It reads the same flag data --help prints: the first backticked word in a flag's usage is its value placeholder, defaults come from the flag's value, and hidden commands, hidden flags, and the --help flag are left out. The heading, description, and examples around it stay hand-written on the docs page.

• Help text aligned with the docs: the CLI reference's current descriptions for the agent, simulate, debugger, private-link, cloud auth, project, and docs commands are ported into their help text, and every value flag gets a placeholder (--region REGION rather than --region string). Switching the docs to generated output then changes little on the page, and --help gets the docs' wording. cloud auth --revoke gets the usage text it was missing.

• What --help knows but the docs dropped: generate-docs now marks required flags ("Required."), names the environment variable a flag reads (LIVEKIT_AGENT_DEPLOYMENT on agent dev, LK_SESSION_PORT on the debugger), and says simulate text and audio take the simulate options.

• Help text fixed after comparing it with the current docs.livekit.io pages: rollback --version is required (it never defaulted to the previous version); deploy --region and create --deployment were never read, so they're hidden (still accepted); update-secrets --overwrite replaces every secret; deploy --image/--image-tar ignore --deployment; versions --attribute(s) filter; project list --json includes API secrets; init says when --lang, --install, --skills, and --region prompt or fall back; each debugger --json says what it prints; --samples accepts 1 or 3; export takes any finished run; private-link create --endpoint takes an Azure Private Link Service alias.

• notify-docs.yaml runs when a release is published (prereleases are skipped). It dispatches livekit-cli-released with the tag to livekit/internal-actions, which forwards it to livekit/web. That workflow downloads the release's lk, regenerates the reference with lk generate-docs, and opens a docs PR. It uses the existing org secret SYNC_DISPATCH_TOKEN, the same relay agent-skills uses, so no credential that writes to livekit/web lives in this public repo.

To change wording on docs.livekit.io, edit the command's help text here; the next published release updates the docs.

Related:

• livekit/internal-actions: https://github.com/livekit/internal-actions/pull/18
• livekit/web: https://github.com/livekit/web/pull/6531

How to verify

make build
./bin/lk generate-docs agent deploy
./bin/lk generate-docs agent simulate
./bin/lk agent deploy --help
./bin/lk generate-docs nope   # unknown command: lk nope, exit 1
./bin/lk --help | grep -c generate-docs   # 0, hidden
go test ./cmd/lk

[u9g]

lk generate-docs printing agent deploy and agent simulate in the docs.livekit.io CLI reference format, the same help text in lk agent deploy --help with placeholders, the update banner staying on stderr when captured to a file, an unknown command failing, and the command staying hidden from lk --help.

generate-docs.mp4

[u9g]

lk generate-docs marking rollback --version and promote --deployment Required (and the CLI enforcing it), simulate text pointing at the simulate options it takes, dev --deployment listing LIVEKIT_AGENT_DEPLOYMENT, deploy no longer listing the no-op --region and noting --image ignores --deployment, project list --json warning it includes the API secret, and debugger events --json saying it prints NDJSON.

generate-docs-fixes.mp4

[kath0la]

I made some small changes: some rephrasing, reusing default values, and adding a test. I changed the github action to released from published because it got flagged as not getting triggered by a prerelease getting promoted to a release.

[kath0la]

Sometimes "required" is in the usage text and sometimes it's not (for example, endpoint). It would be preferable to not include it in the text consistently and just use the Required field to document it.