vocal-bridge 0.21.0

CLI tools for Vocal Bridge voice agent development

Vocal Bridge CLI

Developer tools for iterating on voice agents built with Vocal Bridge.

Installation

pip install vocal-bridge

Requires Python 3.9+. Includes WebSocket support for real-time debug streaming.

Quick Start

# Authenticate with your API key (get this from the Vocal Bridge dashboard)
vb auth login

# View your agent info
vb agent

# View recent call logs
vb logs

# View call statistics
vb stats

# Update your agent's prompt
vb prompt edit

Authentication

API Key Types

Vocal Bridge supports two types of API keys:

• Agent API keys: Tied to a specific agent. Get one from your agent's detail page.
• Account API keys: Work across all your agents. Create one from the dashboard's "API Keys" tab. After login, use vb agent use to select which agent to work with. When calling the API directly with an account key, include the X-Agent-Id header with the agent UUID.

Login with API Key

# Interactive login
vb auth login

# Or provide key directly
vb auth login vb_your_api_key_here

# For account keys, select an agent after login
vb agent use

Check Status

vb auth status

Logout

vb auth logout

Environment Variables

You can also set credentials via environment variables:

export VOCAL_BRIDGE_API_KEY=vb_your_api_key_here
export VOCAL_BRIDGE_API_URL=https://vocalbridgeai.com  # optional

Commands

Agent Info

# Show current agent details
vb agent

# List all agents
vb agent list

# Select an agent to work with (interactive)
vb agent use

# Select by agent ID or name
vb agent use <agent_id>
vb agent use "Whiskers the Math Cat"

Create Agent (Paid Subscribers)

Create and deploy a new voice agent programmatically. Requires an active paid subscription. Maximum 50 agents per account.

# Create a simple chatty agent
vb agent create --name "My Assistant" --style Chatty --prompt "You are a helpful assistant."

# Create with a greeting
vb agent create --name "Sales Bot" --style Focused \
  --prompt "You help customers find products." \
  --greeting "Hi! How can I help you today?"

# Create web-only agent (no phone number)
vb agent create --name "Web Agent" --style Chatty \
  --prompt "You are a support agent." --deploy-targets web

# Create from a prompt file
vb agent create --name "Custom Agent" --style Focused --prompt-file prompt.txt

# Create with model settings
vb agent create --name "Custom Voice" --style Focused \
  --prompt "You are helpful." --model-settings-file settings.json

# Create with MCP server integrations
vb agent create --name "Connected Agent" --style Chatty \
  --prompt "You help with scheduling." --mcp-servers-file servers.json

# Create a Listener agent (passive observer, never speaks — streams transcripts
# and coaching suggestions to your app via the data channel)
vb agent create --name "IR Coach" --style Listener \
  --prompt "You coach during earnings Q&A. Trigger on analyst questions. Respond with a bold recommended answer, 2-3 supporting bullets, and one italic caveat." \
  --coachee-description "the company CFO during earnings Q&A" \
  --coaching-debounce 8

# Output as JSON
vb agent create --name "Test" --style Chatty --prompt "Hello." --json

Required flags:

• --name — Agent name
• --style (or --mode) — Agent style: Chatty, Focused, Gemini, Ultravox, or Listener
• --prompt or --prompt-file — System prompt (text or file path)

Optional flags:

• --greeting — Greeting message
• --deploy-targets — phone, web, or both (default: both)
• --background-enabled — Enable background AI: true/false (default: true)
• --web-search-enabled — Enable web search: true/false (default: true)
• --hold-enabled — Enable hold: true/false (default: false)
• --hangup-enabled — Enable hangup: true/false (default: false)
• --debug-mode — Enable debug mode: true/false (default: false)
• --model-settings-file — JSON file with model settings
• --mcp-servers-file — JSON file with MCP servers array
• --client-actions-file — JSON file with client actions array
• --api-tools-file — JSON file with custom HTTP API tools array
• --ai-agent-file — JSON file with AI Agent integration config
• --json — Output result as JSON

Delete Agent

Permanently delete an agent and release its phone number. Requires typing the agent name to confirm.

# Delete the currently selected agent (interactive confirmation)
vb agent delete

# Delete a specific agent by ID
vb agent delete <agent_id>

# Skip confirmation prompt (use with caution)
vb agent delete --force

# Output as JSON
vb agent delete --json

The delete command will:

1. Show agent details and ask you to type the agent name to confirm
2. Delete the dispatch rule and release the phone number
3. Remove the agent record from the database

If the deleted agent was your currently selected agent, the selection is cleared automatically.

Call Logs

# List recent call logs (default: 20)
vb logs
vb logs list

# List more logs
vb logs list -n 50

# Filter by status
vb logs list --status completed
vb logs list --status failed

