Agent commands

Overview

The LiveKit CLI is the primary interface for working with LiveKit agents. Use lk agent commands to develop and test agents locally, or to deploy and manage agents on LiveKit Cloud. Every agent command starts with lk agent. You can abbreviate this as lk a. For example, lk a console does the same as lk agent console.

For instructions on installing the CLI, see the LiveKit CLI Setup guide.

Working directory

The default working directory for each command is the current directory. You can override the working directory by passing it as the first regular argument.

For example, this command deploys the agent in the current directory:

lk agent deploy

While this command deploys the agent in the named directory:

lk agent deploy ~/my-agent

Project and agent identification

If a livekit.toml file is present in the working directory, the CLI uses the project and agent configuration from that file by default.

If no livekit.toml file is present, the CLI uses the default project. You must also specify the agent ID with the --id flag for commands that operate on an existing agent.

Targeting a deployment

The create, deploy, promote, logs, and delete subcommands accept an optional --deployment <name> flag (alias -d) to target a non-production deployment of the agent. Omit the flag to target the reserved production deployment.

--deployment NAME (alias -d): Name of the deployment to target. An empty or omitted value targets the reserved production deployment. For name constraints, see Deployment names. Invalid names are rejected by the server with an error rather than targeting production.

The status, versions, and list subcommands instead show a deployment column in their output rather than taking a --deployment flag.

Local development commands

Use these commands to run your agent on your own machine during development. Unlike the Cloud management commands, they execute your agent code locally.

lk agent [start|dev|console] [lk options] [entrypoint] [-- runtime-args]

Each command accepts an optional entrypoint. Arguments after -- are passed to the Node.js or Python runtime that starts your agent, before the entrypoint. They aren't passed to your agent.

The --log-level option for start and dev also accepts CRITICAL for Python and FATAL for Node.js. The CLI adjusts the case of the value for your runtime.

Entrypoint detection

When you don't pass an entrypoint, the CLI resolves one automatically:

1. It detects the project type by searching the working directory and its parents for a project manifest, which is package.json for Node.js, or uv.lock, requirements.txt, or pyproject.toml for Python. If none is found, the command errors.
2. It then looks for a conventional entrypoint file, in order: agent.py then src/agent.py for Python, and main.ts then src/main.ts or src/main.js for Node.js. If you run from a subdirectory of the project root, the CLI also checks these paths relative to your current directory.

The official starter templates (agent-starter-python and agent-starter-node) use src/agent.py and src/main.ts, so you can run these commands from the project root with no argument:

lk agent dev

Pass an explicit path when your entrypoint uses a different name, for example, a single-file recipe:

lk agent console answer_call.py

Start

Run the agent in production mode, with clean logging and graceful shutdown on SIGINT or SIGTERM. A deployed agent runs in production mode through the container's start command. Run lk agent start locally to test the same behavior.

lk agent start [command options] [entrypoint]

Options for start:

• --log-level LEVEL: Log level. One of TRACE, DEBUG, INFO, WARN, ERROR.

Examples

Run the auto-detected agent entrypoint:

lk agent start

Pass an option to the runtime after --. This example passes an environment file to Node.js:

lk agent start -- --env-file=.env.production

Dev

Run the agent in development mode. This mode outputs human-friendly colored logs and reloads automatically when you change source files.

lk agent dev [command options] [entrypoint]

Options for dev:

• --log-level LEVEL: Log level. One of TRACE, DEBUG, INFO, WARN, ERROR.
• --no-reload: Disable auto-reload on file changes.

Examples

Run the auto-detected agent entrypoint with auto-reload:

lk agent dev

Run a specific file at the debug log level:

lk agent dev src/agent.py --log-level DEBUG

Console

Talk to your agent locally through your computer's microphone and speakers. Console mode simulates a room without connecting to LiveKit Cloud, so it's the fastest way to test an agent. Because the room is simulated, it has no job metadata—to test with metadata, use the Agent Console.

lk agent console [command options] [entrypoint]

