Skip to main content

​
Overview

lua voice is the entry point for testing voice-enabled agents. You can talk to your agent live in the browser, run automated voice tests against *.voice.test.ts files, and inspect which voice primitives are wired into your agent. 
lua voice                          # Interactive: pick agent → voice → start browser test
lua voice test                     # Run all *.voice.test.ts files
lua voice list                     # List voice primitives in the manifest

​
Subcommands

ActionWhat it does
(default)Interactive live test. Pick an agent, then a voice, then start a browser session.
testRun *.voice.test.ts files via Jest or Vitest.
listList LuaVoice primitives in the compiled manifest.

​
Live Test Options

These apply to the default lua voice invocation.
OptionDescription
--agent <name>Agent name. Skips the agent picker when your project has multiple agents with voices.
--voice <name>Voice name. Skips the voice picker when an agent has multiple voices. Defaults to the primary voice.
--context <json>Seed initial conversation context as a JSON object.
--thread-id <id>Custom thread ID suffix for sandbox API scoping.

​
Live Test Examples

# Interactive — pick agent and voice from menus
lua voice

# Skip the agent picker
lua voice --agent support-bot

# Pick a specific voice (skips voice picker)
lua voice --voice billing-line

# Seed initial context — the agent enters the conversation already knowing things
lua voice --context '{"orderId":"ABC-123","customerName":"Sam"}'

# Scope to a custom thread (for replaying a session later via API)
lua voice --thread-id qa-2026-05-18-run-1

​
lua voice test — Automated Voice Tests

Runs your project’s *.voice.test.ts files via Jest or Vitest. Lua auto-detects which runner you’re using; pass --runner to force one.
OptionDescription
--voice <name>Run only <name>.voice.test.ts (filename match).
--pattern <regex>Test path pattern. Default: \.voice\.test\.. Overrides --voice if both set.
--watchRe-run tests on file change.
--bailStop on first failing test.
--runner <runner>Force runner: jest, vitest, or auto (default).
lua voice test                       # All *.voice.test.ts files
lua voice test --voice support       # Only support.voice.test.ts
lua voice test --pattern support     # Filter by name pattern (regex)
lua voice test --watch               # Watch mode
lua voice test --bail                # Stop on first failure
lua voice test --runner vitest       # Force Vitest

​
lua voice list

Prints the LuaVoice primitives defined in your compiled manifest. Useful for sanity-checking that all your voice agents and voices are wired up after a compile.
OptionDescription
--jsonOutput as JSON for scripting.
lua voice list
lua voice list --json | jq