gem-hunter

This package includes command line utilities that interacts with LiveKit. It allows you to:

• Bootstrap new applications from templates
• Create access tokens
• Access LiveKit APIs, create and delete rooms, etc.
• Join a room as a participant, inspecting in-room events
• Start and manage Egresses
• Perform load testing, efficiently simulating real-world load

brew install livekit-cli

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

The script installs lk to /usr/local/bin. Set LK_INSTALL_PATH to install somewhere else.

Or download a precompiled binary for the latest release

winget install LiveKit.LiveKitCLI

Or download a precompiled binary for the latest release

This repo uses Git LFS for embedded video resources. Please ensure git-lfs is installed on your machine.

Every build of lk includes the audio/console subsystem (CGO + PortAudio + WebRTC APM). You will need platform headers/libraries for the C compile:

• macOS: nothing to install — CoreAudio frameworks ship with Xcode CLT.
• Linux: sudo apt-get install libasound2-dev (or your distro's ALSA dev package).

Then:

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

The WebRTC APM C++ requires a Clang-based toolchain (it uses MSVC-style SEH on Windows). macOS and most Linux distros already use Clang for cgo. To build for Windows — or to cross-compile for any platform — install Zig 0.14.1 (used as the Clang C/C++ toolchain) and run a GoReleaser snapshot build, which sets the compiler and flags for you:

goreleaser build --single-target --snapshot --clean

See lk --help for a complete list of subcommands. The --help flag can also be used on any subcommand for more information.

The quickest way to get started is to authenticate with your LiveKit Cloud account and link an existing project. If you haven't created an account or project yet, head here first. Then run the following:

lk cloud auth

Follow the URL to login in the browser and choose your project to link. When you return to your terminal, you'll have the option to use this project as the default.

When a default project is set up, you can omit url, api-key, and api-secret when using the CLI. You can also set up multiple projects, and temporarily switch the active project used with the --project flag, or persistently using lk project set-default.

lk project add --api-key <key> --api-secret <secret> <project_name>

lk project list

lk project set-default <project_name>

The LiveKit CLI can help you bootstrap applications from a number of convenient template repositories, using your project credentials to set up required environment variables and other configuration automatically. To create an application from a template, run the following:

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

Then follow the CLI prompts to finish your setup.

For a list of all available templates, run:

lk app list-templates

See the LiveKit Templates Index for details about templates, and for instructions on how to contribute your own.

lk room join --identity publisher \
  --attribute key1=value1 \
  --attribute key2=value2 \
  <room_name>

You can also specify attributes by providing a JSON file:

lk room join --identity publisher \
  --attribute-file attributes.json \
  <room_name>

Where attributes.json contains a JSON object with key-value pairs:

{
  "key1": "value1",
  "key2": "value2"
}

To publish a demo video as a participant's track, use the following:

lk room join --identity publisher --publish-demo <room_name>

This will publish the demo video track with simulcast, at 720p, 360p, and 180p.

You can publish your own audio/video files. These tracks files need to be encoded in supported codecs. Refer to encoding instructions

lk room join --identity publisher \
  --publish <path/to/video.ivf> \
  --publish <path/to/audio.ogg> \
  --fps 23.98 \
  <room_name>

This will publish the pre-encoded .ivf and .ogg files to the room, indicating video FPS of 23.98. Note that the FPS only affects the video; it's important to match video framerate with the source to prevent out of sync issues.

Note: For files uploaded via CLI, expect an initial delay before the video becomes visible to the remote viewer. This delay is attributed to the pre-encoded video's fixed keyframe intervals. Video encoded with LiveKit client SDKs do not have this delay.

It's possible to publish any source that FFmpeg supports (including live sources such as RTSP) by using it as a transcoder.

This is done by running FFmpeg in a separate process, encoding to a Unix socket. (not available on Windows). lk can then read transcoded data from the socket and publishing them to the room.

First run FFmpeg like this:

ffmpeg -i <video-file | rtsp://url> \
  -c:v libx264 -bsf:v h264_mp4toannexb -b:v 2M -profile:v baseline -pix_fmt yuv420p \
    -x264-params keyint=120 -max_delay 0 -bf 0 \
    -listen 1 -f h264 unix:/tmp/myvideo.sock \
  -c:a libopus -page_duration 20000 -vn \
  	-listen 1 -f opus unix:/tmp/myaudio.sock

This transcodes the input into H.264 baseline profile and Opus.

Then, run lk like this:

lk room join --identity bot \
  --publish h264:///tmp/myvideo.sock \
  --publish opus:///tmp/myaudio.sock \
  <room_name>

You should now see both video and audio tracks published to the room.

Note: To publish H.265/HEVC over sockets, use the h265:// scheme (for example, h265:///tmp/myvideo.sock or h265://127.0.0.1:16400). Ensure your LiveKit deployment and clients support H.265 playback.

It's possible to publish from video streams coming over a TCP socket. lk can act as a TCP client. For example, with a gstreamer pipeline ending in ! tcpserversink port=16400 and streaming H.264.

Run lk like this:

lk room join \
  --identity bot \
  --publish h264:///127.0.0.1:16400 \
  <room_name>

You can publish multiple H.264 or H.265 video tracks from different TCP ports as a single Simulcast track. This is done by using multiple --publish flags.

The track will be published in simulcast mode if multiple --publish flags with the syntax <codec>://<host>:<port>/<width>x<height> are passed in as arguments, where <codec> is h264 or h265. All layers must use the same codec.

Example:

Use Gstreamer to scale a video input to 3 resolutions (1920x1080, 1280x720, 640x360), encode each as a H.264 stream and output each H.264 stream on a different port using tcpserversink.

# Note: this is just an example of a Gstreamer pipeline structure
# It uses a `tee` element to split the raw frame input to 3 pipelines for 
# scaling to a specific resolution then encoding to H.264 byte stream.
gst-launch-1.0 -e -v \
  v4l2src device=<device> \
  tee name=t  \
  t. ! <scale to 1920x1080, H.264 encode elements> ! \
      tcpserversink host=0.0.0.0 port=5005 sync=false async=false \
  t. ! <scale to 1280x720, H.264 encode elements> ! \
      tcpserversink host=0.0.0.0 port=5006 sync=false async=false \
  t. ! <scale to 640x480, H.264 encode elements> ! \
      tcpserversink host=0.0.0.0 port=5007 sync=false async=false

Use livekit-cli to publish the 3 resolution streams to 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>

Notes:

• LiveKit CLI can publish simulcast tracks using H.264 or H.265. Ensure your LiveKit deployment and clients support the chosen codec (HEVC/H.265 support varies by platform/browser).
• You can only use multiple --publish flags to create a simulcast track.
• Using more than 1 --publish flag for other types of streams will not work.
• Tracks will automatically be set to HIGH/MED/LOW resolution based on the order of their width.
• If only 2 tracks are published, they will be published as HIGH and LOW resolution layers.

Using unix sockets, it's also possible to publish streams from your application. The tracks need to be encoded into a format that WebRTC clients could playback (VP8, H.264, H.265, and Opus).

Once you are writing to the socket, you could use ffplay to test the stream.

ffplay -i unix:/tmp/myvideo.sock

Recording requires egress service to be set up first.

Example request.json files are located here.

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

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

# Start track egress (single audio or video track)
lk egress start --type track <path/to/request.json>

In order to speed up the development cycle of your recording templates, we provide a sub-command test-egress-template that helps you to validate your templates.

The command will spin up a few virtual publishers, and then simulate them joining your room It'll then open a browser to the template URL, with the correct parameters filled in.

Here's an example:

lk egress test-template \
  --base-url http://localhost:3000 \
  --room test-room \
  --layout speaker \
  --video-publishers 3

This command will launch a browser pointed at http://localhost:3000, while simulating 3 publishers publishing to your livekit instance.

Load testing utility for LiveKit. This tool is quite versatile and is able to simulate various types of load.

Note: livekit-load-tester has been renamed to sub-command lk load-test

This guide requires a LiveKit server instance to be set up. You can start a load tester with:

lk load-test \
  --room test-room \
  --video-publishers 8

This simulates 8 video publishers to the room, with no subscribers. Video tracks are published with simulcast, at 720p, 360p, and 180p.

To test audio capabilities in your app, you can also simulate simultaneous speakers to the room.

lk load-test \
  --room test-room \
  --audio-publishers 5

The above simulates 5 concurrent speakers, each playing back a pre-recorded audio sample at the same time. In a meeting, typically there's only one active speaker at a time, but this can be useful to test audio capabilities.

Generate a token so you can log into the room:

lk token create --join \
  --room test-room \
  --identity test-user \
  --open meet

This will open Meet, a video conferencing example app, and join the simulated room. Alternatively, you can omit the --open parameter, visit the site and paste in the token yourself.

Due to bandwidth limitations of your ISP, most of us wouldn't have sufficient bandwidth to be able to simulate 100s of users download/uploading from the internet.

We recommend running the load tester from a VM on a cloud instance, where there isn't a bandwidth constraint.

To make this simple, make will generate a linux amd64 binary in bin/. You can scp the binary to a server instance and run the test there.

Prior to running the load tests, it's important to ensure file descriptor limits have been set correctly. See Performance tuning docs.

On the machine that you are running the load tester, they would also need to be applied:

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

You can run the load tester on multiple machines, each simulating any number of publishers or subscribers.

LiveKit SFU's performance is measured by the amount of data sent to its subscribers.

Use this command to simulate a load test of 5 publishers, and 500 subscribers:

lk load-test \
  --duration 1m \
  --video-publishers 5 \
  --subscribers 500

It'll print a report like the following. (this run was performed on a 16 core, 32GB memory VM)

Summary | Tester  | Tracks    | Bitrate                 | Latency     | Total Dropped
        | Sub 0   | 10/10     | 2.2mbps                 | 78.86829ms  | 0 (0%)
        | Sub 1   | 10/10     | 2.2mbps                 | 78.796542ms | 0 (0%)
        | Sub 10  | 10/10     | 2.2mbps                 | 79.361718ms | 0 (0%)
        | Sub 100 | 10/10     | 2.2mbps                 | 79.449831ms | 0 (0%)
        | Sub 101 | 10/10     | 2.2mbps                 | 80.001104ms | 0 (0%)
        | Sub 102 | 10/10     | 2.2mbps                 | 79.833373ms | 0 (0%)
...
        | Sub 97  | 10/10     | 2.2mbps                 | 79.374331ms | 0 (0%)
        | Sub 98  | 10/10     | 2.2mbps                 | 79.418816ms | 0 (0%)
        | Sub 99  | 10/10     | 2.2mbps                 | 79.768568ms | 0 (0%)
        | Total   | 5000/5000 | 678.7mbps (1.4mbps avg) | 79.923769ms | 0 (0%)

You can customize various parameters of the test such as

• --video-publishers: number of video publishers
• --audio-publishers: number of audio publishers
• --subscribers: number of subscribers
• --video-resolution: publishing video resolution. low, medium, high
• --no-simulcast: disables simulcast
• --num-per-second: number of testers to start each second
• --layout: layout to simulate (speaker, 3x3, 4x4, or 5x5)
• --simulate-speakers: randomly rotate publishers to speak

The agent load testing utility allows you to dispatch a running agent to a number of rooms and simulate a user in each room that would echo whatever the agent says.

Note: Before running the test, ensure that:

• Your agent is already running using start instead of dev with the specified agent_name configured
• The agent is configured to speak something first (e.g., a simple greeting)

To start an agent load test:

lk perf agent-load-test \
  --rooms 5 \
  --agent-name test-agent \
  --echo-speech-delay 10s \
  --duration 5m
  --attribute key1=value1

The above simulates 5 concurrent rooms, where each room has:

• Your agent test-agent dispatched
• An echo participant that receives and plays back the agent's audio
• A 10-second delay in the echo response from the agent speech
• The test runs for 5 minutes before automatically stopping

Once the specified duration is over (or if the load test is manually stopped), the load test statistics will be displayed in the form of a table.

lk agent console runs your agent locally and connects it straight to your microphone and speakers, so you can talk to it the way a user would without joining a LiveKit room. It is the interactive, human-facing way to test an agent. The terminal shows the live transcript, tool calls with their results, handoffs, and per-turn latency metrics.

Run it from the agent project directory, or name the entrypoint:

lk agent console                         # the project in the current directory, default entrypoint
lk agent console src/my_agent.py         # an explicit entrypoint
lk agent console agent.ts -- --env-file=.env   # arguments after -- go to node/python
lk agent console --text                  # start typing instead of talking; STT/TTS stay off

Keys while it runs: m mutes the microphone, ctrl+t switches between voice and text mode, ? lists shortcuts, and q quits (ctrl+c in text mode). In text mode you type a turn and press enter; only your LLM and tools run, so it is the cheapest way to check conversational logic by hand.

Useful options:

• --list-devices, --input-device, and --output-device choose audio devices by index or name substring.
• --no-aec turns off acoustic echo cancellation if you are on headphones and want the raw signal.
• --record saves the audio and a session report under console-recordings/.

Console needs a terminal. If a program rather than a person is going to hold the conversation, use the agent debugger below.

lk agent debugger is built for coding agents such as Claude Code, Codex, and Cursor. When one of them is working on your LiveKit agent, it can use this command to hold a conversation with the agent it just edited, read the replies and tool calls, and decide what to try next, all from the shell, with no human at a microphone. It is an ad-hoc, local stand-in for Agent Simulations in which the coding agent plays the user and pays with its own tokens: by default the agent runs in console mode with STT/TTS disabled, so a turn costs only your LLM and tool calls, and nothing touches a LiveKit room.

Start the session with --audio to test the audio path instead: each say is spoken with LiveKit Inference TTS into the agent's microphone input, and the agent runs its full audio pipeline (STT, turn detection, TTS, or a realtime model that only takes audio), so misheard names, spelled-out digits, and endpointing behave as they do on a call. Each turn then prints what the agent transcribed, with the text you sent alongside when the words differ. The TTS runs on LiveKit Inference and is billed to your connected LiveKit Cloud project, resolved like other lk commands.

People can use it too, but the output and flags are shaped for a program driving it one command at a time: every turn prints tool calls with their arguments and results, handoffs, errors, and the reply; exit codes are non-zero when a turn fails; --json is available everywhere. If you want to talk to your agent yourself, lk agent console is the better fit.

A typical session, run from the agent project directory (lk agent dbg is short for lk agent debugger):

lk agent debugger start                       # starts the agent, prints its opening message if it has one (--audio to speak turns)
lk agent debugger say "Hi, what can you do?"  # prints tool calls (with arguments and results), handoffs, and the reply
lk agent debugger say "Book a table for two tonight"
lk agent debugger chat-history                # the whole conversation so far
lk agent debugger events                      # live, one-line-per-event stream of everything the session does
lk agent debugger logs --last 40              # the agent process's logs (tracebacks, warnings)
lk agent debugger status                      # active agent, its tools, state, log file
lk agent debugger stop --chat-history         # closing summary, plus the whole conversation

start takes an optional entrypoint (lk agent debugger start src/my_agent.py) when the project doesn't use the default agent.py/src/agent.py or main.ts/src/main.ts; arguments after -- go to the interpreter.

Useful options:

• say --logs shows the agent's log lines beneath the step they belong to, so a tool's traceback appears right under the sanitized error the user would hear.
• say --timeout 30s bounds how long to wait for the reply (default 2 minutes); the exit code is non-zero if the turn failed or timed out.
• --json on any command prints machine-readable output. Each turn is a document with text, reply, duration_ms, and an events list of message, tool_call, handoff, config, error, log, and (on the events stream) state entries, each with a time.
• --metrics adds per-turn latency metrics (time to first token, end-to-end).
• restart relaunches the agent with a fresh conversation after the code changes.
• events streams the session as a flat, timestamped feed (messages, tool calls, handoffs, state changes) until interrupted, replaying the last few first; --logs adds agent log lines, and --json emits NDJSON for piping into other tools.
• --port runs several sessions side by side (one agent per port).
• A session stops itself after 30 minutes without commands so a forgotten one doesn't linger; start --idle-timeout changes that (0 disables it).

To point a coding agent at it, add a line like this to your project's AGENTS.md or CLAUDE.md: "To test the agent, use lk agent debugger (run lk agent debugger --help first); start it, converse with it as a user would, and check logs when something looks wrong."

The CLI includes a built-in lk docs command that lets you search and browse the LiveKit documentation directly from the terminal. It's powered by the LiveKit docs MCP server using the official MCP Go SDK.

# Get a complete overview of the docs site
lk docs overview

# Search the docs
lk docs search "voice agents"

# Fetch a specific page as markdown
lk docs get-page /agents/start/voice-ai-quickstart

# Search code across LiveKit GitHub repos
lk docs code-search "class AgentSession" --repo livekit/agents

# Get recent releases for an SDK
lk docs changelog pypi:livekit-agents

# List all LiveKit SDKs
lk docs list-sdks

# Submit feedback on the docs
lk docs submit-feedback --page /agents/build/tools "Missing info about error handling"

Run lk docs --help for full details on each subcommand.

For development against staging or preview deployments of the docs MCP server, two hidden flags are available on the lk docs command:

• --server-url URL: Override the MCP server endpoint (default: https://docs.livekit.io/mcp/)
• --vercel-header VALUE: Set the x-vercel-protection-bypass header, required for accessing private Vercel preview deployments

# Use a staging server
lk docs --server-url https://docs-staging.example.com/mcp/ search "agents"

# Access a private Vercel preview deploy
lk docs --server-url https://docs-abc123.vercel.app/mcp/ --vercel-header <token> overview

lk skills installs LiveKit's agent skills into your coding agents (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf, Amp, Cline, Goose), and adds the LiveKit Docs MCP server to their MCP config.

# Install every skill and the Docs MCP server for the agents detected on this machine
lk skills install

# Only some agents, or user-wide instead of the current project
lk skills install --agent claude-code --agent codex
lk skills install --global

# See what's installed, whether it's current, and Docs MCP setup
lk skills list

# Pull the latest skills
lk skills update

# Uninstall
lk skills remove

Skills are copied (not symlinked) into each agent's skills directory; agents that read the shared .agents/skills directory get one copy. Installs are recorded in skills-lock.json (commit it with the skills), or ~/.agents/.skill-lock.json with --global. These are the same lock files npx skills and gh skill use, so any of the three tools can update what another installed. Skills you've edited locally are never overwritten unless you pass --force.

lk agent init offers to install skills into new agent projects for the coding agents on your machine; pass --skills=false to skip.

If a coding agent is on your machine but no LiveKit skills are installed, lk offers once, in a terminal, to install them globally (lk skills install --global). Runs without a terminal or with --yes, such as a coding agent calling lk, print a one-line tip instead and never wait for input. Neither appears in CI, with --quiet or --json, or when LK_NO_SKILLS_PROMPT=1 is set.

CLI commands support various ways to set some parameters, including via environment variables, local configuration files, and command line flags. The precedence order is as follows:

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

If you have multiple projects configured, you can specify which project to use with the --project flag. This will override the default project for that command only.

Some command parameters support template strings, which are substituted with real values at runtime. This is useful for generating unique identities and room names, or tagging entities with timestamps and other metadata. Supported template strings include:

• %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")

For example, you can use the following command to generate a token whose identity is your current user@hostname, and a room with a random suffix:

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

This project shares the same Major and minor version as server-sdk-go for compatibility. The livekit-cli must always import server-sdk-go with matching major and minor versions. When introducing breaking changes to server-sdk-go, increment its minor version and update livekit-cli to use the new version, releasing a matching CLI version accordingly.