Options for console:

• --text, -t: Start in text mode instead of audio mode.
• --input-device NAME: Input device index or name substring.
• --output-device NAME: Output device index or name substring.
• --list-devices: List available audio devices and exit.
• --no-aec: Disable acoustic echo cancellation.
• --record: Record audio and a session report to console-recordings/.
• --port PORT, -p PORT: TCP port for agent communication. Default: 0 (auto-select).

Examples

Start a voice session with the auto-detected entrypoint:

lk agent console

Start in text mode:

lk agent console --text

Select specific audio devices:

lk agent console --input-device "MacBook Pro Microphone" --output-device "External Headphones"

Cloud management commands

The following commands manage agents deployed to LiveKit Cloud:

Init

Initialize a new LiveKit Cloud agent project (Python or Node.js SDK). This command scaffolds a code project from a template (or custom URL) and can deploy to LiveKit Cloud in one step. Use this when starting an agent from scratch.

lk agent init [options] [AGENT-NAME]

Options for init:

• AGENT-NAME: Optional name for the new agent project. If omitted, the CLI prompts you. The starter templates use this value as both the project directory name and the agent's dispatch name (agent_name for Python, agentName for Node.js). To change the dispatch name later, edit the source code directly.
• --region REGION: Region code to deploy the agent to. If unset, the CLI deploys to the nearest region.
• --deploy: Deploy the agent to LiveKit Cloud after initialization. Default: false.
• --template TEMPLATE: Template to instantiate. For example, agent-starter-python or agent-starter-node. See App templates for the full list.
• --template-url URL: Custom URL to a repository or archive to instantiate (for example, a Git repo URL). The project at that URL must include a taskfile.yaml file at its root.
• --sandbox NAME: Deprecated no-op. Accepted for backwards compatibility, but init no longer creates sandbox apps.
• --no-sandbox: Deprecated no-op. Accepted for backwards compatibility. Default: false.

Examples

Initialize a new agent in the current directory (CLI will prompt for name and options):

lk agent init

Initialize a named agent and deploy to LiveKit Cloud in one step:

lk agent init my-voice-agent --deploy

Initialize from a specific template and region:

lk agent init my-agent --template agent-starter-python --region us-east

Simulate

Run agent simulations to evaluate whole conversations against an LLM-driven simulated user. By default, the CLI starts your agent as a local worker and runs the simulation on LiveKit Cloud. Simulations are in beta and currently support Python agents only.

lk agent simulate [options] [entrypoint]

If you don't pass an entrypoint, the CLI uses the first of agent.py or src/agent.py that it finds in the working directory. Pass the entrypoint explicitly if your agent code is in a different directory or file.

Options for simulate:

• -n, --num-simulations N: Number of scenarios to generate from the agent's source.
• --scenarios FILE: Path to a scenarios.yaml file. When set, scenarios come from the file instead of being generated from source.
• --concurrency N: Maximum number of simulations to run in parallel. Defaults to the per-project limit and cannot exceed it.
• --agent-name NAME: Run against an already-running agent instead of spawning one locally. Pass the registered name, or an empty string ("") to target the project's default agent that auto-joins every room. Requires --scenarios.
• --yes, -y: Skip the source-upload confirmation prompt. Required for non-interactive runs that generate scenarios from source.
• --view RUN_ID: Open a previous simulation run by its ID instead of starting a new one.
• --audio: Simulate speech-to-speech interactions using the agent's full audio pipeline. Audio mode isn't available yet; simulations currently run in text mode.

Examples

Generate and run 10 scenarios from the agent's source:

lk agent simulate -n 10

Run a checked-in scenario file:

lk agent simulate --scenarios scenarios.yaml

Run scenarios against an already-running agent:

lk agent simulate --scenarios scenarios.yaml --agent-name my-agent

Create

Create a new agent using configuration in the working directory and optional secrets. You must not already have a configuration file for the agent (default name is livekit.toml). If no Dockerfile is present, the CLI creates one for you.

