lua voice

lua voice starts a live voice session with one of the agent’s voices, lua voice test runs the project’s *.voice.test.ts files, and lua voice list prints the voices in the compiled output. Nothing here changes production; voice sessions use the sandbox. Verified against lua-cli 3.33.0.

Synopsis

lua voice [--agent <name>] [--voice <name>] [--terminal | --phone <E.164>] [--caller-id <E.164>] [--context <json>] [--thread-id <id>]
lua voice test [--voice <name>] [--pattern <regex>] [--watch] [--bail] [--runner jest|vitest|auto]
lua voice list [--json]

Description

lua voice picks an agent and a voice from the compiled manifest in dist-v2/, then a mode. --agent and --voice skip the pickers; --voice defaults to the primary voice, the first bound to the agent. The mode is browser (a local page with microphone and speaker), terminal (--terminal, requires sox), or phone (--phone; the agent calls the number and the command exits once the call is dispatched). --phone and --terminal together are an error; both numbers must be E.164 (+ and 6 to 15 digits). --context seeds the voice session with a JSON object; --thread-id sets the thread suffix its sandbox API calls are scoped to. Without --terminal or --phone the command asks How would you like to test?. Under --ci that prompt, like the pickers, is refused and the command exits 1 with ✖ error: Interactive prompt required but --ci flag is set. Provide all required flags or arguments. lua voice test finds *.voice.test.ts files under the current directory (outside node_modules and build output) and runs them with npx jest or npx vitest with LUA_VOICE_TEST=1 set. --runner auto picks Vitest if package.json depends on it, else Jest; with neither installed the command exits 1 with ✖ error: No supported test runner found.. --voice <name> runs only <name>.voice.test.ts; --pattern overrides it. A failing run exits 1. lua voice list reads dist-v2/manifest.json; run lua compile first. It prints each voice’s models, hooks, greeting, and owning agent, marking the primary voice ★. lua voice needs a project directory and a credential; list needs only the compiled output; test needs neither.

Arguments

Argument	Values	Description
subcommand	`test`, `list`	Omit it to start a live voice session.

Options

Option	Description	Default
`--agent <name>`	Agent whose voice to use.	prompt if several
`--voice <name>`	Voice to use, or the test file to run for `test`.	primary voice; all files
`--terminal`	Use the terminal microphone and speaker; requires `sox`.	off
`--phone <number>`	Call this E.164 number.	—
`--caller-id <number>`	E.164 number to present; must be owned by the organization.	—
`--context <json>`	JSON object seeded into the voice session.	—
`--thread-id <id>`	Thread suffix for the voice session’s sandbox API scope.	—
`--pattern <regex>`	Test path pattern for `test`; overrides `--voice`.	`\.voice\.test\.`
`--watch`	Re-run `test` on file change.	off
`--bail`	Stop `test` on the first failure.	off
`--runner <runner>`	`jest`, `vitest`, or `auto`.	`auto`
`--json`	Machine-readable output for `list`.	off
`--ci`	Global flag. Refuse any prompt with exit `1` instead of waiting for input.	off

Examples

List the voices in the compiled output.

lua voice list

Output

🎙️  1 voice:

★ field-line  (field-ops-voice (primary))
    llm: inference:openai/gpt-5.2-chat-latest
    stt: inference:deepgram/nova-3
    tts: inference:elevenlabs/eleven_v3
    hooks: —
    greeting: "Field ops line, how can I help?"

Get the same list as JSON for a script.

lua voice list --json

Output

[
  {
    "name": "field-line",
    "llm": "inference:openai/gpt-5.2-chat-latest",
    "stt": "inference:deepgram/nova-3",
    "tts": "inference:elevenlabs/eleven_v3",
    "greeting": "Field ops line, how can I help?",
    "hasOnEnter": false,
    "hasOnUserTurnCompleted": false,
    "hasOnExit": false,
    "hasTools": false,
    "agent": "field-ops-voice",
    "primary": true
  }
]

Have the agent call you, presenting a number the organization owns.

lua voice --voice field-line --phone +15551234567 --caller-id +15557654321 --ci

Run one voice test file with Vitest and stop at the first failure.

lua voice test --voice field-line --runner vitest --bail

Exit codes

Code	Meaning	When
`0`	OK	The voice session was dispatched, the tests passed, or the list printed.
`1`	Error	Unknown agent or voice, bad phone number or `--context`, no test runner, failing tests, no manifest, or a prompt refused under `--ci`.
`2`	Usage	Unknown subcommand or option.
`9`	Auth	No valid credential for a live voice session.
`11`	Unavailable	Network error or a server 5xx while dispatching.

The full table is in Errors and exit codes.

SDK

CLI

REST API

Synopsis

Description

Arguments

Options

Examples

Exit codes

See also

​Synopsis

​Description

​Arguments

​Options

​Examples

​Exit codes

​See also

Synopsis

Description

Arguments

Options

Examples

Exit codes

See also