Livekit Cli

LiveKit CLI

The LiveKit CLI (lk) provides command-line tools for managing LiveKit Cloud projects, creating applications from templates, deploying agents, and configuring telephony.

LiveKit MCP server tools

This skill works alongside the LiveKit MCP server, which provides direct access to the latest LiveKit documentation, code examples, and changelogs. Use these tools when you need up-to-date information that may have changed since this skill was created.

Available MCP tools:

• docs_search - Search the LiveKit docs site
• get_pages - Fetch specific documentation pages by path
• get_changelog - Get recent releases and updates for LiveKit packages
• code_search - Search LiveKit repositories for code examples
• get_python_agent_example - Browse 100+ Python agent examples

When to use MCP tools:

• You need the latest API documentation or feature updates
• You're looking for recent examples or code patterns
• You want to check if a feature has been added in recent releases
• The local references don't cover a specific topic

When to use local references:

• You need quick access to core concepts covered in this skill
• You're working offline or want faster access to common patterns
• The information in the references is sufficient for your needs

Use MCP tools and local references together for the best experience.

References

Consult these resources as needed:

• ./references/livekit-overview.md -- LiveKit ecosystem overview
• ./references/project-commands.md -- Project management and token generation
• ./references/agent-commands.md -- Agent deployment and management
• ./references/telephony-commands.md -- Phone numbers and SIP configuration

Installation

macOS (Homebrew):

brew install livekit-cli

Linux:

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

Windows (winget):

winget install LiveKit.LiveKitCLI

Update the CLI regularly to get the latest features:

# macOS
brew update && brew upgrade livekit-cli

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

# Windows
winget upgrade LiveKit.LiveKitCLI

Authentication

Link your LiveKit Cloud project to the CLI:

lk cloud auth

This opens a browser window to sign in to LiveKit Cloud and select a project. The CLI stores your credentials locally and generates API keys for your CLI instance.

To revoke authorization:

lk cloud auth --revoke

Project management

List all configured projects (default marked with *):

lk project list

Set a different project as default:

lk project set-default <project-name>

Add a self-hosted project manually:

lk project add my-project \
  --url http://localhost:7880 \
  --api-key <my-api-key> \
  --api-secret <my-api-secret> \
  --default

Remove a project from the CLI:

lk project remove <project-name>

Environment variables

Load LiveKit Cloud credentials into a .env.local file:

lk app env -w

This writes LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET to your local environment file.

Create apps from templates

Bootstrap a new application from a template:

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

Run without --template to see all available templates:

lk app create

Available templates:

Note: Templates may be updated over time. Run lk app create without arguments to see the current list interactively.

Generate access tokens

Create an access token for joining rooms:

# For LiveKit Cloud
lk token create \
  --api-key <PROJECT_KEY> --api-secret <PROJECT_SECRET> \
  --join --room test_room --identity test_user \
  --valid-for 24h

# For local development (dev mode)
lk token create \
  --api-key devkey --api-secret secret \
  --join --room test_room --identity test_user \
  --valid-for 24h

Test with simulated participants

Join a room as a simulated participant with demo video:

# For LiveKit Cloud
lk room join \
  --url <PROJECT_SECURE_WEBSOCKET_ADDRESS> \
  --api-key <PROJECT_API_KEY> --api-secret <PROJECT_SECRET_KEY> \
  --publish-demo --identity bot_user \
  my_first_room

# For local development
lk room join \
  --url ws://localhost:7880 \
  --api-key devkey --api-secret secret \
  --publish-demo --identity bot_user \
  my_first_room

Deploy agents

Deploy your first agent to LiveKit Cloud:

cd your-agent-project
lk cloud auth
lk agent create

This registers your agent, creates a livekit.toml configuration file, builds a container image, and deploys it.

Deploy a new version:

lk agent deploy

Monitor your agent:

lk agent status   # Check status and replicas
lk agent logs     # View runtime logs

For more agent commands, see ./references/agent-commands.md.

Phone numbers

Search and purchase US phone numbers:

lk number search --country-code US --area-code 415
lk number purchase --numbers +14155550100
lk number list

For more telephony commands, see ./references/telephony-commands.md.

Best practices

1. Keep the CLI updated to access the latest features and bug fixes. 2. Use `lk app env -w` to load credentials into your local environment instead of hardcoding them. 3. Use templates to bootstrap new projects with best practices already configured. 4. Test locally first with lk room join before deploying to production. 5. Monitor deployments with lk agent status and lk agent logs after deploying.

Agent deployment commands

The LiveKit CLI provides commands for deploying and managing agents on LiveKit Cloud. All agent commands are prefixed with lk agent.

