> ## 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.

# Use the Plivo CLI with a coding agent

> Give Claude Code, Cursor, Codex, Gemini CLI, Antigravity or any agent a reliable way to drive Plivo: one prompt to start, the Plivo skills as files or plugins, and the rules agents follow.

Give your coding agent the CLI reference so it can find commands and work with your Plivo account. A skill is a `SKILL.md` reference file that the agent loads when it needs instructions.

## Start

Paste this into Claude Code, Cursor or Codex:

```text Prompt theme={null}
Install the Plivo CLI: curl -fsSL https://raw.githubusercontent.com/plivo/plivo-cli/main/install.sh | bash. Then run plivo skill install all and use the plivo CLI for my Plivo tasks.
```

You complete the browser sign-in. The skills ask you before anything that spends money or changes your account.

> [!NOTE]
>
> For Codex, run `plivo skill install cli --agent codex`. For Windows and other installation methods, use [Install and log in](https://plivo.com/docs/cli/install.md). To install the skills as a plugin or extension instead, see [below](#install-as-a-plugin-or-extension).

## Which skill does what

Skills ship inside the CLI, so installing one needs no network call. Install the CLI reference first, then the task skill you need.

| Skill | What it covers | Guide |
| - | - | - |
| `cli` | The CLI itself: every command, the JSON and error shapes, the exit codes and the safety rules. Installed when you give no name. | This page |
| `audio-streaming` | Checks credit, know your customer (KYC) compliance and numbers; sets up an echo, Pipecat or existing voice agent; connects it through a tunnel, application and number; then places a test call. | [Build with a coding agent](https://plivo.com/docs/audio-streaming/integration-guides/ai-coding-agent.md) |
| `sip-trunking` | Connecting an AI voice platform such as LiveKit, ElevenLabs, Retell or Vapi over SIP trunking. | [SIP trunking skill](https://plivo.com/docs/voice-agents/sip-trunking/integration-guides/ai-coding-agent.md) |
| `voice-xml` | Writing and fixing Plivo Voice XML. | [Voice XML skill](https://plivo.com/docs/voice/xml/ai-coding-agent.md) |

## Offer after login

Run `plivo login` inside Claude Code, Cursor or Codex, and after you sign in it offers to install the Plivo skills where that agent reads them: `Install the Plivo skills for Claude Code? (Y/n)`

* It asks once per machine, whatever the answer, and not at all when current copies are installed.
* Without a terminal to ask on, such as an agent's own shell, it prints the command instead: `Install the Plivo skills for Claude Code with: plivo skill install all`.
* `plivo login --yes` installs them without asking; `plivo login --quiet` skips the offer. The offer never fails the login. If an install fails, it prints a warning and the command to retry.

## Install options

```bash theme={null}
plivo skill install                     # the CLI skill → ~/.claude/skills/plivo-cli/SKILL.md (default --agent claude: read by Claude Code and Cursor)
plivo skill install audio-streaming     # → ~/.claude/skills/plivo-audio-streaming/
plivo skill install all                 # every skill
plivo skill install all --agent codex   # → ~/.agents/skills/, where Codex reads skills
plivo skill install all --project       # → <repo>/.claude/skills/ in this git repo, for everyone who clones it
plivo skill install --dir ./my-agent/skills/plivo-cli   # a folder you choose; one skill at a time
plivo skill install --print             # write to stdout for any other tool; one skill at a time
plivo skill install all --dry-run       # show where each would go, write nothing
plivo skill list                        # every skill and whether it is installed
plivo skill list --agent codex          # the same, in ~/.agents/skills
```

* `--agent` can't be combined with `--dir` or `--project`. `--project` is refused outside a git repository. `plivo skill list --project` works from any folder in the repository and shows each skill as `installed`, `installed (differs from bundled)` or `not installed`.
* **Edited copies are kept.** A copy that matches no released version holds someone's edits. `skill install` keeps it and exits `5` unless you add `--force`. The other skills are still installed.

### Keep the skills up to date

A newer CLI brings newer skills. [Upgrade the CLI](https://plivo.com/docs/cli/install.md#upgrade), then run:

```bash theme={null}
plivo skill update --dry-run    # show what would change, write nothing
plivo skill update              # update what is installed
plivo skill update --force      # also replace copies you edited
```

`skill update` looks in `~/.claude/skills` (Claude Code and Cursor), `~/.agents/skills` (Codex) and, inside a git repository, the same two folders under `<repo>`. It replaces a copy only when it matches a released version; anything else counts as your edit and is kept unless you add `--force`. Skills that aren't installed stay that way.

> [!NOTE]
>
> The `first-agent` skill is retired: the `audio-streaming` skill's guided flow replaces it. Installing `audio-streaming` into the default skills folder renames an old `plivo-first-agent` skill's file to `SKILL.md.retired`, so nothing you wrote is lost. `plivo skill update` reports one still installed, with the command that removes it.

## Install as a plugin or extension

Some agents install the Plivo skills as a plugin or extension, kept current with the [Plivo CLI repository](https://github.com/plivo/plivo-cli). The skills still run the Plivo CLI, so install it and run `plivo login` once. **Cursor** reads the skills that `plivo skill install` writes to `~/.claude/skills`.

| Agent | Install |
| - | - |
| Claude Code 2.1.275 or later | Inside Claude Code: `/plugin install plivo --marketplace plivo/plivo-cli` |
| Older Claude Code | `/plugin marketplace add plivo/plivo-cli`, then `/plugin install plivo@plivo` |
| Gemini CLI | `gemini extensions install https://github.com/plivo/plivo-cli` |
| Codex | `codex plugin marketplace add plivo/plivo-cli`, then `codex plugin add plivo@plivo` |
| Google Antigravity (app, IDE and CLI) | `agy plugin install https://github.com/plivo/plivo-cli/tree/main/antigravity/plivo` |

Owners of a Claude organization can add `https://github.com/plivo/plivo-cli` under **Organization settings > Plugins & skills** to give every member the skills.

## How an agent finds commands

Help, the command map, schemas and docs need no login. `plivo ask` needs a saved profile.

| To learn | Run |
| - | - |
| The flags of one command | `plivo <command> --help` |
| Every command, argument and flag, as JSON | `plivo --map`, such as `plivo --map --query 'data.commands[].path'` |
| One command as JSON, with response fields where the CLI reads them | `plivo <command> --schema`, such as `plivo sip connect plan --schema` |
| What a docs page says | `plivo docs search <keywords>`, `plivo docs show <page>`. See [Read the docs from the terminal](https://plivo.com/docs/cli/configure.md#read-the-docs-from-the-terminal) |
| A how-to answer, with sources | `plivo ask "<question>"`. See [Ask a question](https://plivo.com/docs/cli/apis/help.md#ask-a-question) |

## Rules agents follow

Selected actions require `--yes`, but some billed operations, such as `lookup`, do not. Approval must come from the user, not from assuming the CLI gates every change.

* **Use structured output.** With `-o json`, most commands return `data` on success and `error.code` on failure. `ask -o json` emits JSON Lines, so parse it one line at a time. Action commands such as hangups, updates and deletes print a result too. The local tools (`streams test`, `streams forward`, `upgrade`) send progress to stderr, so stdout stays parseable.
* **Preview changes with `--dry-run`.** Some previews still read account data. Get approval for spending or account changes, then add `--yes` where the command requires it.
* **Branch on the exit code.** `0` success, `1` bad input, `2` login, `3` network, `4` rate limited, `5` refused for safety, `6` CLI too old. See [Exit codes](https://plivo.com/docs/cli/configure.md#exit-codes).
* **Retry only when `retryable` is `true`.** A network failure on a write is `retryable: false`, because the request may have gone through. Read the resource back before you send it again.
* **Don't invent flags.** `--help`, `--schema` and `plivo --map` are the source of truth. An unknown flag is refused, and a mistyped subcommand fails with `BAD_INPUT` and a suggestion.
* **Diagnose before guessing.** Use [`plivo ask`](https://plivo.com/docs/cli/apis/help#ask-a-question) for how-to questions and [`plivo … diagnose`](https://plivo.com/docs/cli/voice-agent/diagnose-call) for a failed call or message. Both are rate-limited per account. With `-o json`, `diagnose` returns one result with fixed fields; see [Read the result in a script](https://plivo.com/docs/cli/voice-agent/diagnose-call.md#read-the-result-in-a-script).
* **Read only what you need.** `--query` picks fields and `--all` reads every page of a list. See [Pick fields with JMESPath](https://plivo.com/docs/cli/configure.md#pick-fields-with-jmespath).
* **Log in once, by a person.** There is no headless login and no credentials from the environment. A person runs `plivo login` once on the machine the agent uses. Set `PLIVO_FEEDBACK_PROMPT=0` and `CI=1` to turn off prompts. See [Run in CI and from agents](https://plivo.com/docs/cli/install.md#run-in-ci-and-from-agents).
* **Report CLI bugs.** After a command fails unexpectedly, `plivo feedback --bug --dry-run` shows a bug report you can send.