Egress and ingress

Overview

Use the lk egress commands to record or stream media out of LiveKit with LiveKit Egress, and the lk ingress commands to bring outside media sources into a room with LiveKit Ingress. To install the CLI, see Install the CLI.

To choose a project, pass --project PROJECT_NAME or set a default with lk project set-default.

lk egress [command [command options]]
lk ingress [command [command options]]

Request JSON

The egress start, ingress create, and ingress update commands take the API request as JSON, using protobuf field names such as room_name. Pass a path, a literal JSON string, or - to read from standard input. Unknown fields cause an error. For more examples, see the LiveKit CLI repository .

Egress commands

Start

Start a new egress from a StartEgressRequest. The command prints the new egress ID and status.

lk egress start [options] REQUEST_JSON

Options for egress start:

• REQUEST_JSON: Request JSON. See Request JSON.
• --type TYPE: Deprecated. Reads REQUEST_JSON as a source-specific request. Valid values: room-composite (RoomCompositeEgressRequest), participant (ParticipantEgressRequest), track (TrackEgressRequest), track-composite (TrackCompositeEgressRequest), and web (WebEgressRequest).

For sources, outputs, and storage settings, see Egress sources and Output and streaming options.

Examples

Record a room to an MP4 file in S3. Create room-recording.json:

{
  "room_name": "my-room",
  "template": {
    "layout": "speaker-dark"
  },
  "outputs": [
    {
      "file": {
        "filepath": "recordings/my-room.mp4"
      }
    }
  ],
  "storage": {
    "s3": {
      "access_key": "<aws-access-key>",
      "secret": "<aws-access-secret>",
      "region": "us-east-1",
      "bucket": "my-bucket"
    }
  }
}

Then start the egress:

lk egress start room-recording.json

Record a single video track, passing the request as a literal JSON string:

lk egress start '{
  "room_name": "my-room",
  "media": { "video_track_id": "TR_xxxxxxxxxxxx" },
  "outputs": [{ "file": { "filepath": "my-track.mp4" } }]
}'

List

List egresses for the project, in any state by default.

lk egress list [options]

Options for egress list:

• --id ID: List a specific egress. Repeatable. Overrides --room, --active, and --limit.
• --room NAME: List only egresses for the room NAME.
• --active, -a: List only active egresses. Default: false.
• --limit NUMBER: Maximum number of egresses to return. Default: one page of results.
• --json, -j: Output as JSON. Default: false.

Examples

List active egresses in a room:

lk egress list --room my-room --active

Stop

Stop one or more active egresses.

lk egress stop --id EGRESS_ID [--id EGRESS_ID ...]

Options for egress stop:

• --id EGRESS_ID: Required. ID of the egress to stop. Repeatable.

Examples

lk egress stop --id EG_xxxxxxxxxxxx --id EG_yyyyyyyyyyyy

Test-template

Preview a custom recording template in your browser with simulated publishers and active speakers, without starting an egress. Press Ctrl+C to stop.

lk egress test-template --base-url URL --publishers NUMBER [options]

Options for egress test-template:

• --base-url URL: Required. Base URL of your template, for example http://localhost:5173.
• --publishers NUMBER: Required. Number of simulated video publishers.
• --layout TYPE: Layout name passed to the template, such as grid or speaker.
• --room NAME: Name of the room to create. Default: layout-demo-<unix-timestamp>.

For a walkthrough, see Test your template.

Examples

Preview a local template with four publishers in a grid layout:

lk egress test-template \
  --base-url http://localhost:5173 \
  --room my-room \
  --layout grid \
  --publishers 4

Update-layout

Change the layout of an active room composite egress. See Default layouts.

lk egress update-layout --id EGRESS_ID --layout LAYOUT

Options for egress update-layout:

• --id EGRESS_ID: Required. ID of the egress to update.
• --layout LAYOUT: Required. New layout name, such as grid or speaker-light.

Examples

Switch a room recording to the grid layout:

lk egress update-layout --id EG_xxxxxxxxxxxx --layout grid

Update-stream

Add or remove RTMP output URLs on an active streaming egress. See UpdateStream.

lk egress update-stream --id EGRESS_ID [--add-urls URL ...] [--remove-urls URL ...]

Options for egress update-stream:

• --id EGRESS_ID: Required. ID of the egress to update.
• --add-urls URL: RTMP URL to add. Repeatable.
• --remove-urls URL: RTMP URL to remove. Repeatable.

Examples

Replace one destination with another:

lk egress update-stream \
  --id EG_xxxxxxxxxxxx \
  --add-urls rtmp://live.twitch.tv/app/<new-stream-key> \
  --remove-urls rtmp://live.twitch.tv/app/<old-stream-key>

Ingress commands

Create

Create an ingress from a CreateIngressRequest. The command prints the ingress ID, URL, and stream key.

lk ingress create JSON

Options for ingress create:

• JSON: Request JSON. See Request JSON.

Set input_type to RTMP_INPUT (default), WHIP_INPUT, or URL_INPUT. See Supported sources.

Examples

Create an RTMP ingress. Create rtmp-ingress.json:

{
  "input_type": "RTMP_INPUT",
  "name": "my-ingress",
  "room_name": "my-room",
  "participant_identity": "rtmp-publisher",
  "participant_name": "RTMP publisher"
}

Then create the ingress:

lk ingress create rtmp-ingress.json

Create a URL ingress that pulls an HLS stream:

lk ingress create '{
  "input_type": "URL_INPUT",
  "name": "hls-ingress",
  "room_name": "my-room",
  "participant_identity": "hls-source",
  "url": "https://example.com/stream/playlist.m3u8"
}'

Update

Update an ingress from an UpdateIngressRequest, which must include ingress_id. Only reusable ingresses, such as RTMP or WHIP, can be updated.

lk ingress update JSON

Options for ingress update:

• JSON: Request JSON. See Request JSON.

Examples

Point an existing ingress at a different room:

lk ingress update '{
  "ingress_id": "IN_xxxxxxxxxxxx",
  "room_name": "another-room"
}'

List

List ingresses for the project.

lk ingress list [options]

Options for ingress list:

• --room NAME: List only ingresses for the room NAME.
• --id ID: List a specific ingress.
• --limit NUMBER: Maximum number of ingresses to return. Default: one page of results. Ignored with --id.
• --json, -j: Output as JSON. Default: false.

Examples

Get a specific ingress as JSON:

lk ingress list --id IN_xxxxxxxxxxxx --json

Delete

Delete an ingress.

lk ingress delete INGRESS_ID

Options for ingress delete:

• INGRESS_ID: ID of the ingress to delete.

Examples

lk ingress delete IN_xxxxxxxxxxxx