> ## 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.

# Voice Command

> Try LuaVoice agents live in the browser and run voice test suites

## 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.

```bash theme={null}
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

```bash theme={null}
# 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).                            |

```bash theme={null}
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. |

```bash theme={null}
lua voice list
lua voice list --json | jq
```

## Related

* [Persona Command](/cli/persona-command) — channel-aware personas including `voice` branch
* [LuaAgent API](/api/luaagent)
* [Voice API](/api/voice) — define voices in code with `LuaVoice`