# Paginate
vb logs list --offset 20 -n 20

# View details of a specific call
vb logs show <session_id>
vb logs <session_id>  # legacy shorthand

# Output as JSON
vb logs list --json
vb logs show <session_id> --json

For agents with post-call processing configured, vb logs show includes a Post-processing line indicating whether the post-call analysis/action run succeeded, timed out (10-minute limit), or failed — with a short reason. Same fields are available in --json output as post_processing_status and post_processing_message.

Download Recordings

Download call recordings to your local machine.

# Download recording to current directory
vb logs download <session_id>

# Download with custom filename
vb logs download <session_id> -o call.ogg

Note: Recordings are only available if the agent has call recording enabled.

Statistics

# Show call statistics
vb stats

# Output as JSON
vb stats --json

Prompt Management

# Show current prompt and greeting
vb prompt show

# Edit prompt in your default editor ($EDITOR)
vb prompt edit

# Edit greeting instead
vb prompt edit --greeting

# Set prompt from file
vb prompt set --file prompt.txt

# Set prompt from stdin
echo "You are a helpful assistant." | vb prompt set

# Set greeting from file
vb prompt set --file greeting.txt --greeting

Agent Configuration

Manage all agent settings including style, capabilities, and integrations.

# Show all agent settings
vb config show

# Show settings as JSON
vb config show --json

# Edit full config in your default editor ($EDITOR)
vb config edit

Export Config Sections

Export a specific config section as JSON. Output is pipe-friendly for roundtripping:

# Export current settings as JSON
vb config get model-settings
vb config get client-actions
vb config get mcp-servers
vb config get api-tools
vb config get ai-agent
vb config get builtin-tools

# Save to file, edit, then re-apply
vb config get model-settings > settings.json
# edit settings.json...
vb config set --model-settings-file settings.json

Discover Valid Options

Before updating settings, use vb config options to discover valid values:

# Show all available options for current agent style
vb config options

# Show options for a specific setting (by name or label)
vb config options voice
vb config options "TTS Model"
vb config options language

# Show all settings in a category
vb config options stt
vb config options audio
vb config options realtime

# Output as JSON
vb config options --json

Update Individual Settings

# Change agent style (Chatty, Focused, Gemini, Ultravox, Listener)
vb config set --style Focused

# Enable/disable capabilities
vb config set --debug-mode true
vb config set --hold-enabled true
vb config set --hangup-enabled true
vb config set --background-enabled false

# Update name or greeting
vb config set --name "My Agent"
vb config set --greeting "Hello! How can I help you today?"

# Set session limits
vb config set --max-call-duration 15
vb config set --max-history-messages 50

# Continuous speech ("keep talking" mode) — agent continues on its own after a
# short silence instead of waiting for the user each turn (tutors, narrators,
# guided experiences). The user can still interrupt at any time by speaking.
vb config set --continuous-mode true
vb config set --continuous-mode true --continuous-mode-delay 3   # wait 3s before continuing
vb config set --continuous-mode false  # back to normal turn-based behavior

# Set MCP servers from file
vb config set --mcp-servers-file servers.json

# Set model settings from file
vb config set --model-settings-file model.json

# AI Agent integration
vb config set --ai-agent-enabled true --ai-agent-description "Customer support agent"
vb config set --ai-agent-file ai_agent.json
vb config set --ai-agent-enabled false  # Disable

Partial Updates with --merge

Use --merge to deep-merge file contents with current settings instead of replacing them. Only the fields you specify are changed:

# Update only the model, keeping all other settings intact
echo '{"realtime": {"model": "gpt-realtime-1.5"}}' > update.json
vb config set --model-settings-file update.json --merge

# Full roundtrip workflow
vb config get model-settings > settings.json
# edit settings.json to change only what you need...
vb config set --model-settings-file settings.json

--merge works with dict-based configs: --model-settings-file, --builtin-tools-file, --ai-agent-file. Array-based configs (--mcp-servers-file, --client-actions-file, --api-tools-file) are always replaced.

Available Styles

Style	Description
Chatty	Best for snappy, low-latency conversations. Ideal when most context fits in the system prompt.
Focused	Best for information-heavy conversations like interviews or surveys. More thorough responses.
Gemini	Powered by Google Gemini Live API. Great for natural, flowing conversations.
Ultravox	Powered by Ultravox Realtime API. Optimized for voice-first interactions.
Listener	Passive observer that never speaks. Joins the room, transcribes multi-speaker audio with diarization, and streams coaching suggestions to your app via the data channel. Use for live coaching during multi-party calls (investor relations, sales, interviews). Web-only — no phone number provisioned. See vb docs after creation for the action schema, and the Listener Mode Settings section below for tunable behavior.

Listener Mode Settings

Listener-mode agents (--style Listener) accept additional settings that control coaching behavior. All settings are optional with sensible defaults; specify any subset.

