Rooms and participants | LiveKit Documentation

Overview

Use these commands to work with rooms and participants from your terminal:

lk room: Create, list, update, and delete rooms, join a room as a participant, and moderate participants and tracks.
lk token: Create access tokens with specific grants.
lk dispatch: Explicitly dispatch agents to rooms and manage existing dispatches.

To install the CLI, see Install the CLI.

lk room [command [command options]]
lk token [command [command options]]
lk dispatch [command [command options]]

Credentials

These commands need a server URL, API key, and API secret. The CLI uses the first available source:

The --project NAME or --subdomain SUBDOMAIN flag, which selects a configured project.
The --url, --api-key, and --api-secret flags, or the LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET environment variables.
The --dev flag, which uses devkey and secret for a local server in dev mode.
The project named in a livekit.toml file in the working directory.
Your default project.

Add --curl to any server API command to print the equivalent curl request.

Flags marked "(supports templates)" replace %t (UTC timestamp), %x (random hex), and %U (current user). For example, --room "test-%t" creates a room like test-20260101120000.

Test a room with LiveKit Meet

Check that a project works end to end by joining a room from LiveKit Meet and publishing a second participant from the CLI.

Generate an access token

Create an access token to join the room. For a local server in dev mode, add --dev.

lk token create \
  --join --room test_room --identity test_user \
  --valid-for 24h

You can also generate tokens from your project's dashboard .

Connect with LiveKit Meet