Prerequisites

• Latest version of the LiveKit CLI
• A LiveKit Cloud project linked via lk cloud auth
• A working agent project

Create and deploy an agent

Register and deploy a new agent:

cd your-agent-project
lk agent create

This command: 1. Registers your agent with LiveKit Cloud and assigns a unique ID 2. Creates a livekit.toml configuration file 3. Creates a Dockerfile if one doesn't exist 4. Uploads your code to the build service 5. Builds a container image 6. Deploys to your LiveKit Cloud project

Options for create

• --region REGION: Region code for the agent deployment
• --secrets KEY=VALUE: Secrets injected as environment variables (can use multiple times)
• --secrets-file FILE: File containing secret KEY=VALUE pairs, one per line
• --secret-mount FILE: Path to a file to mount as a secret in the container
• --config FILE: Name of the configuration file (default: livekit.toml)
• --silent: Do not prompt for interactive confirmation

Deploy new versions

Deploy an updated version of your agent:

lk agent deploy

LiveKit Cloud uses rolling deployments: 1. Builds a new container image from your code 2. Deploys new instances alongside existing ones 3. Routes new sessions to new instances 4. Gives old instances up to 1 hour to complete active sessions 5. Autoscales based on demand

Options for deploy

• --secrets KEY=VALUE: Update secrets during deployment
• --secrets-file FILE: File containing secrets to update
• --secret-mount FILE: File to mount as a secret

You can also deploy from a specific directory:

lk agent deploy /path/to/agent

Monitor status

Check the status of your deployed agent:

lk agent status

This shows:

• Current deployment status
• Number of replicas running
• Health information

View logs

Stream runtime logs from your agent:

lk agent logs

This shows a live tail of logs from the newest agent server instance, including recent log history.

View build logs from the current deployment:

lk agent logs --log-type=build

Rollback

Revert to a previous version without rebuilding:

lk agent rollback

Rollback uses the same rolling deployment strategy as regular deployments. This feature requires a paid LiveKit Cloud plan.

Configuration file

The livekit.toml file contains your agent's deployment configuration:

[project]
  subdomain = "<my-project-subdomain>"

[agent]
  id = "<agent-id>"

Generate a new configuration file:

lk agent config

Secrets management

List secrets

View all secrets for your agent (values are hidden):

lk agent secrets

Update secrets

Add or update secrets:

# From individual values
lk agent update-secrets --secrets "API_KEY=value" --secrets "OTHER_KEY=value"

# From a file
lk agent update-secrets --secrets-file=.env.production

# Replace all secrets (delete existing, add new)
lk agent update-secrets --secrets-file=new-secrets.env --overwrite

File-mounted secrets

Mount a file as a secret (available at /etc/secret/<filename>):

lk agent update-secrets --secret-mount ./google-application-credentials.json

Automatic secrets

LiveKit Cloud automatically provides these environment variables:

• LIVEKIT_URL - Your LiveKit Cloud server URL
• LIVEKIT_API_KEY - API key for your project
• LIVEKIT_API_SECRET - API secret for your project

These cannot be set or modified manually.

Secret naming rules

• Only letters, numbers, and underscores allowed
• Maximum 70 characters
• Case sensitive
• Recommended: uppercase letters and underscores (e.g., MY_API_KEY)

Log forwarding

Forward logs to external services by adding their credentials as secrets:

Datadog:

lk agent update-secrets --secrets "DATADOG_TOKEN=your-client-token"
lk agent update-secrets --secrets "DATADOG_REGION=us1"  # Optional, default: us1

CloudWatch:

lk agent update-secrets \
  --secrets "AWS_ACCESS_KEY_ID=your-key-id" \
  --secrets "AWS_SECRET_ACCESS_KEY=your-secret-key" \
  --secrets "AWS_REGION=us-west-2"  # Optional, default: us-west-2

Sentry:

lk agent update-secrets --secrets "SENTRY_DSN=your-sentry-dsn"

New Relic:

lk agent update-secrets --secrets "NEW_RELIC_LICENSE_KEY=your-license-key"

Build requirements

The build process has a 10-minute timeout. To optimize builds:

1. Use a proper .dockerignore to exclude unnecessary files 2. Download ML models during build, not at runtime (use download-files command) 3. Never include .env files or secrets in your image 4. Use lockfiles for reproducible builds

Dockerfile tips

The CLI generates a Dockerfile automatically, but if you customize it:

• Use glibc-based images (Debian/Ubuntu), not Alpine
• Don't run as root
• Set an explicit WORKDIR
• Use the start command in your CMD/ENTRYPOINT

LiveKit overview

