> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration, flags and output

> Global flags, JSON output and exit codes, config keys, and how to turn telemetry off.

## 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](/docs/cli/configure#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:

```json theme={null}
{ "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:

```json theme={null}
{ "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](/docs/cli/configure#telemetry) for exactly what is and isn't sent.

```bash theme={null}
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](/docs/cli/authenticate#use-api-credentials-ci-and-agents).
* `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:

```bash theme={null}
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):

```bash theme={null}
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.