Documentation Index
Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
| Action | What it does |
|---|
| (default) | Interactive live test. Pick an agent, then a voice, then start a browser session. |
test | Run *.voice.test.ts files via Jest or Vitest. |
list | List LuaVoice primitives in the compiled manifest. |
Live Test Options
These apply to the default lua voice invocation.
| Option | Description |
|---|
--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.
| Option | Description |
|---|
--voice <name> | Run only <name>.voice.test.ts (filename match). |
--pattern <regex> | Test path pattern. Default: \.voice\.test\.. Overrides --voice if both set. |
--watch | Re-run tests on file change. |
--bail | Stop 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.
| Option | Description |
|---|
--json | Output as JSON for scripting. |
lua voice list
lua voice list --json | jq
