pp-twilio

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/social-and-messaging/twilio/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Twilio — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `twilio-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install twilio --cli-only
   ```
2. Verify: `twilio-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/twilio/cmd/twilio-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for this CLI when an agent or operator needs Twilio data they cannot get in one API call: cross-subaccount aggregation, delivery-failure analysis, TCPA opt-out audits, idle-number cleanup, or any 'how was last week' question. It is also the right tool for incident triage when a CallSid needs the full Call+Recording+Transcription stitch in one command. Skip it for one-off message sends if you already have twilio-cli configured — but for any analytic or investigative workflow it is faster, offline-capable, and agent-native.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Local state that compounds
- **`delivery-failures`** — See why messages failed last week, grouped by error code and destination country, with the dollar cost of those failures totaled.

  _When debugging delivery, agents need the failure distribution, not 4000 individual rows. This command answers 'why is delivery degraded' in one query._

  ```bash
  twilio-pp-cli delivery-failures --since 7d --json
  ```
- **`subaccount-spend`** — One CSV with every subaccount's last-month spend pivoted across SMS, MMS, voice, and recording categories — the agency-billing report nobody else ships.

  _For agency operators, this is the entire monthly billing report in one command. Agents can run it with --period thisMonth for a live forecast._

  ```bash
  twilio-pp-cli subaccount-spend --period last-month --csv > march-billing.csv
  ```
- **`message-status-funnel`** — Distribution of message terminal statuses (delivered, failed, undelivered, sent) with delivery-rate percentages and median time-to-delivery.

  _Operations dashboards need the funnel, not the raw rows. One query is the whole 'is delivery healthy right now' answer._

  ```bash
  twilio-pp-cli message-status-funnel --since 24h --json
  ```
- **`call-disposition`** — Cross-tab of call Status (completed, busy, no-answer, failed, canceled) by AnsweredBy (human, machine_start, fax), with dollar cost per bucket.

  _Outbound campaign tuning depends on knowing the human-pickup rate vs voicemail rate. Agents can answer this without paging through thousands of call records._

  ```bash
  twilio-pp-cli call-disposition --since 7d --json
  ```

### Cross-entity stitches
- **`call-trace`** — Given a CallSid, return everything that happened on that call: metadata, recordings, transcriptions, conference participation — in one structured output.

  _On-call engineers paged about a dropped call need the full picture in seconds, not three API round trips while the customer waits._

  ```bash
  twilio-pp-cli call-trace CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --json
  ```
- **`idle-numbers`** — Phone numbers you are paying for but have not used to send or receive in N days — with the dollar amount you are wasting per month.

  _At $1/number/month, agencies running 100+ subaccount numbers can save hundreds annually. Agents can run it as a monthly cleanup task._

  ```bash
  twilio-pp-cli idle-numbers --since 30d --json
  ```
- **`webhook-audit`** — Group your IncomingPhoneNumbers by their Voice/SMS webhook URL to find single-use URLs that may be orphans pointing at deleted endpoints. Add --probe for a live HEAD check.

  _Orphan webhooks silently fail incoming calls and SMS. Quarterly audit is cheap insurance against silent dropped traffic._

  ```bash
  twilio-pp-cli webhook-audit --probe --json
  ```
- **`conversation`** — All messages and calls involving one phone number, merged into a single timestamped timeline with in/out arrows, body, and duration.

  _When investigating a customer complaint or fraud claim, the full back-and-forth is one query. Agents can answer 'what did we say to this number' without four searches._

  ```bash
  twilio-pp-cli conversation +14155551234 --json
  ```

### Compliance & audit
- **`opt-out-violations`** — Find numbers that texted STOP/UNSUBSCRIBE/END/QUIT and any messages your account sent to them afterwards — the TCPA exposure check the Twilio API has no resource for.

  _TCPA fines are $500–$1,500 per violation. Compliance teams audit for this quarterly; agents can spot-check it any time._

  ```bash
  twilio-pp-cli opt-out-violations --since 90d --json --select to,opt_out_at,subsequent_send_at,message_sid
  ```
- **`error-code-explain`** — Top error codes from your recent messages and calls, with curated one-line explanations and fixes for the most common Twilio errors.

  _Every Twilio user Googles error codes. Bundling the explanation with the count removes a constant context-switch._

  ```bash
  twilio-pp-cli error-code-explain --since 7d --json
  ```

### Agent-native plumbing
- **`sync-status`** — Last sync timestamp and row count per resource in the local store — so you know how fresh every other analytic command is.

  _Without freshness UX every analytic command is suspect. One read tells the agent whether to call sync first._

  ```bash
  twilio-pp-cli sync-status --json
  ```
- **`tail-messages`** — Stream new messages with a status filter as they happen — twilio-pp-cli's --follow that twilio-cli does not ship.

  _Incident triage and on-call response need a live feed of failures, not a polling shell loop. One command, no daemon._

  ```bash
  twilio-pp-cli tail-messages --status failed --follow
  ```

## Command Reference

**2010-04-01** — Manage 2010 04 01

- `twilio-pp-cli 2010-04-01 create-account` — Create a new Twilio Subaccount from the account making the request
- `twilio-pp-cli 2010-04-01 fetch-account` — Fetch the account specified by the provided Account Sid
- `twilio-pp-cli 2010-04-01 list-account` — Retrieves a collection of Accounts belonging to the account used to make the request
- `twilio-pp-cli 2010-04-01 update-account` — Modify the properties of a given Account

**addresses** — Manage addresses

- `twilio-pp-cli addresses delete-address` — Delete address
- `twilio-pp-cli addresses fetch-address` — Fetch address
- `twilio-pp-cli addresses update-address` — Update address

**addresses-json** — Manage addresses json

- `twilio-pp-cli addresses-json create-address` — Create address
- `twilio-pp-cli addresses-json list-address` — List address

**applications** — Manage applications

- `twilio-pp-cli applications delete` — Delete the application by the specified application sid
- `twilio-pp-cli applications fetch` — Fetch the application specified by the provided sid
- `twilio-pp-cli applications update` — Updates the application's properties

**applications-json** — Manage applications json

- `twilio-pp-cli applic