lk agent create [options] [working-dir]

Options for create:

• --region REGION: Region code for the agent deployment. If no value is provided, the CLI prompts you to select a region.
• --deployment NAME (alias -d): Deployment to create the agent in. Defaults to production.
• --secrets KEY=VALUE [--secrets KEY=VALUE]: One or more KEY=VALUE secrets. Repeat the flag for each secret. Injected as environment variables into the agent. Individual values take precedence over values in --secrets-file, in the case of duplicate keys.
• --secrets-file FILE: File containing secret KEY=VALUE pairs, one per line. Injected as environment variables into the agent.
• --secret-mount FILE: Path to a file to load as a file-mounted secret in the agent container.
• --config FILE: Name of the configuration file to create for the new deployment. If no value is provided, the default name is livekit.toml.
• --silent: Do not prompt for interactive confirmation. Default: false.

Examples

Create and deploy a new agent to us-east from the current directory, providing secrets inline and via file:

lk agent create \
  --region us-east \
  --secrets OPENAI_API_KEY=sk-xxx \
  --secrets GOOGLE_API_KEY=ya29.xxx \
  --secrets-file ./secrets.env \
  .

Deploy

Build and deploy a new agent version based on the working directory. You must have a livekit.toml and Dockerfile in the working directory.

lk agent deploy [options] [working-dir]

Options for deploy:

• --deployment NAME (alias -d): Deployment to deploy to. Defaults to production.
• --secrets KEY=VALUE [--secrets KEY=VALUE]: One or more KEY=VALUE secrets. Repeat the flag for each secret. Injected as environment variables into the agent. Takes precedence over --secrets-file.
• --secrets-file FILE: File containing secret KEY=VALUE pairs, one per line. Injected as environment variables into the agent.
• --secret-mount FILE: Path to a file to load as a file-mounted secret in the agent container.

Examples

Deploy a new version of production from the current directory:

lk agent deploy

Deploy to the staging deployment:

lk agent deploy --deployment staging

Deploy a new version from the subdirectory ./agent:

lk agent deploy ./agent

Promote

Promote the image running in a non-production deployment to production without rebuilding (build once, deploy many). Use this to ship a build you've already validated in a deployment like staging.

lk agent promote --deployment NAME [options] [working-dir]

Options for promote:

• --deployment NAME (alias -d): Non-production deployment whose image is promoted to production. You can't promote the production deployment to itself.
• --id ID: Agent ID. If unset and livekit.toml is present, uses the ID found there.

Examples

Promote the staging image to production:

lk agent promote --deployment staging

Status

Show the current status of the specified agent:

lk agent status [options] [working-dir]

Options for status:

• --id AGENT_ID: Agent ID. By default, uses the ID found in the livekit.toml file in the working directory.

Examples

Show the status of the agent in the current directory:

lk agent status

Show the status of the agent with the ID CA_MyAgentId:

lk agent status --id CA_MyAgentId

Example output. Each deployment of the agent is listed as a separate row, with the Deployment column showing production for the production deployment:

Using default project [my-project]
Using agent [CA_MyAgentId]
┌─────────────────┬─────────────┬────────────────┬─────────┬─────────────┬──────────┬────────────┬─────────┬───────────┬──────────────────────┐
│ ID              │ Name        │ Version        │ Region  │ Deployment  │ Status   │ CPU        │ Mem     │ Replicas  │ Deployed At          │
├─────────────────┼─────────────┼────────────────┼─────────┼─────────────┼──────────┼────────────┼─────────┼───────────┼──────────────────────┤
│ CA_MyAgentId    │ steve-agent │ 20250809003117 │ us-east │ production  │ Running  │ 0m / 2000m │ 0 / 4GB │ 1 / 1 / 1 │ 2025-08-09T00:31:48Z │
│ CA_MyAgentId    │ steve-agent │ 20250809010422 │ us-east │ staging     │ Sleeping │ 0m / 2000m │ 0 / 4GB │ 0 / 0 / 1 │ 2025-08-09T01:04:51Z │
└─────────────────┴─────────────┴────────────────┴─────────┴─────────────┴──────────┴────────────┴─────────┴───────────┴──────────────────────┘