Flag	Range / values	Default	What it does
--coachee-description TEXT	up to 500 chars	empty	Names the person you're coaching. When set, the agent only generates a coaching card when someone else is speaking (so it doesn't try to coach this person on their own words), and tailors each card as guidance for them. Example: "the CFO during earnings Q&A".
--coaching-debounce SECS	0–60	12	Minimum seconds between coaching cards. Higher = fewer, more spaced-out suggestions; lower = more frequent. Set to 0 for back-to-back cards.
--coaching-context-turns N	0–50	10	How many recent turns of conversation the agent considers per coaching card. Higher = better-grounded; lower = faster and cheaper.
--coaching-job-timeout SECS	5–120	30	Maximum seconds to wait for each coaching card before giving up. Lower for snappier feedback; higher if your prompt relies on external data lookups.
--coaching-gate true|false	—	true	When true, coaching only appears when the conversation matches the trigger conditions in your prompt. When false, every spoken turn produces a coaching card.
--speaker-map true|false	—	true	When true, the agent identifies who's speaking (names, roles) as the conversation unfolds and sends speaker_map_update events. When false, your app only sees raw labels like S0, S1.
--speaker-map-interval SECS	5–300	20	How often the agent re-checks for new speaker identities. Lower = identities resolve faster.

Examples:

# Set the coaching recipient and slow the cadence to one card every 20s
vb config set --coachee-description "the candidate being interviewed" \
              --coaching-debounce 20

# Turn off gating — get a coaching card for every spoken turn
vb config set --coaching-gate false

# Skip speaker identity inference entirely (you'll see only raw S0/S1 labels)
vb config set --speaker-map false

# Inspect or export current values
vb config options                 # lists all settings for the current agent
vb config get model-settings      # JSON dump of current settings

Each flag is also available on vb agent create for one-shot setup at deploy time.

Outbound Calling (Pilot Subscribers)

Place outbound phone calls through your agent. Requires an active Pilot subscription and outbound calling enabled on the agent.

Enable Outbound Calling

Enabling outbound calling requires accepting the Outbound Calling Terms of Use:

# Enable outbound with ToS acceptance
vb config set --outbound-enabled true --accept-outbound-tos

# Set an outbound greeting (spoken when callee answers)
vb config set --outbound-greeting "Hi, this is a call from Acme Corp."

Outbound Calling Terms of Use:

• Compliance: You are solely responsible for complying with all applicable laws, including the Telephone Consumer Protection Act (TCPA), the Telemarketing Sales Rule (TSR), and all state and local telemarketing regulations.
• Consent: You certify that you have obtained prior express consent from all individuals your agent will call, as required by applicable law.
• Prohibited Uses: You will not use outbound calling for unsolicited telemarketing, spam, robocalling, fraud, harassment, calls to emergency services, or any illegal or illicit purpose.
• Indemnification: Vocal Bridge bears no liability for claims, fines, or damages arising from your use of outbound calling. You agree to indemnify and hold Vocal Bridge harmless from any such claims.
• Termination: Vocal Bridge may monitor outbound calling activity and suspend or terminate access at any time for violations, without notice.

Place a Call

# Place an outbound call
vb call [phone]

# With callee name
vb call [phone] --name "John Smith"

# Output as JSON
vb call [phone] --json

Phone numbers must be in E.164 format (e.g., [phone]). Rate limits: 50 calls/day per agent, 200 calls/day per user.

Debug Streaming

Stream real-time debug events from your agent during calls. First enable debug mode in your agent settings.

# Stream debug events via WebSocket (real-time)
vb debug

# Use HTTP polling instead (fallback)
vb debug --poll

# Adjust polling interval (only with --poll)
vb debug --poll -i 1.0

Debug events include:

• User transcriptions (what the caller says)
• Agent responses (what your agent says)
• Tool calls and results
• Background query results
• Session start/end events
• Errors

Evaluate a Call (Pilot Subscribers)

Run a multimodal evaluation of a recorded call session. The full audio recording, the agent's full configuration (system prompt, greeting, capabilities, configured client actions), the structured transcript (with the agent's tool calls), the client action events log, and the raw session report are all sent to a multimodal LLM for a qualitative QA score and concrete prompt-improvement suggestions.

# Basic eval against the agent's own configuration
vb eval <session_id>

# With an explicit objective (what the agent should accomplish)
vb eval <session_id> --objective "Schedule an interview for next Tuesday"

# With both an objective and an expected scenario
vb eval <session_id> \
  --objective "Confirm the candidate's availability" \
  --scenario "User is busy and tries to reschedule twice"

# Long objective/scenario from files
vb eval <session_id> --objective-file objective.txt --scenario-file scenario.txt

