CLI - CallingBox

The CallingBox CLI ships with the Python SDK as an optional extra. It talks to the same public /v1 API, so anything you can do with the SDK you can do from your terminal, including placing calls, listing numbers, inspecting history, and more.

Install

The CLI is packaged with the Python SDK, but its dependencies (typer, rich) are kept behind an [cli] extra so SDK-only users stay lean:

pip install 'callingbox[cli]'

Verify the install:

callingbox --version
callingbox --help

If you only ran pip install callingbox, the callingbox command will print an install hint rather than crashing with an import error.

Authenticate

The CLI resolves your API key in this order (highest wins):

--api-key flag on the command
CALLINGBOX_API_KEY environment variable
Config file written by callingbox login

Run callingbox login once and paste your key when prompted. The CLI validates the key against GET /v1/numbers before saving it:

callingbox login
# API key: ****************
# ✓ Saved credentials to /Users/you/.config/callingbox/config.toml

The config file is written with mode 0600 on Unix so other users on the machine cannot read it. For CI or scripted setups, pass the key directly:

callingbox login --api-key sk_live_...

Environment variable

Skip the config file entirely by exporting the key in your shell:

export CALLINGBOX_API_KEY=sk_live_...

Check the active credentials

callingbox whoami
# source:   env
# api key:  sk_liv…5678
# base url: https://api.callingbox.io

whoami does not hit the API. It only tells you how the CLI would resolve your credentials right now.

Log out

callingbox logout

Removes the config file if it exists. Environment variables and flags are not affected.

Custom API base URL

The CLI defaults to the production API. If your organization uses a private CallingBox deployment, set CALLINGBOX_BASE_URL, or pass --base-url per invocation, or persist with callingbox login --base-url https://your-deployment.example.

Place a call

The flagship command dispatches a call from an existing outbound agent, polls until it reaches a terminal status, and prints the structured returns data:

callingbox call \
  --agent AGENT_ID \
  --to "+15551234567"

Flags:

Flag	Required	Description
`--agent`	yes	Outbound agent id.
`--to`	yes	Destination number in E.164 format.
`--context`	no	JSON object passed to the agent as context.
`--instructions`	no	Per-call instructions. Wholly replaces the agent’s default for this call.
`--from`	no	Caller ID override. Must already be attached to the agent. Defaults to the agent’s primary number.
`--webhook-url`	no	Per-call webhook override. Defaults to the agent’s `webhook_url`.
`--transcript`	no	Also fetch and print the call transcript when the call completes. Ignored with `--no-wait`.
`--no-wait`	no	Return immediately after dispatch.
`--timeout`	no	Max seconds to wait. Default `600`.

Persona, voice, language, returns, tools, and voicemail behavior all live on the agent. Create or edit an agent to change them. They are not accepted as flags on callingbox call.

Fire-and-forget

If you don’t want to wait for the call to complete:

callingbox call --agent AGENT_ID --to "+15551234567" --no-wait

The CLI prints the call record (including the id) and exits. Poll later with callingbox calls get <id>.

Timeouts

If the call doesn’t reach a terminal status before --timeout expires, the CLI exits with code 6 and prints the call id so you can keep polling manually.

List and retrieve calls

Calls are cursor-paginated (Stripe/OpenAI-style) with stable ordering by creation time.

callingbox calls list                         # first page (default 20)
callingbox calls list --limit 50
callingbox calls list --after call_abc...     # next page
callingbox calls list --all                   # auto-paginate every page
callingbox calls get call_abc...              # single record
callingbox calls transcript call_abc...       # role/text panel of the transcript

Add --json to calls transcript (or pipe it) to emit { "call_id": "...", "segments": [...] } suitable for scripts. Flags on calls list:

Flag	Description
`--limit N`	Max records per page (1–100, default 20).
`--after CALL_ID`	Return calls older than this id.
`--before CALL_ID`	Return calls newer than this id.
`--all`	Fetch every page and print them together.

When has_more=true, the CLI prints a hint at the bottom of the table with the exact --after flag to use next.

Manage phone numbers

callingbox numbers list                                   # paginated
callingbox numbers list --all                             # every number
callingbox numbers search --area-code 415                 # available to buy
callingbox numbers search --country US --type local --limit 20
callingbox numbers buy +14155551234                       # purchases after confirmation
callingbox numbers buy +14155551234 --yes                 # skip the confirmation prompt

numbers buy charges your credit balance. The CLI asks for an interactive confirmation by default; use --yes / -y in scripts. numbers search is a provider-backed lookup (not paginated); use --limit to control how many candidates are returned.

JSON output for scripts

By default the CLI renders rich tables and panels when stdout is a TTY. Pipe the output, or pass --json, to get machine-readable JSON:

callingbox calls list --json | jq '.data[] | select(.status == "failed")'
callingbox call --agent AGENT_ID --to "+1..." --json

For list commands without --all, the JSON envelope matches the API:

{
  "data": [ /* ... */ ],
  "has_more": true
}

With --all, the output is a plain JSON array since all pages have been flattened.

Global flags

Every command accepts these top-level flags:

Flag	Description
`--api-key KEY`	Override the API key for a single invocation.
`--base-url URL`	Override the base URL (for example a private deployment).
`--json`	Emit raw JSON instead of formatted output.
`--version`	Print the CLI version and exit.
`-h`, `--help`	Show help. Available on every subcommand.

Exit codes

The CLI uses distinct exit codes so scripts can react to specific failure modes:

Code	Meaning
`0`	Success.
`1`	Unexpected error.
`2`	Usage error (bad flags, invalid JSON).
`3`	Authentication error (missing or rejected key).
`4`	Resource not found.
`5`	Bad request from the API.
`6`	Timeout waiting for a call to complete.
`7`	Network error.

Shell completions

Thanks to Typer, the CLI ships with shell completion support for bash, zsh, fish, and PowerShell:

callingbox --install-completion

Or inspect the generated script without installing it:

callingbox --show-completion

Use `python -m callingbox`

If the callingbox entry point isn’t on your PATH (common in some sandboxed envs), invoke the CLI via the module:

python -m callingbox --help

Next steps

SDK overview

Compare the Python SDK, TypeScript SDK, CLI, and raw HTTP.

Python SDK

The library the CLI is built on. Use it for richer programmatic workflows.

Call object

Understand every field printed by callingbox calls get.

Structured results

Design the --returns schema the CLI prints on completion.

​Install

​Authenticate

​Interactive login

​Non-interactive login

​Environment variable

​Check the active credentials

​Log out

​Custom API base URL

​Place a call

​Fire-and-forget

​Timeouts

​List and retrieve calls

​Manage phone numbers

​JSON output for scripts

​Global flags

​Exit codes

​Shell completions

​Use python -m callingbox

​Next steps

SDK overview

Python SDK

Call object

Structured results

Install

Authenticate

Interactive login

Non-interactive login

Environment variable

Check the active credentials

Log out

Custom API base URL

Place a call

Fire-and-forget

Timeouts

List and retrieve calls

Manage phone numbers

JSON output for scripts

Global flags

Exit codes

Shell completions

Use `python -m callingbox`

Next steps