Troubleshooting

vac is not found

Install or refresh the global package:

npm install --global voice-agent-cli
vac --version

To run the current checkout instead:

npm ci
npm run build
npm link
vac --help

If another installed program already owns vac, use the equivalent voice-agent alias.

Authentication fails

Verify the key in the same process that runs the command:

RETELL_API_KEY=your_api_key vac retell agents list --limit 1

The CLI does not automatically load the repository .env. Export it in your shell, use Node’s environment-file support in your own wrapper, or run vac retell login.

Configuration is invalid

The current schema nests Retell below providers. Fix or remove the path reported in the structured error, then run vac retell login to write a valid file. See Configuration.

Prompt directory is missing

Pull the prompts before diffing or updating:

vac retell prompts pull agent_123

The default agent directory is .voice-agent/retell/prompts/agent_123/. Custom --output and --source values are base directories, not JSON files.

A command or flag is rejected

Help is available at every level:

vac retell --help
vac retell calls update-live --help

CLI usage errors are JSON on stderr. The next_steps entry names the closest help command.