# Vocal Bridge CLI

Developer tools for iterating on voice agents built with [Vocal Bridge](https://vocalbridgeai.com).

## Installation

```bash
pip install vocal-bridge
```

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

## Quick Start

```bash
# 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 (paid subscribers). After login, use `vb agent use` to select which agent to work with.

### Login with API Key

```bash
# 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

```bash
vb auth status
```

### Logout

```bash
vb auth logout
```

### Environment Variables

You can also set credentials via environment variables:

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

## Commands

### Agent Info

```bash
# 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
vb agent use <agent_id>
```

### Create Agent (Paid Subscribers)

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

```bash
# 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

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

```bash
# 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

```bash
# Show call statistics
vb stats

# Output as JSON
vb stats --json
```

### Prompt Management

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

```bash
# 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
```

#### Discover Valid Options

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

```bash
# 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

```bash
# 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
```

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

### Debug Streaming

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

```bash
# 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

## Configuration Files

### CLI Configuration

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

```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:

```json
[
  {
    "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

```bash
# 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

```bash
# 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

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