LiveKit is a realtime communication platform for building AI-native applications with audio, video, and data streaming. This overview helps you understand the LiveKit ecosystem and how to use these skills effectively.

Platform components

LiveKit Cloud

LiveKit Cloud is a fully managed platform for building, deploying, and operating AI agent applications. It includes:

• Realtime media infrastructure - Global mesh of servers for low-latency audio, video, and data streaming
• Managed agent hosting - Deploy agents without managing servers or orchestration
• LiveKit Inference - Run AI models directly within LiveKit Cloud without API keys
• Native telephony - Provision phone numbers and connect PSTN calls directly to rooms
• Observability - Built-in analytics, logs, and quality metrics

Agents framework

The Agents framework lets you build Python or Node.js programs that join LiveKit rooms as realtime participants. Key capabilities:

• Voice pipelines - Stream audio through STT-LLM-TTS pipelines
• Realtime models - Use models like OpenAI Realtime API that handle speech directly
• Tool calling - Define functions the LLM can invoke during conversations
• Multi-agent workflows - Hand off between specialized agents
• Turn detection - State-of-the-art model for natural conversation flow

Architecture

┌─────────────┐     WebRTC      ┌─────────────┐     HTTP/WS      ┌─────────────┐
│   Frontend  │ ◄─────────────► │   LiveKit   │ ◄──────────────► │    Agent    │
│  (Web/App)  │                 │    Room     │                  │   Server    │
└─────────────┘                 └─────────────┘                  └─────────────┘
                                       │                                │
                                       │                                │
                                       ▼                                ▼
                                ┌─────────────┐                  ┌─────────────┐
                                │  Telephony  │                  │  AI Models  │
                                │    (SIP)    │                  │ (STT/LLM/TTS)│
                                └─────────────┘                  └─────────────┘

How these skills work together

The LiveKit skills cover the full stack for building voice AI applications:

Typical workflow:

1. Choose your backend - Use agents-py or agents-ts based on your team's preference 2. Build the frontend - Use agents-ui for React-based web interfaces 3. Connect via LiveKit - Both connect to the same LiveKit room for realtime communication

Using the skills effectively

When to use each skill

• Building a new voice agent? Start with agents-py or agents-ts for the backend logic
• Need a web interface? Add agents-ui for pre-built React components
• Full-stack project? Use both a backend skill and agents-ui together

Combining skills

The skills are designed to work together. A typical project structure:

my-voice-app/
├── agent/           # Use agents-py or agents-ts skill
│   └── agent.py     # or agent.ts
├── frontend/        # Use agents-ui skill
│   └── src/
│       └── app/
└── .env.local       # Shared LiveKit credentials

Environment setup

All skills require LiveKit credentials:

LIVEKIT_API_KEY=your_api_key
LIVEKIT_API_SECRET=your_api_secret
LIVEKIT_URL=wss://your-project.livekit.cloud

Get these from your LiveKit Cloud dashboard or self-hosted deployment.

Resources

• LiveKit documentation
• Agents framework guide
• LiveKit Cloud
• GitHub repositories

Project management commands

The LiveKit CLI provides commands for managing projects and generating access tokens. A project consists of a URL, API key, and API secret that point to a LiveKit deployment.

Cloud authentication

Authenticate with LiveKit Cloud

Link your LiveKit Cloud account to the CLI:

lk cloud auth

This opens a browser-based flow to sign in and select a project. LiveKit Cloud generates API keys for your CLI instance and adds the project automatically.

Options:

• --timeout SECONDS, -t SECONDS: Seconds before giving up (default: 900)
• --poll-interval SECONDS, -i SECONDS: Seconds between poll requests (default: 4)

To link multiple projects, run lk cloud auth multiple times.

Revoke authorization

Remove a project and revoke its API keys:

lk cloud auth --revoke

Options:

• --project PROJECT_NAME: Name of the project to revoke (default: current default project)

This revokes the API keys stored in your CLI instance. Any copies of these keys made with lk app env or lk app create are also revoked.

Project commands

List projects

Show all configured projects (default marked with *):

lk project list

Example output:

┌──────────────────────┬──────────────────────────────────────────────────┬───────────────┐
│ Name                 │ URL                                              │ API Key       │
├──────────────────────┼──────────────────────────────────────────────────┼───────────────┤
│   dev-local          │ http://localhost:7880                            │ APIxxxxxxxxxx │
│   staging            │ wss://staging-abc123.livekit.cloud               │ APIyyyyyyyyyy │
│ * production         │ wss://production-xyz789.livekit.cloud            │ APIzzzzzzzzzz │
└──────────────────────┴──────────────────────────────────────────────────┴───────────────┘

