CLI Reference

Complete documentation for the botcall CLI. Every command, every flag, every exit code.

Installation

Requires Node.js 18 or later.

npm install -g botcall

Verify the install:

botcall --version
0.1.1

Authentication

Get an API key from the dashboard after subscribing. Keys start with bs_live_.

botcall auth login --api-key bs_live_xxxxx --api-url https://botcall-production-f65b.up.railway.app
✓ API key saved
✓ Connected! You have 0 phone number(s)

Your key is stored in ~/.config/botcall/config.json (macOS/Linux) or %APPDATA%\botcall\config.json (Windows). You only need to log in once per machine.

Alternatively, set an environment variable — this takes precedence over the saved key:

export BOTCALL_API_KEY=bs_live_xxxxx

Quickstart

# 1. Authenticate
botcall auth login --api-key bs_live_xxxxx --api-url https://botcall-production-f65b.up.railway.app

# 2. Get a phone number
botcall provision
✓ Provisioned: +12065551234

# 3. Trigger SMS on the target service, then:
botcall get-code
847291

# 4. Use in a script
CODE=$(botcall get-code)
echo "Got code: $CODE"

botcall auth

Manage authentication. Three sub-actions: login, status, logout.

auth login

botcall auth login --api-key <key> [--api-url <url>]

Saves the key and immediately tests the connection. Exits non-zero if the key is invalid.

auth status

botcall auth status
✓ Authenticated (API mode)
  Key: bs_live_zU5B...
  URL: https://api.botcall.io

Shows the current auth state. Prints the first 12 characters of the key, never the full value.

auth logout

botcall auth logout
✓ Logged out

Clears the saved key from disk. The BOTCALL_API_KEY environment variable is not affected.

botcall provision

botcall provision [--area-code <code>] [--country <code>]

Provisions a new phone number on your account. Numbers are billed monthly — release when done.

On success, prints the phone number in E.164 format to stdout — clean, no extra text. Useful for capturing in scripts.

botcall provision
✓ Provisioned: +12065551234
+12065551234

botcall provision --area-code 415
✓ Provisioned: +14155559876
+14155559876

# Capture in a script
NUMBER=$(botcall provision)
echo "My number: $NUMBER"

• 0Number provisioned successfully
• 1Limit reached for plan, not authenticated, or provisioning error

botcall list

botcall list [--json]
botcall ls [--json]   # alias

Lists all provisioned phone numbers on your account.

botcall list

Your numbers:

  +12065551234 (active) - SMS, Voice

botcall list --json
[
  {
    "id": "abc123",
    "number": "+12065551234",
    "status": "active",
    "capabilities": {
      "sms": true,
      "voice": true,
      "mms": false
    }
  }
]

The id field from --json output is used with botcall release <id>.

botcall inbox

botcall inbox [--limit <n>] [--json]

Shows recent incoming messages for all your numbers.

botcall inbox

Recent messages:

  2026-03-30T14:22:11Z
  ← +15551234567 [CODE: 847291]
  Your verification code is 847291. Do not share it.


botcall inbox --limit 50 --json
[
  {
    "id": "msg_xxx",
    "from": "+15551234567",
    "to": "+12065551234",
    "body": "Your verification code is 847291.",
    "code": "847291",
    "direction": "inbound",
    "receivedAt": "2026-03-30T14:22:11Z"
  }
]

The code field is populated when a numeric verification code is automatically extracted from the message body.

botcall get-code

botcall get-code [--timeout <seconds>]

Waits for an incoming SMS and extracts the verification code. Call this after triggering the verification flow on the target service. Prints only the code to stdout — nothing else — making it ideal for scripts.

# Wait up to 30 seconds (default)
botcall get-code
847291

# Wait up to 20 seconds
botcall get-code --timeout 20
583012

# Capture in a script
CODE=$(botcall get-code)
echo "Code: $CODE"

• 0Code found. Printed to stdout. Nothing else on stdout.
• 1Timeout — no message received within the timeout window. Or: not authenticated, no number provisioned, API error.

botcall release

botcall release <number-id>

Releases a provisioned phone number. Billing stops immediately. The number returns to the pool and cannot be recovered.

Get the number ID from botcall list --json:

# Step 1: find the ID
botcall list --json
[{ "id": "abc123", "number": "+12065551234", ... }]

# Step 2: release it
botcall release abc123
✓ Number released

• 0Number released
• 1Number not found, not owned by your account, or API error

botcall usage

botcall usage

Shows your current plan, limits, and usage for the billing period.

botcall usage

Plan: STARTER

Limits:
  Phone numbers: 1/1
  SMS this month: 3/100

No flags. Human-readable output only.

botcall billing

botcall billing

Opens the Stripe billing portal in your default browser. From there you can update your payment method, view invoices, or cancel your subscription.

No flags.

botcall upgrade

botcall upgrade <plan>

Creates a Stripe checkout session and opens it in your browser to upgrade your plan.

botcall upgrade starter
Opening checkout in browser...

If browser doesn't open, visit:
https://checkout.stripe.com/...

MCP Server

botcall ships a Model Context Protocol server (botcall-mcp) for Claude Desktop and any other MCP-compatible AI tool.

npm install -g botcall-mcp

Add to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "botcall": {
      "command": "npx",
      "args": ["-y", "botcall-mcp"],
      "env": {
        "BOTCALL_API_KEY": "bs_live_xxxxx"
      }
    }
  }
}

Available MCP tools:

Scripting

All commands that output useful data print it to stdout. Spinners and labels go to stderr so they don't pollute captured output.

#!/bin/bash
# Full automation example: provision a number, wait for a code, release the number

export BOTCALL_API_KEY=bs_live_xxxxx

# Provision
NUMBER=$(botcall provision)
echo "Number: $NUMBER"

# ... trigger the verification flow using $NUMBER ...

# Wait for code
CODE=$(botcall get-code --timeout 30)
if [ $? -ne 0 ]; then
  echo "Timed out waiting for code"
  exit 1
fi
echo "Code: $CODE"

# Get the number ID and release it
ID=$(botcall list --json | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['id'])")
botcall release "$ID"

Environment Variables