Status values

The status field indicates the current state of the agent.

Normal statuses

These indicate that the agent is running or deploying normally.

Sleep

Agents on certain plans may be scaled down to zero active instances. See cold start for more info.

Errors

These indicate that the agent is in an error state.

Update

Update secrets for an existing agent. This command restarts the agent servers, but does not interrupt any active sessions.

lk agent update [options] [working-dir]

Options for update:

• --secrets KEY=VALUE [--secrets KEY=VALUE]: One or more KEY=VALUE secrets. Repeat the flag for each secret. Injected as environment variables into the agent. Takes precedence over --secrets-file.
• --secrets-file FILE: File containing secret KEY=VALUE pairs, one per line. Injected as environment variables into the agent.
• --secret-mount FILE: Path to a file to load as a file-mounted secret in the agent container.
• --id AGENT_ID: Agent ID. By default, uses the ID found in the livekit.toml file in the working directory.

Examples

Update secrets and restart the agent:

lk agent update \
  --secrets OPENAI_API_KEY=sk-new

Restart

Restart the agent server pool for the specified agent. This command does not interrupt any active sessions.

lk agent restart [options] [working-dir]

Options for restart:

• --id AGENT_ID: Agent ID. By default, uses the ID found in the livekit.toml file in the working directory.

Examples

lk agent restart --id CA_MyAgentId

Rollback

Rollback the specified agent to a prior version:

lk agent rollback [options] [working-dir]

Options for rollback:

• --version string: Version to roll back to. Defaults to the most recent version prior to the current.
• --id ID: Agent ID. If unset and livekit.toml is present, uses the ID found there.

Examples

Roll back to a specific version:

lk agent rollback --id CA_MyAgentId --version 20250809003117

Logs

Stream logs for the specified agent and log type. Also available as tail.

lk agent logs [options] [working-dir]
# or
lk agent tail [options] [working-dir]

Options for logs/tail:

• --deployment NAME (alias -d): Deployment to stream logs from. Defaults to production.
• --id ID: Agent ID. If unset and livekit.toml is present, uses the ID found there.
• --log-type string: Log type to retrieve. Valid values: deploy, build. Default: deploy.

Examples

Tail deploy logs from production:

lk agent logs --id CA_MyAgentId --log-type deploy

Tail deploy logs from the staging deployment:

lk agent logs --deployment staging

Delete

Delete the specified agent. Also available as destroy.

lk agent delete [options] [working-dir]
# or
lk agent destroy [options] [working-dir]

Options for delete/destroy:

• --deployment NAME (alias -d): Deployment to delete. If unset, deletes the entire agent, including production. You can't delete production by name.
• --id ID: Agent ID. If unset and livekit.toml is present, uses the ID found there.

Examples

Delete the entire agent:

lk agent delete --id CA_MyAgentId

Delete only the staging deployment:

lk agent delete --deployment staging

Versions

List versions associated with the specified agent, which can be used to rollback.

lk agent versions [options] [working-dir]

Options for versions:

• --id ID: Agent ID. If unset and livekit.toml is present, uses the ID found there.

Examples

lk agent versions --id CA_MyAgentId

Example output. The Production, Draining, and Active columns show each version's role: Production marks the version currently serving production, Draining marks a version still finishing active sessions after a new deploy, and Active marks a version that's running:

Using default project [my-project]
Using agent [CA_MyAgentId]
┌────────────────┬────────────┬──────────┬────────┬──────────┬──────────────────────┬──────────────────────┐
│ Version        │ Production │ Draining │ Active │ Status   │ Created At           │ Deployed At          │
├────────────────┼────────────┼──────────┼────────┼──────────┼──────────────────────┼──────────────────────┤
│ 20250809010422 │ ✓          │ ---      │ ✓      │ Deployed │ 2025-08-09T01:00:00Z │ 2025-08-09T01:04:51Z │
│ 20250809003117 │ ---        │ ✓        │ ✓      │ Deployed │ 2025-08-09T00:30:00Z │ 2025-08-09T00:31:48Z │
└────────────────┴────────────┴──────────┴────────┴──────────┴──────────────────────┴──────────────────────┘