Options:

• --json, -j: Output as JSON, including API key and secret

Add a project

Add a self-hosted or manual project:

lk project add PROJECT_NAME \
  --url LIVEKIT_URL \
  --api-key API_KEY \
  --api-secret API_SECRET \
  [--default]

Options:

• PROJECT_NAME: Unique name for the project in your CLI instance
• --url URL: WebSocket URL of the LiveKit server
• --api-key KEY: Project API key
• --api-secret SECRET: Project API secret
• --default: Set this project as the default

Example (self-hosted):

lk project add my-local \
  --url http://localhost:7880 \
  --api-key devkey \
  --api-secret secret \
  --default

Set default project

Change the default project used by other commands:

lk project set-default PROJECT_NAME

Remove a project

Remove a project from your local CLI configuration:

lk project remove PROJECT_NAME

This does not affect the project in LiveKit Cloud. For Cloud projects, use lk cloud auth --revoke to also revoke the API keys.

Environment variables

Load credentials to file

Write LiveKit credentials to a local environment file:

lk app env -w

This creates or updates .env.local with:

• LIVEKIT_URL
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET

Token generation

Create an access token

Generate a token for joining rooms:

lk token create \
  --api-key <API_KEY> --api-secret <API_SECRET> \
  --join --room <ROOM_NAME> --identity <USER_IDENTITY> \
  --valid-for <DURATION>

Options:

• --api-key KEY: API key for signing the token
• --api-secret SECRET: API secret for signing the token
• --join: Grant permission to join rooms
• --room ROOM: Name of the room to join
• --identity IDENTITY: Unique identity for the participant
• --valid-for DURATION: Token validity period (e.g., 24h, 1h30m)

Example for LiveKit Cloud:

lk token create \
  --api-key <PROJECT_KEY> --api-secret <PROJECT_SECRET> \
  --join --room test_room --identity test_user \
  --valid-for 24h

Example for local development (dev mode):

lk token create \
  --api-key devkey --api-secret secret \
  --join --room test_room --identity test_user \
  --valid-for 24h

App templates

Create from template

Bootstrap a new application:

lk app create --template <TEMPLATE_NAME> <APP_NAME>

Run without --template to see available templates interactively:

lk app create

Available templates:

Room commands

Join a room

Join a room as a simulated participant:

lk room join \
  --url <LIVEKIT_URL> \
  --api-key <API_KEY> --api-secret <API_SECRET> \
  --identity <IDENTITY> \
  <ROOM_NAME>

Options:

• --publish-demo: Publish a looped demo video to the room

Example for LiveKit Cloud:

lk room join \
  --url wss://my-project.livekit.cloud \
  --api-key <API_KEY> --api-secret <API_SECRET> \
  --publish-demo --identity bot_user \
  my_room

Example for local development:

lk room join \
  --url ws://localhost:7880 \
  --api-key devkey --api-secret secret \
  --publish-demo --identity bot_user \
  my_room

This is useful for testing multi-user sessions or simulating participants publishing media.

Telephony commands

The LiveKit CLI provides commands for managing phone numbers and SIP configuration. These commands help you set up inbound and outbound calling for your voice AI agents.

Phone number commands

Note: LiveKit Phone Numbers currently only supports inbound calling. Support for outbound calls is coming soon.

All phone number commands are prefixed with lk number.

Search available numbers

Search for phone numbers available for purchase:

lk number search --country-code US --area-code 415

Options:

• --country-code STRING: Filter by country code (e.g., "US", "CA"). Required.
• --area-code STRING: Filter by area code (e.g., "415")
• --limit INT: Maximum number of results (default: 50)
• --json, -j: Output as JSON

Example:

lk number search --country-code US --area-code 415 --limit 10

Purchase numbers

Buy phone numbers from inventory:

lk number purchase --numbers +14155550100

Options:

• --numbers STRING: Phone numbers to purchase (e.g., "+16505550010"). Required.
• --sip-dispatch-rule-id STRING: SIP dispatch rule ID to apply to purchased numbers

List numbers

List phone numbers for your project:

lk number list

Options:

• --limit INT: Maximum number of results (default: 50)
• --status STRING: Filter by status: active, pending, released (can use multiple times)
• --sip-dispatch-rule-id STRING: Filter by SIP dispatch rule ID
• --json, -j: Output as JSON

Examples:

# List all active numbers
lk number list

# List active and released numbers
lk number list --status active --status released

Get number details

Get details for a specific phone number:

lk number get --id <PHONE_NUMBER_ID>
# or
lk number get --number +16505550010

Options:

• --id STRING: Phone number ID for direct lookup
• --number STRING: Phone number string for lookup

Update number

Update a phone number's configuration:

lk number update --id <PHONE_NUMBER_ID> --sip-dispatch-rule-id <DISPATCH_RULE_ID>

Options:

• --id STRING: Phone number ID
• --number STRING: Phone number string (alternative to --id)
• --sip-dispatch-rule-id STRING: Dispatch rule ID to assign

Example:

lk number update --number +16505550010 --sip-dispatch-rule-id <RULE_ID>

Release numbers

Release phone numbers:

lk number release --ids <PHONE_NUMBER_ID>
# or
lk number release --numbers +16505550010

Options:

• --ids STRING: Phone number IDs to release
• --numbers STRING: Phone number strings to release

SIP inbound trunk commands

Inbound trunks control how incoming calls are authenticated and processed. Commands are prefixed with lk sip inbound.

Create inbound trunk

Create a trunk from a JSON file:

lk sip inbound create inbound-trunk.json

Example JSON (inbound-trunk.json):

{
  "trunk": {
    "name": "My trunk",
    "numbers": ["+15105550100"],
    "krispEnabled": true
  }
}

Trunk with allowed callers:

{
  "trunk": {
    "name": "My trunk",
    "numbers": ["+15105550100"],
    "allowedNumbers": ["+13105550100", "+17145550100"]
  }
}

List inbound trunks

List all inbound trunks:

lk sip inbound list

Update inbound trunk

Update an existing trunk:

lk sip inbound update --id <trunk-id> inbound-trunk.json

SIP outbound trunk commands

Outbound trunks are used for making calls. Commands are prefixed with lk sip outbound.

List outbound trunks

List all outbound trunks:

lk sip outbound list

SIP dispatch rule commands

Dispatch rules control how callers are added to rooms. Commands are prefixed with lk sip dispatch.

Create dispatch rule

Create a dispatch rule from a JSON file:

lk sip dispatch create dispatch-rule.json

Individual dispatch rule (creates a new room per caller):

{
  "dispatch_rule": {
    "rule": {
      "dispatchRuleIndividual": {
        "roomPrefix": "call-"
      }
    },
    "name": "My dispatch rule",
    "roomConfig": {
      "agents": [{
        "agentName": "inbound-agent",
        "metadata": "job dispatch metadata"
      }]
    }
  }
}

Direct dispatch rule (all callers join the same room):

{
  "dispatch_rule": {
    "rule": {
      "dispatchRuleDirect": {
        "roomName": "open-room"
      }
    },
    "name": "My dispatch rule"
  }
}

Pin-protected room:

{
  "dispatch_rule": {
    "rule": {
      "dispatchRuleDirect": {
        "roomName": "safe-room",
        "pin": "12345"
      }
    },
    "name": "My dispatch rule"
  }
}

Callee dispatch rule (room based on called number):

{
  "dispatch_rule": {
    "rule": {
      "dispatchRuleCallee": {
        "roomPrefix": "number-",
        "randomize": false
      }
    },
    "name": "My dispatch rule"
  }
}

List dispatch rules

List all dispatch rules:

lk sip dispatch list

Update dispatch rule

Update an existing dispatch rule:

lk sip dispatch update --id <dispatch-rule-id> --trunks "[]" dispatch-rule.json

Options:

• --id STRING: Dispatch rule ID to update
• --trunks STRING: Comma-separated trunk IDs (use "[]" for all trunks)

Setting up inbound calling

Complete setup for accepting inbound calls:

1. Purchase a phone number:

   lk number search --country-code US --area-code 415
   lk number purchase --numbers +14155550100

2. Create a dispatch rule (save as dispatch-rule.json):

   {
     "dispatch_rule": {
       "rule": {
         "dispatchRuleIndividual": {
           "roomPrefix": "call-"
         }
       },
       "name": "Inbound calls",
       "roomConfig": {
         "agents": [{
           "agentName": "my-voice-agent"
         }]
       }
     }
   }

   lk sip dispatch create dispatch-rule.json

3. Assign the dispatch rule to your number:

   lk number list  # Get the phone number ID
   lk number update --id <PHONE_NUMBER_ID> --sip-dispatch-rule-id <DISPATCH_RULE_ID>

4. Deploy your agent with the name specified in the dispatch rule:

   lk agent create

Dispatch rule types

SIP trunk providers

If you're using a third-party SIP provider instead of LiveKit Phone Numbers, you'll need to create inbound/outbound trunks. Supported providers include:

• Twilio
• Telnyx
• Plivo
• Wavix

See the LiveKit telephony documentation for provider-specific setup guides.