In LiveKit Meet , open the "Custom" tab and enter your server URL and token. For LiveKit Cloud, the Project URL (starting with wss://) is in your project settings.

LiveKit Meet

Full source code for the LiveKit Meet example app.

Simulate another publisher

Join the same room from the CLI and publish a looping demo video. Expect a short delay before the video renders.

lk room join --identity bot_user --publish-demo test_room

You can also open Meet in a second browser tab with another token that uses a different --identity.

Room commands

For the equivalent server SDK methods, see Room management.

Create a room

Create a room and print it as JSON. Rooms are created automatically when the first participant joins, so use this only to configure a room in advance.

lk room create [options] ROOM_NAME

Options for room create:

ROOM_NAME: Name of the room to create.
--empty-timeout SECS: Number of seconds to keep the room open before any participant joins.
--departure-timeout SECS: Number of seconds to keep the room open after the last participant leaves.
--min-playout-delay MS: Minimum playout delay for video, in milliseconds.
--max-playout-delay MS: Maximum playout delay for video, in milliseconds.
--sync-streams: Put audio and video in the same stream for better sync. Default: false.
--room-preset NAME: Room configuration preset to use.
--agents-file JSON: JSON file with a dispatches array of agents to dispatch.
--room-egress-file JSON: JSON file with a RoomCompositeEgressRequest to record the room.
--participant-egress-file JSON: JSON file with an AutoParticipantEgress to record each participant.
--track-egress-file JSON: JSON file with an AutoTrackEgress to record each track.

For the egress file formats, see Auto egress.

Examples

Close the room after 10 minutes if nobody joins, or 30 seconds after the last participant leaves:

lk room create \
  --empty-timeout 600 \
  --departure-timeout 30 \
  my-room

Dispatch an agent when the room is created:

lk room create --agents-file agents.json my-room

Where agents.json contains:

{
  "dispatches": [
    {
      "agent_name": "my-agent",
      "metadata": "{\"user_id\": \"12345\"}"
    }
  ]
}

List rooms

List active rooms.

lk room list [options] [ROOM_NAME ...]

Options for room list:

ROOM_NAME: Names of rooms to return. Default: all active rooms.
--json, -j: Output as JSON. Default: false.

Examples

lk room list --json my-room other-room

Update room metadata

Replace the metadata of an active room.

lk room update --metadata METADATA ROOM_NAME

Options for room update:

ROOM_NAME: Name of the room to update.
--metadata METADATA: Required. New room metadata, typically JSON.

Examples

lk room update --metadata '{"topic": "Weekly sync"}' my-room

Delete a room

Delete a room and disconnect all participants.

lk room delete ROOM_NAME

Join a room

Join a room as a participant to publish media, send data or DTMF, or watch room events. The CLI signs its own token and stays connected until you press Ctrl+C.

lk room join [options] ROOM_NAME

Options for room join:

ROOM_NAME: Name of the room to join, or use --room.
--room NAME, -r NAME: Name of the room to join (supports templates).
--identity ID, -i ID: Participant identity (supports templates). Default: participant-<random>.
--metadata JSON: Participant metadata.
--attribute KEY=VALUE: Participant attribute. Repeatable.
--attribute-file JSON: JSON file of participant attributes, merged with --attribute.
--auto-subscribe: Subscribe to other participants' tracks. Default: false.
--publish-demo: Publish a looping demo video track.
--publish FILES: .h264, .ivf, or .ogg file, or a socket, to publish. Repeat for up to three tracks.
--fps FPS: Frame rate of published video files.
--h26x-streaming-format FORMAT: H.264/H.265 input format, annex-b or length-prefixed. Default: annex-b.
--attach-frame-metadata: Attach LKTS frame metadata from H.264/H.265 SEI to each frame.
--exit-after-publish: Disconnect when publishing finishes.
--publish-data DATA: Send a data packet after joining.
--publish-dtmf DIGITS: Send DTMF digits after joining. w adds a 0.5 second pause.
--open APP: Open meet (LiveKit Meet , as an observer participant) or console (the agent console) in your browser.

Publishing from a socket

--publish also accepts a Unix socket (<codec>:///<socket_path>) or TCP socket (<codec>://<host:port>). Valid codecs are h264, h265, vp8, and opus.

For simulcast, pass two or three h264 or h265 URLs with each layer's dimensions appended, such as h264://<host:port>/1280x720. All layers must use the same codec.

Examples

Publish a video and an audio file, then disconnect when both finish:

lk room join \
  --identity publisher \
  --publish video.h264 \
  --publish audio.ogg \
  --fps 30 \
  --exit-after-publish \
  my-room

Publish an H.264 stream from a TCP socket:

lk room join \
  --identity camera-1 \
  --attribute location=lobby \
  --publish h264://127.0.0.1:16400 \
  my-room

Mute or unmute a track

Mute or unmute a participant's track. Mutes by default. Remote unmute is off unless you enable it.

lk room mute-track --room NAME --identity ID [--mute | --unmute] TRACK_SID

Options for room mute-track:

TRACK_SID: SID of the track to mute or unmute.
--room NAME, -r NAME: Required. Name of the room (supports templates).
--identity ID, -i ID: Required. Identity of the publishing participant (supports templates).
--mute, -m: Mute the track.
--unmute, -u: Unmute the track.

To find track SIDs, use room participants get.

Examples

lk room mute-track --room my-room --identity alice --mute TR_AMkSxxxxxx

Update track subscriptions

Subscribe a participant to tracks, or unsubscribe them. Subscribes by default.

lk room update-subscriptions --room NAME --identity ID [--subscribe | --unsubscribe] TRACK_SID [TRACK_SID ...]

Options for room update-subscriptions:

TRACK_SID: SIDs of the tracks.
--room NAME, -r NAME: Required. Name of the room (supports templates).
--identity ID, -i ID: Required. Identity of the subscribing participant (supports templates).
--subscribe, -s: Subscribe to the tracks.
--unsubscribe, -S: Unsubscribe from the tracks.

Examples

lk room update-subscriptions \
  --room my-room \
  --identity bob \
  --unsubscribe \
  TR_AMkSxxxxxx TR_VCkSxxxxxx

Send data

Send a data packet to participants in a room.

lk room send-data --room NAME [options] DATA

Options for room send-data:

DATA: Payload to send.
--room NAME, -r NAME: Required. Name of the room (supports templates).
--topic TOPIC: Topic of the message.
--identity ID: Recipient identity. Repeatable. Default: all participants.

Examples

lk room send-data --room my-room --topic chat '{"message": "Hello, everyone"}'

Participant commands

For the equivalent server SDK methods, see Managing participants.

lk room participants [command [command options]]

List participants

List the participants in a room.

lk room participants list ROOM_NAME

Get a participant

Print a participant's details, including tracks, as JSON.

lk room participants get --room NAME IDENTITY

Options for room participants get:

IDENTITY: Identity of the participant, or use --identity.
--room NAME, -r NAME: Required. Name of the room (supports templates).
--identity ID, -i ID: Identity of the participant (supports templates).

Remove a participant

Disconnect a participant. On LiveKit Cloud, this also revokes their token, so they need a new one to rejoin.

lk room participants remove --room NAME IDENTITY

Options for room participants remove:

IDENTITY: Identity of the participant, or use --identity.
--room NAME, -r NAME: Required. Name of the room (supports templates).
--identity ID, -i ID: Identity of the participant (supports templates).

Update a participant

Change a participant's metadata or permissions. Pass at least one of --metadata or --permissions.

lk room participants update --room NAME [options] IDENTITY

Options for room participants update:

IDENTITY: Identity of the participant, or use --identity.
--room NAME, -r NAME: Required. Name of the room (supports templates).
--identity ID, -i ID: Identity of the participant (supports templates).
--metadata METADATA: New metadata. Replaces the existing metadata.
--permissions JSON: Permission fields to change, in snake_case, such as can_publish or hidden. Unset fields keep their values.

Examples

lk room participants update \
  --room my-room \
  --permissions '{"can_publish": true}' \
  alice

Move a participant

Move a participant to another room. LiveKit Cloud only.

lk room participants move --room NAME --identity ID --destination-room NAME

Options for room participants move:

--room NAME, -r NAME: Required. Current room (supports templates).
--identity ID, -i ID: Required. Identity of the participant (supports templates).
--destination-room NAME: Required. Room to move the participant to.

Forward a participant

Forward a participant to another room. They stay in the source room, and their tracks are also shared to the destination. LiveKit Cloud only.

lk room participants forward --room NAME --identity ID --destination-room NAME

Options for room participants forward:

--room NAME, -r NAME: Required. Current room (supports templates).
--identity ID, -i ID: Required. Identity of the participant (supports templates).
--destination-room NAME: Required. Room to forward the participant to.

Token commands

The lk token command creates access tokens for clients and server API calls.

Create a token

Create a signed access token. Tokens are signed locally, so no server URL is needed.

lk token create [options]

Without grant flags, the CLI prompts for permissions. In non-interactive mode, such as with --yes or in CI, pass at least one grant flag.

Options for token create:

--room NAME, -r NAME: Room name (supports templates). Default: room-<timestamp>.
--identity ID, -i ID: Participant identity (supports templates). Default: participant-<random>.
--name NAME, -n NAME: Display name of the participant (supports templates). Default: the identity.
--join: Grant permission to join the room.
--admin: Grant permission to moderate the room.
--create: Grant permission to create and delete rooms.
--list: Grant permission to list rooms.
--egress: Grant permission to use LiveKit Egress.
--ingress: Grant permission to use LiveKit Ingress.
--inference: Grant permission to use LiveKit Inference.
--allow-update-metadata: Allow the participant to update their own name and metadata.
--allow-source SOURCE: Allowed publish sources: camera, microphone, screen_share, screen_share_audio. Comma-separated or repeatable. Default: all.
--metadata JSON: Participant metadata.
--attribute KEY=VALUE: Participant attribute. Repeatable.
--attribute-file JSON: JSON file of participant attributes, merged with --attribute.
--grant JSON: Extra video grant fields in camelCase, such as canPublish. Merged with other grant flags.
--valid-for TIME: Token lifetime, such as 30m or 1h10m. Default: 5m.
--agent NAME: Agent to dispatch when the participant joins. Requires --join.
--deployment NAME, -d NAME: Agent deployment. Default: production.
--job-metadata METADATA: Metadata for the dispatched agent job.
--json, -j: Output as JSON.
--token-only: Output only the token. Can't be used with --json.
--open APP: Open meet (LiveKit Meet ) or console (the agent console) in your browser with the token.

Examples

Create a subscribe-only token and save it to a variable:

TOKEN=$(lk token create \
  --join --room my-room --identity viewer \
  --grant '{"canPublish": false, "canPublishData": false}' \
  --token-only)

Dispatch an agent on join and open the room in LiveKit Meet:

lk token create \
  --join --room support-%t --identity customer \
  --agent my-agent \
  --job-metadata '{"plan": "ship"}' \
  --open meet

Dispatch commands

For how explicit dispatch works, see Dispatch via API.

List dispatches

List the agent dispatches in a room.

lk dispatch list [options] ROOM_NAME

Add --json (-j) to output JSON.

Get a dispatch

Get an agent dispatch by ID.

lk dispatch get [options] ROOM_NAME DISPATCH_ID

Add --json (-j) to output JSON.

Create a dispatch

Dispatch an agent to a room, creating the room if needed.

lk dispatch create --agent-name NAME [--room NAME | --new-room] [options]

Options for dispatch create:

--agent-name NAME: Required. Name of the agent to dispatch.
--room NAME: Room to dispatch to. Required unless you pass --new-room.
--new-room: Use a generated room name (room-<random>). Overrides --room.
--deployment NAME, -d NAME: Agent deployment. Default: production.
--metadata METADATA: Job metadata for the agent.
--json, -j: Output as JSON.

Examples

lk dispatch create \
  --room my-room \
  --agent-name my-agent \
  --metadata '{"user_id": "12345"}'

Delete a dispatch

Delete an agent dispatch by ID.

lk dispatch delete [options] ROOM_NAME DISPATCH_ID

Add --json (-j) to output JSON.

Overview

Credentials

Test a room with LiveKit Meet

Generate an access token

Connect with LiveKit Meet

LiveKit Meet

Simulate another publisher

Room commands

Create a room

Examples

List rooms

Examples

Update room metadata

Examples

Delete a room

Join a room

Publishing from a socket

Examples

Mute or unmute a track

Examples

Update track subscriptions

Examples

Send data

Examples

Participant commands

List participants

Get a participant

Remove a participant

Update a participant

Examples

Move a participant

Forward a participant

Token commands

Create a token

Examples

Dispatch commands

List dispatches

Get a dispatch

Create a dispatch

Examples

Delete a dispatch

Ask LiveKit