List

List all deployed agents in the current project:

lk agent list [options]

Options for list:

• --id IDs [--id IDs]: Filter to one or more agent IDs. Repeatable.
• --project PROJECT_NAME: The project name to list agents for. By default, use the project from the current livekit.toml file or the default project.

Examples

lk agent list

Example output. The Deployments column lists each agent's deployments, with production always shown first:

Using default project [my-project]
┌─────────────────┬───────────────┬─────────┬─────────────────────┬────────────────┬──────────────────────┐
│ ID              │ Dispatch Name │ Regions │ Deployments         │ Version        │ Deployed At          │
├─────────────────┼───────────────┼─────────┼─────────────────────┼────────────────┼──────────────────────┤
│ CA_MyAgentId    │ steve-agent   │ us-east │ production,staging   │ 20250809003117 │ 2025-08-09T00:31:48Z │
└─────────────────┴───────────────┴─────────┴─────────────────────┴────────────────┴──────────────────────┘

Secrets

Show the current secret keys for the specified agent. Does not include secret values.

lk agent secrets [options] [working-dir]

Options for secrets:

• --id AGENT_ID: Agent ID. By default, uses the ID found in the livekit.toml file in the working directory.

Examples

lk agent secrets --id CA_MyAgentId

Example output:

Using default project [my-project]
Using agent [CA_MyAgentId]
┌────────────────┬──────────────────────┬──────────────────────┐
│ Name           │ Created At           │ Updated At           │
├────────────────┼──────────────────────┼──────────────────────┤
│ OPENAI_API_KEY │ 2025-08-08T23:32:29Z │ 2025-08-09T00:31:10Z │
│ GOOGLE_API_KEY │ 2025-08-08T23:32:29Z │ 2025-08-09T00:31:10Z │
│ HEDRA_API_KEY  │ 2025-08-08T23:32:29Z │ 2025-08-09T00:31:10Z │
└────────────────┴──────────────────────┴──────────────────────┘

Update secrets

Update secrets for the specified agent. This command restarts the agent:

lk agent update-secrets [options] [working-dir]

Options for update-secrets:

• --secrets KEY=VALUE [--secrets KEY=VALUE]: One or more KEY=VALUE secrets. Repeat the flag for each secret. Injected as environment variables into the agent. Takes precedence over --secrets-file.
• --secrets-file FILE: File containing secret KEY=VALUE pairs, one per line. Injected as environment variables into the agent.
• --secret-mount FILE: Path to a file to load as a file-mounted secret in the agent container.
• --id ID: Agent ID. If unset and livekit.toml is present, uses the ID found there.
• --overwrite: Overwrite existing secrets. Default: false.

Examples

Update secrets without overwriting existing keys:

lk agent update-secrets --id CA_MyAgentId \
  --secrets-file ./secrets.env

Overwrite existing keys explicitly:

lk agent update-secrets --id CA_MyAgentId \
  --secrets OPENAI_API_KEY=sk-xxx \
  --overwrite

Mount a file as a secret:

lk agent update-secrets --id CA_MyAgentId \
  --secret-mount ./google-appplication-credentials.json

Config

Generate a new livekit.toml in the working directory for an existing agent:

lk agent config --id AGENT_ID [options] [working-dir]

Options for config:

• --id AGENT_ID: Agent ID. Uses the provided ID to generate a new livekit.toml file.

Generate Dockerfile

Generate a new Dockerfile and .dockerignore file in the working directory. To overwrite existing files, use the --overwrite flag.

lk agent dockerfile [options] [working-dir]

Options for dockerfile:

• --overwrite: Overwrite existing files. Default: false.

Examples

lk agent dockerfile