DOCSEARCHbyAlgolia
Submit Docs

LiveKit CLI

repository·main·Indexed 18 days ago

https://github.com/livekit/livekit-cli

The LiveKit CLI (`lk`) is a command-line tool for interacting with LiveKit servers. It allows developers to bootstrap applications from templates, manage projects, join rooms as participants to publish media via FFmpeg or Gstreamer, manage Egress recordings, and perform load testing for video/audio publishers and subscribers. It also includes `lk docs` for browsing LiveKit documentation via an MCP server.

Tokens
25.2K
Snippets
112
Records
132
Agent score
63%

What's inside livekit-cli

  1. Version compatibility between livekit-cli and server-sdk-go

    main

    The livekit-cli is designed to be compatible with specific versions of the server-sdk-go. To ensure stability and avoid errors, the Major and minor versions of livekit-cli must match the versions of server-sdk-go it is using.

    Compatibility Rules:

    • Valid: livekit-cli version 2.2.2 with server-sdk-go version 2.2.0 (or any version where major/minor match).
    • Invalid: livekit-cli version is ahead of server-sdk-go (e.g., CLI 2.3.2 vs SDK 2.2.2).
    • Invalid: livekit-cli major version is ahead of server-sdk-go (e.g., CLI 3.2.2 vs SDK 2.2.2).
    • Invalid: livekit-cli minor version is behind server-sdk-go (e.g., CLI 2.2.2 vs SDK 2.3.2).

  2. Understand parameter precedence in the CLI

    main

    The LiveKit CLI resolves configuration parameters using the following order of precedence (highest to lowest):

    1. Command line flags (e.g., --api-key, --room)
    2. Environment variables (e.g., LIVEKIT_API_KEY, LIVEKIT_URL)
    3. Local configuration files (defaults to ./livekit.toml, can be overridden with --config)
    4. Default project configuration (set via lk project set-default)

    You can override the default project for a single command using the --project flag.

  3. Use template strings in CLI commands

    main

    Many CLI command parameters support template strings for runtime substitution. This is useful for generating unique identities, room names, or metadata.

    Supported Tokens

    • %t: Compact timestamp ("20250702150405")
    • %T: ISO 8601 timestamp ("2025-07-02T15:04:05Z07:00")
    • %Y: Year ("2025")
    • %m: Month ("07")
    • %d: Day of the month ("02")
    • %H: Hour ("15")
    • %M: Minute ("04")
    • %S: Second ("05")
    • %x: Random 6-character hexadecimal string ("a1b2c3")
    • %U: Current user ("username")
    • %h: Current hostname ("my-computer.local")
    • %p: Current PID ("12345")

    Example

    Generate a token with an identity based on the current user and hostname, and a room name with a random suffix:

    lk token create --join --identity "%U@%h" --room "room-%x"

  4. Publish H.264/H.265 simulcast tracks from TCP

    main

    You can publish multiple video streams from different TCP ports as a single Simulcast track. This is achieved by using multiple --publish flags with the syntax <codec>://<host>:<port>/<width>x<height>.

    Requirements

    • All layers must use the same codec (h264 or h265).
    • Tracks are automatically assigned HIGH/MED/LOW resolutions based on the order of their width.
    • If only 2 tracks are provided, they become HIGH and LOW layers.

    Example To publish three resolutions (1920x1080, 1280x720, 640x480) as a single simulcast track:

    lk room join --identity <name> --url "<url>" --api-key "<key>" --api-secret "<secret>" \
--publish h264://127.0.0.1:5005/1920x1080 \
--publish h264://127.0.0.1:5006/1280x720 \
--publish h264://127.0.0.1:5007/640x480 <room>
    lk room join --identity <name> --url "<url>" --api-key "<key>" --api-secret "<secret>" \
--publish h264://127.0.0.1:5005/1920x1080 \
--publish h264://127.0.0.1:5006/1280x720 \
--publish h264://127.0.0.1:5007/640x480 <room>

  5. Encode static videos for LiveKit using ffmpeg

    main

    When preparing static video resources for use with LiveKit, videos should be encoded into specific H.264 bitstream formats to ensure compatibility and performance. The following ffmpeg commands demonstrate how to encode a source video (e.g., butterfly.mp4) into various resolutions and bitrates, ranging from 1080p down to 180p.

    Key encoding parameters used for these resources include:

    • -c:v libx264: Uses the H.264 codec.
    • -bsf:v h264_mp4toannexb: Converts the bitstream to Annex B format.
    • -profile baseline: Uses the baseline profile for maximum compatibility.
    • -pix_fmt yuv420p: Sets the pixel format to YUV 420p.
    • -x264-params keyint=120: Sets the GOP (Group of Pictures) size.
    • -bf 0: Disables B-frames.
    # 1080p @ 30fps, 3M bitrate
ffmpeg -i butterfly.mp4 \
  -c:v libx264 -bsf:v h264_mp4toannexb \
  -b:v 3M -vf "scale=1920:1080, fps=30" \
  -profile baseline -pix_fmt yuv420p \
  -x264-params keyint=120 -max_delay 0 -bf 0 \
  butterfly_1080_3000.h264

# 720p @ 30fps, 2M bitrate
ffmpeg -i butterfly.mp4 \
  -c:v libx264 -bsf:v h264_mp4toannexb \
  -b:v 2M -vf "scale=1280:720, fps=30" \
  -profile baseline -pix_fmt yuv420p \
  -x264-params keyint=120 -max_delay 0 -bf 0 \
  butterfly_720_2000.h264

