@bland-ai/cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,516 @@
+# Bland CLI
+
+The command-line interface for [Bland AI](https://bland.ai). Build, test, and deploy conversational AI agents from your terminal.
+
+## Install
+
+```bash
+npm install -g @bland-ai/cli
+```
+
+Or run without installing:
+
+```bash
+npx @bland-ai/cli
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+### 1. Authenticate
+
+```bash
+bland auth login --key YOUR_API_KEY
+```
+
+Or set the environment variable:
+
+```bash
+export BLAND_API_KEY=your_key_here
+```
+
+### 2. Check your account
+
+```bash
+bland auth whoami
+```
+
+### 3. Make a call
+
+```bash
+bland call send +15551234567 --task "Ask if they're interested in a demo" --voice nat --wait
+```
+
+### 4. Build a pathway
+
+```bash
+# Scaffold a new project
+bland pathway init ./my-pathway --name "Customer Support"
+
+# Edit the YAML file in your editor
+# Then push it to Bland
+bland pathway push ./my-pathway
+
+# Test it interactively
+bland pathway chat <pathway_id> --verbose
+```
+
+## Commands
+
+### Authentication
+
+```bash
+bland auth login              # Log in with API key
+bland auth login --key sk-... # Log in non-interactively
+bland auth logout              # Clear credentials
+bland auth whoami              # Show account info and balance
+bland auth switch              # Switch between profiles
+bland auth profiles            # List all saved profiles
+```
+
+The CLI stores profiles in `~/.config/bland-cli/config.json`. You can have multiple profiles for different orgs or environments.
+
+### Calls
+
+```bash
+bland call send <number>       # Make an outbound call
+  --task <prompt>               #   What the AI should do
+  --pathway <id>                #   Use a pathway instead of a task
+  --voice <voice>               #   Voice selection (nat, josh, etc.)
+  --from <number>               #   Caller ID
+  --first-sentence <text>       #   Opening line
+  --model <base|turbo>          #   Model selection
+  --max-duration <mins>         #   Max call length
+  --wait                        #   Wait and stream live transcript
+  --record                      #   Enable recording
+  --transfer <number>           #   Transfer number
+  --request-data <json>         #   Variables to inject
+  --webhook <url>               #   Post-call webhook
+
+bland call list                # List recent calls
+  --limit <n>                   #   Max results (default 20)
+  --status <s>                  #   Filter: completed, active, failed
+  --from <date>                 #   Start date
+  --to <date>                   #   End date
+  --inbound                     #   Only inbound calls
+  --batch <id>                  #   Filter by batch
+
+bland call get <call_id>       # Full call details + transcript
+bland call stop <call_id>      # End an active call
+bland call events <call_id>    # View call events
+bland call recording <call_id> # Get recording URL
+  --download                    #   Save to local file
+bland call analyze <call_id>   # Run post-call analysis
+```
+
+### Pathways
+
+The pathway workflow lets you define conversational flows as YAML files and sync them with the Bland API.
+
+#### YAML Format
+
+```yaml
+name: "Customer Support"
+description: "Handles inbound support calls"
+version: draft
+
+global:
+  voice: nat
+  model: base
+
+nodes:
+  greeting:
+    type: default
+    prompt: |
+      Greet the customer warmly. Ask how you can help them today.
+    edges:
+      - target: identify_issue
+        condition: "Customer describes their problem"
+      - target: transfer_human
+        condition: "Customer asks for a human"
+
+  identify_issue:
+    type: default
+    prompt: |
+      Listen to the customer's issue and categorize it.
+    extract_variables:
+      - name: issue_type
+        type: string
+        description: "billing, technical, or general"
+    edges:
+      - target: billing_help
+        condition: "issue_type is billing"
+      - target: tech_help
+        condition: "issue_type is technical"
+
+  billing_help:
+    type: default
+    prompt: "Help with billing questions."
+    edges:
+      - target: goodbye
+
+  tech_help:
+    type: default
+    prompt: "Help with technical issues."
+    edges:
+      - target: goodbye
+
+  transfer_human:
+    type: transfer
+    number: "+15551234567"
+
+  goodbye:
+    type: end_call
+    prompt: "Thank the customer and end the call."
+```
+
+#### Pathway Commands
+
+```bash
+# Project setup
+bland pathway init [dir]       # Scaffold a new pathway project
+  --name <name>                 #   Pathway name
+
+# Sync with Bland
+bland pathway pull <id> [dir]  # Download pathway as YAML
+bland pathway push [dir]       # Upload YAML to Bland
+  --create                      #   Create new if no ID linked
+bland pathway diff [dir]       # Compare local vs remote
+bland pathway validate [dir]   # Validate YAML locally
+bland pathway watch [dir]      # Auto-push on file changes
+
+# CRUD
+bland pathway list             # List all pathways
+bland pathway get <id>         # Show pathway details
+bland pathway create [name]    # Create a new pathway
+  --from-file <path>            #   Create from YAML file
+bland pathway delete <id>      # Delete a pathway
+bland pathway duplicate <id>   # Duplicate a pathway
+
+# Interactive testing
+bland pathway chat <id>        # Chat with a pathway in your terminal
+  --start-node <name>           #   Start at a specific node
+  --variables <json>            #   Inject variables
+  --verbose                     #   Show node transitions and variables
+
+# Automated testing
+bland pathway test <id>        # Run YAML test cases
+  --file <test.yaml>            #   Test case file
+  --parallel <n>                #   Concurrent test runs
+bland pathway simulate <id>    # Run AI simulation
+  --scenario <text>             #   Scenario description
+  --count <n>                   #   Number of simulations
+
+# Node-level testing
+bland pathway node test <pid> <nid>  # Test a single node
+  --permutations <n>                  #   Number of variations
+
+# Versioning
+bland pathway versions <id>    # List versions
+bland pathway promote <id>     # Promote draft to production
+
+# Code nodes
+bland pathway code test <pid> <nid>  # Test a custom code node
+  --input <json>                      #   Test input data
+
+# AI generation
+bland pathway generate         # Generate pathway from description
+  --description <text>
+
+# Editing
+bland pathway edit <id>        # Edit a node prompt in $EDITOR
+
+# Folders
+bland pathway folder list
+bland pathway folder create <name>
+```
+
+#### Test Cases Format
+
+```yaml
+pathway: "Customer Support"
+tests:
+  - name: billing_inquiry
+    scenario: "Customer calls about a wrong charge on their bill."
+    expected_path: [greeting, identify_issue, billing_help, goodbye]
+    expected_variables:
+      issue_type: "billing"
+
+  - name: transfer_request
+    scenario: "Customer immediately asks to speak to a human."
+    expected_path: [greeting, transfer_human]
+```
+
+### Personas
+
+```bash
+bland persona list             # List all personas
+bland persona get <id>         # Show persona details
+bland persona create           # Create interactively
+bland persona update <id>      # Update persona
+bland persona delete <id>      # Delete persona
+bland persona promote <id>     # Promote draft to production
+bland persona reset-draft <id> # Reset draft to production
+bland persona gaps <id>        # View knowledge gaps
+```
+
+### Phone Numbers
+
+```bash
+bland number list              # List owned numbers
+bland number buy               # Purchase a new number
+  --area-code <code>            #   Preferred area code
+  --country <code>              #   Country code (default: US)
+  --count <n>                   #   Buy multiple
+bland number release <number>  # Release a number
+bland number update <number>   # Update number config
+  --pathway <id>                #   Set inbound pathway
+  --persona <id>                #   Set persona
+  --webhook <url>               #   Set webhook
+  --prompt <text>               #   Set prompt
+  --voice <voice>               #   Set voice
+bland number configure <number>  # Interactive configuration
+```
+
+### Voices
+
+```bash
+bland voice list               # List available voices
+  --language <code>             #   Filter by language
+  --custom                      #   Show only custom voices
+bland voice speak <text>       # Generate TTS audio
+  --voice <voice>               #   Voice to use (default: nat)
+  -o, --output <file>           #   Save to file
+```
+
+### Tools
+
+```bash
+bland tool list                # List all tools
+bland tool get <id>            # Show tool details
+bland tool create              # Create interactively
+bland tool update <id>         # Update tool
+bland tool delete <id>         # Delete tool
+bland tool test <id>           # Test with sample input
+  --input <json>                #   Test input data
+  --verbose                     #   Show full request/response
+bland tool types               # List tool types
+```
+
+### Knowledge Bases
+
+```bash
+bland knowledge list           # List knowledge bases (alias: bland kb list)
+bland knowledge create <name>  # Create knowledge base
+bland knowledge scrape <name>  # Scrape URLs into KB
+  --urls <url1,url2>            #   Comma-separated URLs
+  --file <urls.txt>             #   File with URLs (one per line)
+bland knowledge delete <id>    # Delete knowledge base
+bland knowledge status <id>    # Check processing status
+```
+
+### Batch Campaigns
+
+```bash
+bland batch create             # Create batch campaign
+  --file <contacts.csv>         #   Contacts CSV file
+  --pathway <id>                #   Pathway to use
+  --from <number>               #   From number
+bland batch list               # List batches
+bland batch get <id>           # Batch details + stats
+bland batch stop <id>          # Stop a running batch
+```
+
+### SMS
+
+```bash
+bland sms send <number>        # Send SMS
+  --from <number>               #   From number
+  --message <text>              #   Message text
+  --pathway <id>                #   Use pathway for conversation
+bland sms conversations        # List SMS conversations
+bland sms get <id>             # Get conversation thread
+```
+
+### Other Commands
+
+```bash
+# Web agents
+bland agent list | get | create | update | delete
+
+# Guard rails
+bland guard list | create | delete
+
+# Monitoring
+bland alarm list | create | delete
+
+# Secrets
+bland secret list | set | delete
+
+# Releases
+bland release list | create | promote
+
+# Widgets
+bland widget list | create | delete
+
+# Evaluations
+bland eval run | list | get
+
+# Audio
+bland audio generate <text> --voice <voice> -o <file>
+bland audio analyze <file>
+
+# SIP
+bland sip discover <host>
+
+# Local development
+bland listen                   # Forward webhooks to localhost
+  --forward-to <url>           #   Your local server URL
+  --port <n>                   #   Listen port (default: 4242)
+  --events <types>             #   Filter event types
+```
+
+## Profiles
+
+The CLI supports multiple profiles for managing different API keys or organizations.
+
+```bash
+# Add a second profile
+bland auth login --key sk-staging-xxx
+
+# Switch between profiles
+bland auth switch
+
+# List profiles
+bland auth profiles
+```
+
+Profiles are stored at `~/.config/bland-cli/config.json`. You can also override the API key per-command with `BLAND_API_KEY`:
+
+```bash
+BLAND_API_KEY=sk-staging-xxx bland pathway list
+```
+
+## Pathway Workflow
+
+The typical development cycle for pathways:
+
+```
+1. bland pathway init ./my-bot       # Scaffold project
+2. Edit bland-pathway.yaml            # Write your flow
+3. bland pathway validate             # Check for errors
+4. bland pathway push --create        # Upload to Bland
+5. bland pathway chat <id> --verbose  # Test interactively
+6. bland pathway test <id>            # Run automated tests
+7. bland pathway promote <id>         # Ship to production
+8. bland pathway watch                # Auto-push on save
+```
+
+## MCP Server
+
+The CLI includes an MCP (Model Context Protocol) server that lets AI coding tools like Claude Code and Cursor interact with your Bland account.
+
+```bash
+# Start the MCP server
+bland mcp
+
+# Or with SSE transport
+bland mcp --transport sse --port 3100
+```
+
+### Claude Code Setup
+
+Add to your Claude Code config:
+
+```json
+{
+  "mcpServers": {
+    "bland": {
+      "command": "npx",
+      "args": ["@bland-ai/cli", "mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | What it does |
+|------|-------------|
+| `bland_call_send` | Make a phone call |
+| `bland_call_list` | List recent calls |
+| `bland_call_get` | Get call details and transcript |
+| `bland_pathway_list` | List pathways |
+| `bland_pathway_get` | Get pathway details |
+| `bland_pathway_create` | Create a pathway from nodes/edges |
+| `bland_pathway_chat` | Chat with a pathway |
+| `bland_pathway_node_test` | Test a single node |
+| `bland_persona_list` | List personas |
+| `bland_persona_get` | Get persona details |
+| `bland_number_list` | List phone numbers |
+| `bland_number_buy` | Buy a phone number |
+| `bland_voice_list` | List available voices |
+| `bland_tool_test` | Test a custom tool |
+| `bland_knowledge_list` | List knowledge bases |
+| `bland_audio_generate` | Generate TTS audio |
+
+## Local Webhook Development
+
+Forward Bland webhooks to your local dev server without ngrok:
+
+```bash
+# Terminal 1: your app
+node server.js
+
+# Terminal 2: bland webhook forwarder
+bland listen --forward-to http://localhost:3000/webhook
+```
+
+The CLI creates a webhook endpoint and forwards incoming events to your local URL, logging each event with timestamps and response codes.
+
+## JSON Output
+
+Every list and get command supports `--json` for piping to `jq` or scripts:
+
+```bash
+# Get all pathway IDs
+bland pathway list --json | jq '.[].id'
+
+# Get a call transcript as JSON
+bland call get <id> --json | jq '.transcripts'
+
+# Count active numbers
+bland number list --json | jq 'length'
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `BLAND_API_KEY` | API key (overrides stored profile) |
+| `BLAND_BASE_URL` | API base URL (default: `https://api.bland.ai`) |
+
+## Project Files
+
+When you run `bland pathway init`, it creates:
+
+```
+my-pathway/
+  bland-pathway.yaml   # Pathway definition
+  tests/
+    test-cases.yaml    # Test cases
+  .blandrc             # Project config (pathway ID, file paths)
+```
+
+The `.blandrc` file links your local project to a remote pathway:
+
+```yaml
+pathway_id: pw_abc123
+pathway_file: bland-pathway.yaml
+test_file: tests/test-cases.yaml
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bland-ai/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The official Bland AI command-line interface",
   "type": "module",
   "main": "dist/index.js",