CLI

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 — 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 just 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.

Run against a local backend

For local development, point the CLI at your local backend the same way the SDK does:

export CALLINGBOX_BASE_URL=http://localhost:3002
export CALLINGBOX_API_KEY=sk_test_...
callingbox calls list

You can also pass --base-url per invocation, or persist it with callingbox login --base-url http://localhost:3002.

Place a call

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

callingbox call \
  --to "+15551234567" \
  --prompt "Confirm appointment tomorrow 2pm" \
  --returns '{"confirmed": "boolean"}'

Flags:

Flag	Required	Description
`--to`	yes	Destination number in E.164 format.
`--prompt`	yes	Instruction for the AI agent.
`--context`	no	JSON object passed to the agent as context.
`--returns`	no	JSON object describing the structured data to extract.
`--from`	no	Caller ID. Defaults to your oldest active number.
`--language`	no	BCP-47 language code.
`--webhook-url`	no	POST call events to this URL.
`--voicemail-action`	no	`hangup` or `leave_message`.
`--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`.

Fire-and-forget

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

callingbox call --to "+15551234567" --prompt "Quick reminder" --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

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 --to "+1..." --prompt "..." --returns '{"confirmed":"boolean"}' --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 (self-hosted / local dev).
`--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.

Start

SDKs & Tools

Core Model

Account

Reference

Install

Authenticate

Environment variable

Check the active credentials

Log out

Run against a local backend

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

Start

SDKs & Tools

Core Model

Account

Reference

​Install

​Authenticate

​Interactive login

​Non-interactive login

​Environment variable

​Check the active credentials

​Log out

​Run against a local backend

​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

Run against a local backend

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