# 540p @ 25fps, 800K bitrate
ffmpeg -i butterfly.mp4 \
  -c:v libx264 -bsf:v h264_mp4toannexb \
  -b:v 800K -vf "scale=960:540, fps=25" \
  -profile baseline -pix_fmt yuv420p \
  -x264-params keyint=120 -max_delay 0 -bf 0 \
  butterfly_540_800.h264

# 360p @ 20fps, 400K bitrate
ffmpeg -i butterfly.mp4 \
  -c:v libx264 -bsf:v h264_mp4toannexb \
  -b:v 400K -vf "scale=640:360, fps=20" \
  -profile baseline -pix_fmt yuv420p \
  -x264-params keyint=120 -max_delay 0 -bf 0 \
  butterfly_360_400.h264

# 180p @ 15fps, 150K bitrate
ffmpeg -i butterfly.mp4 \
  -c:v libx264 -bsf:v h264_mp4toannexb \
  -b:v 150K -vf "scale=320:180, fps=15" \
  -profile baseline -pix_fmt yuv420p \
  -x264-params keyint=120 -max_delay 0 -bf 0 \
  butterfly_180_150.h264

  6. Install the LiveKit CLI

    main

    Install the lk command line utility using the package manager appropriate for your operating system.

    macOS

    brew install livekit-cli

    Linux

    curl -sSL https://get.livekit.io/cli | bash

    Or download a precompiled binary from the latest release.

    Windows

    winget install LiveKit.LiveKitCLI

    Or download a precompiled binary from the latest release.

    brew install livekit-cli

  7. Configure system settings for load testing

    main

    When running high-scale load tests, you must ensure the host machine's file descriptor and network limits are sufficiently high. Apply these settings on the machine running the load tester:

    ulimit -n 65535
sysctl -w fs.file-max=2097152
sysctl -w net.core.somaxconn=65535
sysctl -w net.core.rmem_max=25165824
sysctl -w net.core.wmem_max=25165824

  8. Manage Egress and Recording

    main

    Recording requires the LiveKit Egress service to be configured. You can start different types of egresses using a JSON request file.

    Start Egresses

    # Room composite (recording of the room UI)
lk egress start --type room-composite <path/to/request.json>

# Track composite (audio + video)
lk egress start --type track-composite <path/to/request.json>

# Single track egress
lk egress start --type track <path/to/request.json>

    Test Egress Templates Use test-egress-template to validate recording templates. This command spins up virtual publishers and opens a browser to the template URL.

    lk egress test-template \
  --base-url http://localhost:3000 \
  --room test-room \
  --layout speaker \
  --video-publishers 3
    lk egress start --type room-composite <path/to/request.json>

  9. Build the LiveKit CLI from source

    main

    To build lk from source, ensure git-lfs is installed for embedded video resources.

    Prerequisites

    • macOS: CoreAudio frameworks (included with Xcode CLT).
    • Linux: libasound2-dev (or equivalent ALSA development package).
    • Windows/Cross-compilation: Install Zig 0.14.1 to act as the Clang C/C++ toolchain.

    Build Steps

    For standard builds:

    git clone https://github.com/livekit/livekit-cli && cd livekit-cli
go build ./cmd/lk

    For Windows or cross-platform builds using GoReleaser:

    goreleaser build --single-target --snapshot --clean
    go build ./cmd/lk

  10. Set up and manage LiveKit projects

    main

    The CLI allows you to authenticate with LiveKit Cloud and manage multiple projects. Once a project is set as default, you can omit url, api-key, and api-secret from subsequent commands.

    Authenticate and link a project

    lk cloud auth

    Follow the browser URL to login and select a project. You will be prompted to set it as the default.

    Manage projects manually

    • Add a project: lk project add --api-key <key> --api-secret <secret> <project_name>
    • List projects: lk project list
    • Switch default project: lk project set-default <project_name>
    • Temporary switch: Use the --project <name> flag with any command to use a specific project without changing the default.
    lk cloud auth

  11. Join a room and publish media tracks

    main

    Use the lk room join command to enter a room as a participant and publish media.

    Join with participant attributes Attributes can be passed via flags or a JSON file.

    # Using flags
lk room join --identity publisher --attribute key1=value1 --attribute key2=value2 <room_name>

# Using a JSON file
lk room join --identity publisher --attribute-file attributes.json <room_name>

    Publishing tracks

    • Demo video: Use --publish-demo <room_name> to publish a 720p/360p/180p simulcast demo track.
    • Media files: Publish encoded .ivf (video) and .ogg (audio) files.
      lk room join --identity publisher --publish <path/to/video.ivf> --publish <path/to/audio.ogg> --fps 23.98 <room_name>
    • FFmpeg/Unix Sockets: Publish transcoded streams from FFmpeg via Unix sockets.
      lk room join --identity bot --publish h264:///tmp/myvideo.sock --publish opus:///tmp/myaudio.sock <room_name>
    • TCP/Gstreamer: Publish streams from a TCP server.
      lk room join --identity bot --publish h264:///127.0.0.1:16400 <room_name>
    lk room join --identity publisher --publish <path/to/video.ivf> --publish <path/to/audio.ogg> --fps 23.98 <room_name>

  12. Bootstrap an application from templates

    main

    You can create new applications using pre-defined templates. The CLI will automatically configure environment variables and settings using your project credentials.

    List available templates

    lk app list-templates

    Create an application

    lk app create --template <template_name> my-app

    Follow the interactive prompts to complete the setup.

    lk app create --template <template_name> my-app