# Vocal Bridge CLI

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

## Installation

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

No external dependencies - uses Python stdlib only. Requires Python 3.9+.

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

# List more logs
vb logs -n 50

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

# Paginate
vb logs --offset 20 -n 20

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

# Output as JSON
vb logs --json
vb logs <session_id> --json
```

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

## Configuration

Configuration is 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.

## 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 <session_id>  # detailed view with transcript

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

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