pindo-cli

The official command-line interface for Pindo, the SMS platform. Log in once, then send test messages, check your balance, manage your organization and pull reports from your terminal or from scripts.

• Installation
• Quick start
• Commands
• Authentication and configuration
• Reports
• Using the CLI in scripts
• Using the API directly
• Development

Installation

Requires Python 3.10 or newer.

The recommended way is pipx (or uv), which installs the pindo command in its own isolated environment:

pipx install pindo-cli

uv tool install pindo-cli

Plain pip works too:

python -m pip install --upgrade pindo-cli

Check it worked:

pindo --version

Quick start

pindo register                 # create an account (skip if you have one)
pindo login                    # saves your API token to ~/.pindo/config.toml
pindo balance                  # USD 71421.953
pindo sms --to +250781234567 --text "Hello from Pindo" --sender Pindo

Every command prompts for anything you leave out, and pindo <command> --help (or -h) lists its options.

Commands

Global options go before the command:

pindo --debug balance

Phone numbers must be in international format with the country code (+250781234567). Spaces, dashes and brackets are stripped, and a missing leading + is added.

Authentication and configuration

pindo login stores your token in ~/.pindo/config.toml. The file and its folder can only be read by your user account. Every command that needs a token looks for one in this order:

1. --token / -t on the command line
2. the PINDO_TOKEN environment variable (handy for CI and cron jobs)
3. the config file written by pindo login

Run pindo config show to see which token is in use and where it came from.

Reports

Reporting commands live under pindo report and all share these options:

Run pindo report --help to see the available reports.

Using the CLI in scripts

Errors are printed to stderr as a single Error: ... line, and the exit code tells you what happened:

$ pindo balance --token wrong
Error: Unauthorized. Your token is invalid or expired; run `pindo login`. (HTTP 401)
$ echo $?
1

Read-only requests are retried automatically, with backoff, when the server is temporarily unavailable (HTTP 429/502/503/504). Requests that send messages or change data are never retried, so an SMS is never sent twice.

Using the API directly

The CLI is a thin client for the Pindo REST API. Examples for sending SMS (single and bulk), inbound messages, delivery-report webhooks and PindoVerify in cURL, Python, Node.js, PHP, Ruby, Go, Java and C# are in docs/api.md.

Development

You need Poetry 2.x.

git clone https://github.com/pindoio/pindo-cli.git
cd pindo-cli
poetry install
poetry run pre-commit install   # optional: lint and format on every commit

See CONTRIBUTING.md for how the code is laid out and how releases work. To report a security issue, see SECURITY.md.

License

MIT