# Raw JSON output (pipe-friendly)
vb eval <session_id> --json

The session must already have a recording (check with vb logs <session_id>).

Sample output:

Call Evaluation
----------------------------------------
  Session:      550e8400...
  Score:        7/10
  Verdict:      partial

Summary:
  The agent answered the user's questions accurately but missed
  the scheduling objective when the user asked to reschedule.

What worked:
  + Greeted the caller naturally per the configured greeting
  + Recovered cleanly from a mid-sentence interruption

What didn't:
  - Did not call schedule_meeting tool when the user gave a date
  - Tone became impatient on the second reschedule attempt

Suggested prompt improvements:
  Add an explicit instruction to call schedule_meeting whenever
  the user proposes any time, including reschedules.

Restrictions:

• Pilot subscription required — 403 otherwise
• 100 evals/day per user across all your agents — 429 when exceeded
• 18 MB inline audio cap per recording — extremely long calls will be rejected
• API keys, MCP server URLs, and other secrets in your agent's configuration are not sent to the evaluator

The specific evaluator model is fixed by the platform.

Developer Docs

Get integration documentation for building apps with your voice agent:

# Print integration docs (markdown)
vb docs

# Output as JSON
vb docs --json

Returns comprehensive documentation including:

• Agent configuration and capabilities
• MCP server, client actions, API tools, AI Agent integration
• API integration guide with token generation
• Implementation examples (JavaScript, React, Flutter)
• CLI and Claude Code plugin reference

Works with or without an agent selected. With an agent, docs include agent-specific configuration and tools.

Configuration Files

CLI Configuration

CLI settings are stored in ~/.vocal-bridge/config.json:

{
  "api_key": "vb_...",
  "api_url": "https://vocalbridgeai.com"
}

The config file has restricted permissions (600) to protect your API key.

MCP Servers File

When using --mcp-servers-file, provide a JSON array:

[
  {
    "url": "https://actions.zapier.com/mcp/...",
    "name": "Zapier",
    "tools": []
  }
]

Model Settings File

When using --model-settings-file, provide a JSON object organized by category.

For Focused style:

{
  "stt": {
    "model": "assemblyai:universal-streaming",
    "language": "en",
    "eot_threshold": 0.5
  },
  "tts": {
    "model": "eleven_multilingual_v2",
    "voice_id": "cgSgspJ2msm6clMCkdW9"
  },
  "session": {
    "max_call_duration_minutes": 30,
    "max_history_messages": 100
  }
}

Language options:

• Preset: en, multi (auto-detect), es, fr, de, pt, it, nl, ja, ko, zh, hi, ru, ar, pl, tr, vi, th, id, sv, da, fi, no, uk, cs, el, he, ro, hu, ms, bg, sk, hr, ca, ta
• Custom: Use language_source: "custom" with custom_language: "<BCP-47 code>" (e.g., en-US, pt-BR, zh-TW)

For custom language code:

{
  "stt": {
    "model": "deepgram:nova-3",
    "language_source": "custom",
    "custom_language": "pt-BR",
    "eot_threshold": 0.5
  }
}

AI Agent Config File

When using --ai-agent-file, provide a JSON object:

{
  "enabled": true,
  "description": "Customer support agent for Acme Corp",
  "verbatim": false
}

Fields:

• enabled (boolean): Whether AI Agent integration is active
• description (string): What the developer's agent does (max 2000 chars). Helps the voice agent know when to delegate questions.
• verbatim (boolean): If true, voice agent speaks responses exactly as received; if false (default), adapts for natural voice delivery

Examples

Development Workflow

# 1. Check current agent setup
vb agent
vb prompt show

# 2. Make some test calls to your agent
# ...

# 3. Review the call logs
vb logs
vb logs show <session_id>  # detailed view with transcript

# 4. Download a recording for deeper analysis
vb logs download <session_id>

# 5. Update the prompt based on what you learned
vb prompt edit

# 6. Check statistics
vb stats

CI/CD Integration

# Set API key via environment variable
export VOCAL_BRIDGE_API_KEY=$VOCAL_BRIDGE_API_KEY

# Update prompt from a file in your repo
vb prompt set --file prompts/production.txt

# Verify the update
vb prompt show

Analyzing Call Logs

# Get all failed calls
vb logs --status failed --json | jq '.sessions[]'

# Get transcript of a specific call
vb logs <session_id> --json | jq '.transcript_text'

Troubleshooting

"No API key found"

Run vb auth login or set the VOCAL_BRIDGE_API_KEY environment variable.

"Invalid API key"

• Check that your API key starts with vb_
• Verify the key hasn't been revoked in the dashboard
• Generate a new key if needed

"Agent not found"

The API key may have been created for an agent that was deleted. Create a new key from an active agent.

Connection errors

Check your network connection and that the API URL is correct.