vocal-bridge 0.15.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

# 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, or Ultravox
• --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

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

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)
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

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

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

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.