Configuration, flags and output

Global flags

The Plivo CLI supports these flags on every command. Command: plivo <command> [flags] Flags

-o, --output <format>: output format: table or json. Defaults to table when attached to a terminal and json when piped. See Output and exit codes.
-y, --yes: confirm a command that spends money or deletes data. Without it, such commands are refused with exit code 5.
--dry-run: print the HTTP request the command would make (method, URL, body) and exit without sending it.
--profile <name>: run under a named profile from ~/.plivo/config.toml instead of the active one.
--timeout <seconds>: request timeout (default 30).
--log-level <level>: debug, info, warn, error, or none (default warn). debug prints every HTTP request and response to stderr.
-q, --quiet: suppress non-data output.
--no-color: disable colored output.
-h, --help: help for any command.

--explain is not a global flag. It narrates what a command will do in plain English before running it, and it exists only on the commands that implement it: api, account applications create, auth whoami, voice calls make, messaging sms send, messaging whatsapp send, messaging mms send, numbers buy, numbers release and verify sessions create. Every other command rejects it rather than accepting it and doing nothing.

plivo --version (or plivo -v) prints the CLI version; this works on the root command only, not after a subcommand.

Output and exit codes

The CLI is built to be parsed. Every command has one success shape, one error shape, and a small set of exit codes.

Success envelope

With -o json, an API-backed command prints the upstream API response verbatim under data. Nothing is dropped or renamed:

{ "data": { "api_id": "…", "meta": { "limit": 20, "offset": 0, "total_count": 6 }, "objects": [ … ] } }

Single resources have the resource under data; list commands have the API’s meta and objects under data, so objects live at data.objects[...]. Commands that resolve credentials add "meta": {"source": "env" | "profile"}. The local tools that do not call the API (streams test, streams forward, upgrade, config telemetry) honour -o json too: each emits one machine-readable summary on stdout and sends its progress output to stderr, so stdout stays parseable.

Error envelope

Errors go to stderr as JSON and the process exits non-zero:

{ "error": { "code": "RESOURCE_NOT_FOUND", "message": "CDR for call uuid … not found",
             "hint": "List available resources with the matching `... list` command.",
             "status_code": 404, "request_id": "…", "retryable": false } }

Switch on code, never on message text.

Exit codes

Exit	Meaning	Typical `code` values
`0`	success	;
`1`	bad input, or the API rejected the request	`USER_ERROR`, `BAD_INPUT`, `VALIDATION_ERROR`, `RESOURCE_NOT_FOUND`, `UPSTREAM_ERROR`
`2`	authentication	`AUTH_MISSING`, `AUTH_INVALID`, `AUTH_FORBIDDEN`, `AUTH_EXPIRED`
`3`	network	`NETWORK_ERROR`
`5`	refused for safety	`DESTRUCTIVE_REFUSED`; a spend or delete command without `--yes`
`130`	interrupted (Ctrl-C)	;

Safety

Any command that spends money or deletes data, voice calls make, messaging * send, numbers buy, numbers release, * delete, and mutating plivo api calls, is refused unless --yes is present. The refusal happens locally, before any request is sent. Use --dry-run to see the exact request first.

Configuration keys

Use the config command to view and change CLI settings stored in ~/.plivo/config.toml. Command: plivo config <subcommand>

`plivo config telemetry on|off|status`

Turn identity telemetry on or off, or show its current state. See Telemetry for exactly what is and isn’t sent.

plivo config telemetry status
plivo config telemetry off

The environment variable PLIVO_CLI_TELEMETRY=0 does the same for a single shell session or CI job and wins over the config file.

`plivo config get <key>` / `plivo config set <key> <value>`

Read or write an individual setting. Currently supported key: telemetry. Environment variables

PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN: headless credentials.
PLIVO_CLI_TELEMETRY=0: disable identity telemetry.
PLIVO_FEEDBACK_PROMPT=0: silence the post-command feedback prompt.
PLIVO_FEEDBACK_TELEMETRY=0: disable plivo feedback submission entirely.
PLIVO_NO_UPDATE_CHECK=1: silence the “newer version available” hint.

Telemetry

The Plivo CLI sends a small amount of usage data with each request so we can see which commands are used, what fails, and which versions are in the field. It is enabled by default, and you can turn the identity part off at any time.

What is collected

On every request to Plivo:

CLI version, operating system, and architecture (used for the upgrade hint and compatibility).
The command name (for example voice calls list): never its arguments or flag values.
When identity telemetry is on: the account’s Auth ID, the email of the logged-in user, the account region, and an internal user identifier. This lets us see usage per person within an organisation.

plivo feedback additionally sends the rating and comment you type.

What is never collected

Your auth token, API keys, or passwords.
Phone numbers, call or message UUIDs, message bodies, audio, or recordings.
URLs you pass to commands (answer URLs, WebSocket URLs, callback URLs).
Flag values, file contents, or anything from your Plivo account data.

How to turn it off

Identity telemetry is an account-level setting you control:

plivo config telemetry off        # persistent, stored in ~/.plivo/config.toml
plivo config telemetry status

or, for a single shell session or CI job (takes precedence over the config file):

PLIVO_CLI_TELEMETRY=0 plivo voice calls list

With telemetry off, requests still carry the CLI version, OS, and architecture (the server needs them to tell you when an upgrade is available) but no identity fields. Set PLIVO_FEEDBACK_TELEMETRY=0 to disable plivo feedback submission as well.

Getting started

Voice agents with Audio Streaming

Plivo APIs

Configuration, flags and output

Global flags

Output and exit codes

Success envelope

Error envelope

Exit codes

Safety

Configuration keys

`plivo config telemetry on|off|status`

`plivo config get <key>` / `plivo config set <key> <value>`

Telemetry

What is collected

What is never collected

How to turn it off

​Global flags

​Output and exit codes

​Success envelope

​Error envelope

​Exit codes

​Safety

​Configuration keys

​plivo config telemetry on|off|status

​plivo config get <key> / plivo config set <key> <value>

​Telemetry

​What is collected

​What is never collected

​How to turn it off

Global flags

Output and exit codes

Success envelope

Error envelope

Exit codes

Safety

Configuration keys

`plivo config telemetry on|off|status`

`plivo config get <key>` / `plivo config set <key> <value>`

Telemetry

What is collected

What is never collected

How to turn it off