Metadata-Version: 2.4
Name: vocal-bridge
Version: 0.7.1
Summary: CLI tools for Vocal Bridge voice agent development
License: Apache-2.0
Project-URL: Homepage, https://vocalbridgeai.com
Project-URL: Documentation, https://vocalbridgeai.com/docs/developer-guide
Keywords: voice,agent,ai,cli,vocal-bridge
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets>=16.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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

### Login with API Key

You can get an API key from your agent's detail page in the Vocal Bridge dashboard.

```bash
# Interactive login
vb auth login

# Or provide key directly
vb auth login vb_your_api_key_here
```

### 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 agent details
vb agent
```

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

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

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

```json
{
  "stt_model": "nova-3",
  "tts_voice": "alloy",
  "temperature": 0.7
}
```

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