mvanhorn 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:
- Install via the Printing Press installer. It defaults binaries to
$HOME/.local/binon macOS/Linux and%LOCALAPPDATA%\Programs\PrintingPress\binon Windows:npx -y @mvanhorn/printing-press-library install twilio --cli-only - Verify:
twilio-pp-cli --version - Ensure the reported install directory is on
$PATHfor 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.6 or newer):
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.
twilio-pp-cli delivery-failures --since 7d --jsonsubaccount-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.
twilio-pp-cli subaccount-spend --period last-month --csv > march-billing.csvmessage-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.
twilio-pp-cli message-status-funnel --since 24h --jsoncall-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.
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.
twilio-pp-cli call-trace CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --jsonidle-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.
twilio-pp-cli idle-numbers --since 30d --jsonwebhook-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.
twilio-pp-cli webhook-audit --probe --jsonconversation— 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.
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.
twilio-pp-cli opt-out-violations --since 90d --json --select to,opt_out_at,subsequent_send_at,message_siderror-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.
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.
twilio-pp-cli sync-status --jsontail-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.
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 requesttwilio-pp-cli 2010-04-01 fetch-account— Fetch the account specified by the provided Account Sidtwilio-pp-cli 2010-04-01 list-account— Retrieves a collection of Accounts belonging to the account used to make the requesttwilio-pp-cli 2010-04-01 update-account— Modify the properties of a given Account
addresses — Manage addresses
twilio-pp-cli addresses delete-address— Delete addresstwilio-pp-cli addresses fetch-address— Fetch addresstwilio-pp-cli addresses update-address— Update address
addresses-json — Manage addresses json
twilio-pp-cli addresses-json create-address— Create addresstwilio-pp-cli addresses-json list-address— List address
applications — Manage applications
twilio-pp-cli applications delete— Delete the application by the specified application sidtwilio-pp-cli applications fetch— Fetch the application specified by the provided sidtwilio-pp-cli applications update— Updates the application's properties
applications-json — Manage applications json
twilio-pp-cli applications-json create-application— Create a new application within your accounttwilio-pp-cli applications-json list-application— Retrieve a list of applications representing an application within the requesting account
authorized-connect-apps — Manage authorized connect apps
twilio-pp-cli authorized-connect-apps <AccountSid> <ConnectAppSid>— Fetch an instance of an authorized-connect-app
authorized-connect-apps-json — Manage authorized connect apps json
twilio-pp-cli authorized-connect-apps-json <AccountSid>— Retrieve a list of authorized-connect-apps belonging to the account used to make the request
available-phone-numbers — Manage available phone numbers
twilio-pp-cli available-phone-numbers <AccountSid> <CountryCode>— Fetch country
available-phone-numbers-json — Manage available phone numbers json
twilio-pp-cli available-phone-numbers-json <AccountSid>— List available phone number country
balance-json — Manage balance json
twilio-pp-cli balance-json <AccountSid>— Fetch the balance for an Account based on Account Sid. Balance changes may not be reflected immediately. Child...
calls — Manage calls
twilio-pp-cli calls delete— Delete a Call record from your account. Once the record is deleted, it will no longer appear in the API and Account...twilio-pp-cli calls fetch— Fetch the call specified by the provided Call SIDtwilio-pp-cli calls update— Initiates a call redirect or terminates a call
calls-json — Manage calls json
twilio-pp-cli calls-json create-call— Create a new outgoing call to phones, SIP-enabled endpoints or Twilio Client connectionstwilio-pp-cli calls-json list-call— Retrieves a collection of calls made to and from your account
conferences — Manage conferences
twilio-pp-cli conferences fetch— Fetch an instance of a conferencetwilio-pp-cli conferences update— Update
conferences-json — Manage conferences json
twilio-pp-cli conferences-json <AccountSid>— Retrieve a list of conferences belonging to the account used to make the request
connect-apps — Manage connect apps
twilio-pp-cli connect-apps delete— Delete an instance of a connect-apptwilio-pp-cli connect-apps fetch— Fetch an instance of a connect-apptwilio-pp-cli connect-apps update— Update a connect-app with the specified parameters
connect-apps-json — Manage connect apps json
twilio-pp-cli connect-apps-json <AccountSid>— Retrieve a list of connect-apps belonging to the account used to make the request
incoming-phone-numbers — Manage incoming phone numbers
twilio-pp-cli incoming-phone-numbers create-local— Create localtwilio-pp-cli incoming-phone-numbers create-mobile— Create mobiletwilio-pp-cli incoming-phone-numbers create-toll-free— Create toll freetwilio-pp-cli incoming-phone-numbers delete— Delete a phone-numbers belonging to the account used to make the request.twilio-pp-cli incoming-phone-numbers fetch— Fetch an incoming-phone-number belonging to the account used to make the request.twilio-pp-cli incoming-phone-numbers list-local— List localtwilio-pp-cli incoming-phone-numbers list-mobile— List mobiletwilio-pp-cli incoming-phone-numbers list-toll-free— List toll freetwilio-pp-cli incoming-phone-numbers update— Update an incoming-phone-number instance.
incoming-phone-numbers-json — Manage incoming phone numbers json
twilio-pp-cli incoming-phone-numbers-json create-incoming-phone-number— Purchase a phone-number for the account.twilio-pp-cli incoming-phone-numbers-json list-incoming-phone-number— Retrieve a list of incoming-phone-numbers belonging to the account used to make the request.
keys — Manage keys
twilio-pp-cli keys delete— Deletetwilio-pp-cli keys fetch— Fetchtwilio-pp-cli keys update— Update
keys-json — Manage keys json
twilio-pp-cli keys-json create-new-key— Create new keytwilio-pp-cli keys-json list-key— List key
messages — Manage messages
twilio-pp-cli messages delete— Deletes a Message resource from your accounttwilio-pp-cli messages fetch— Fetch a specific Messagetwilio-pp-cli messages update— Update a Message resource (used to redact Messagebodytext and to cancel not-yet-sent messages)
messages-json — Manage messages json
twilio-pp-cli messages-json create-message— Send a messagetwilio-pp-cli messages-json list-message— Retrieve a list of Message resources associated with a Twilio Account
notifications — Manage notifications
twilio-pp-cli notifications <AccountSid> <Sid>— Fetch a notification belonging to the account used to make the request
notifications-json — Manage notifications json
twilio-pp-cli notifications-json <AccountSid>— Retrieve a list of notifications belonging to the account used to make the request
outgoing-caller-ids — Manage outgoing caller ids
twilio-pp-cli outgoing-caller-ids delete— Delete the caller-id specified from the accounttwilio-pp-cli outgoing-caller-ids fetch— Fetch an outgoing-caller-id belonging to the account used to make the requesttwilio-pp-cli outgoing-caller-ids update— Updates the caller-id
outgoing-caller-ids-json — Manage outgoing caller ids json
twilio-pp-cli outgoing-caller-ids-json create-validation-request— Create validation requesttwilio-pp-cli outgoing-caller-ids-json list-outgoing-caller-id— Retrieve a list of outgoing-caller-ids belonging to the account used to make the request
queues — Manage queues
twilio-pp-cli queues delete— Remove an empty queuetwilio-pp-cli queues fetch— Fetch an instance of a queue identified by the QueueSidtwilio-pp-cli queues update— Update the queue with the new parameters
queues-json — Manage queues json
twilio-pp-cli queues-json create-queue— Create a queuetwilio-pp-cli queues-json list-queue— Retrieve a list of queues belonging to the account used to make the request
recordings — Manage recordings
twilio-pp-cli recordings delete— Delete a recording from your accounttwilio-pp-cli recordings fetch— Fetch an instance of a recording
recordings-json — Manage recordings json
twilio-pp-cli recordings-json <AccountSid>— Retrieve a list of recordings belonging to the account used to make the request
signing-keys — Manage signing keys
twilio-pp-cli signing-keys delete— Deletetwilio-pp-cli signing-keys fetch— Fetchtwilio-pp-cli signing-keys update— Update
signing-keys-json — Manage signing keys json
twilio-pp-cli signing-keys-json create-new-signing-key— Create a new Signing Key for the account making the request.twilio-pp-cli signing-keys-json list-signing-key— List signing key
sip — Manage sip
twilio-pp-cli sip create-auth-calls-credential-list-mapping— Create a new credential list mapping resourcetwilio-pp-cli sip create-auth-calls-ip-access-control-list-mapping— Create a new IP Access Control List mappingtwilio-pp-cli sip create-auth-registrations-credential-list-mapping— Create a new credential list mapping resourcetwilio-pp-cli sip create-credential— Create a new credential resource.twilio-pp-cli sip create-credential-list— Create a Credential Listtwilio-pp-cli sip create-credential-list-mapping— Create a CredentialListMapping resource for an account.twilio-pp-cli sip create-domain— Create a new Domaintwilio-pp-cli sip create-ip-access-control-list— Create a new IpAccessControlList resourcetwilio-pp-cli sip create-ip-access-control-list-mapping— Create a new IpAccessControlListMapping resource.twilio-pp-cli sip create-ip-address— Create a new IpAddress resource.twilio-pp-cli sip delete-auth-calls-credential-list-mapping— Delete a credential list mapping from the requested domaintwilio-pp-cli sip delete-auth-calls-ip-access-control-list-mapping— Delete an IP Access Control List mapping from the requested domaintwilio-pp-cli sip delete-auth-registrations-credential-list-mapping— Delete a credential list mapping from the requested domaintwilio-pp-cli sip delete-credential— Delete a credential resource.twilio-pp-cli sip delete-credential-list— Delete a Credential Listtwilio-pp-cli sip delete-credential-list-mapping— Delete a CredentialListMapping resource from an account.twilio-pp-cli sip delete-domain— Delete an instance of a Domaintwilio-pp-cli sip delete-ip-access-control-list— Delete an IpAccessControlList from the requested accounttwilio-pp-cli sip delete-ip-access-control-list-mapping— Delete an IpAccessControlListMapping resource.twilio-pp-cli sip delete-ip-address— Delete an IpAddress resource.twilio-pp-cli sip fetch-auth-calls-credential-list-mapping— Fetch a specific instance of a credential list mappingtwilio-pp-cli sip fetch-auth-calls-ip-access-control-list-mapping— Fetch a specific instance of an IP Access Control List mappingtwilio-pp-cli sip fetch-auth-registrations-credential-list-mapping— Fetch a specific instance of a credential list mappingtwilio-pp-cli sip fetch-credential— Fetch a single credential.twilio-pp-cli sip fetch-credential-list— Get a Credential Listtwilio-pp-cli sip fetch-credential-list-mapping— Fetch a single CredentialListMapping resource from an account.twilio-pp-cli sip fetch-domain— Fetch an instance of a Domaintwilio-pp-cli sip fetch-ip-access-control-list— Fetch a specific instance of an IpAccessControlListtwilio-pp-cli sip fetch-ip-access-control-list-mapping— Fetch an IpAccessControlListMapping resource.twilio-pp-cli sip fetch-ip-address— Read one IpAddress resource.twilio-pp-cli sip list-auth-calls-credential-list-mapping— Retrieve a list of credential list mappings belonging to the domain used in the requesttwilio-pp-cli sip list-auth-calls-ip-access-control-list-mapping— Retrieve a list of IP Access Control List mappings belonging to the domain used in the requesttwilio-pp-cli sip list-auth-registrations-credential-list-mapping— Retrieve a list of credential list mappings belonging to the domain used in the requesttwilio-pp-cli sip list-credential— Retrieve a list of credentials.twilio-pp-cli sip list-credential-list— Get All Credential Liststwilio-pp-cli sip list-credential-list-mapping— Read multiple CredentialListMapping resources from an account.twilio-pp-cli sip list-domain— Retrieve a list of domains belonging to the account used to make the requesttwilio-pp-cli sip list-ip-access-control-list— Retrieve a list of IpAccessControlLists that belong to the account used to make the requesttwilio-pp-cli sip list-ip-access-control-list-mapping— Retrieve a list of IpAccessControlListMapping resources.twilio-pp-cli sip list-ip-address— Read multiple IpAddress resources.twilio-pp-cli sip update-credential— Update a credential resource.twilio-pp-cli sip update-credential-list— Update a Credential Listtwilio-pp-cli sip update-domain— Update the attributes of a domaintwilio-pp-cli sip update-ip-access-control-list— Rename an IpAccessControlListtwilio-pp-cli sip update-ip-address— Update an IpAddress resource.
sms — Manage sms
twilio-pp-cli sms fetch-short-code— Fetch an instance of a short codetwilio-pp-cli sms list-short-code— Retrieve a list of short-codes belonging to the account used to make the requesttwilio-pp-cli sms update-short-code— Update a short code with the following parameters
tokens-json — Manage tokens json
twilio-pp-cli tokens-json <AccountSid>— Create a new token for ICE servers
transcriptions — Manage transcriptions
twilio-pp-cli transcriptions delete— Delete a transcription from the account used to make the requesttwilio-pp-cli transcriptions fetch— Fetch an instance of a Transcription
transcriptions-json — Manage transcriptions json
twilio-pp-cli transcriptions-json <AccountSid>— Retrieve a list of transcriptions belonging to the account used to make the request
usage — Manage usage
twilio-pp-cli usage create-trigger— Create a new UsageTriggertwilio-pp-cli usage delete-trigger— Delete triggertwilio-pp-cli usage fetch-trigger— Fetch and instance of a usage-triggertwilio-pp-cli usage list-record— Retrieve a list of usage-records belonging to the account used to make the requesttwilio-pp-cli usage list-record-all-time— List record all timetwilio-pp-cli usage list-record-daily— List record dailytwilio-pp-cli usage list-record-last-month— List record last monthtwilio-pp-cli usage list-record-monthly— List record monthlytwilio-pp-cli usage list-record-this-month— List record this monthtwilio-pp-cli usage list-record-today— List record todaytwilio-pp-cli usage list-record-yearly— List record yearlytwilio-pp-cli usage list-record-yesterday— List record yesterdaytwilio-pp-cli usage list-trigger— Retrieve a list of usage-triggers belonging to the account used to make the requesttwilio-pp-cli usage update-trigger— Update an instance of a usage trigger
Finding the right command
When you know what you want to do but not which command does it, ask the CLI directly:
twilio-pp-cli which "<capability in your own words>"
which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.
Recipes
Weekly delivery-failure report
twilio-pp-cli delivery-failures --since 7d --json --select error_code,to_country,count,cost_total
Runs the failure aggregation against the local store, narrows the response to the four fields that matter so an agent can summarise without parsing 4000 raw rows.
Last-month agency billing CSV
twilio-pp-cli subaccount-spend --period last-month --csv > march-billing.csv
Walks every subaccount, calls usage/records per subaccount, pivots categories to columns, writes one wide CSV the finance team can paste straight into a spreadsheet.
On-call call-trace from a Slack page
twilio-pp-cli call-trace CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --json --select call.status,call.duration,recordings,transcriptions.text
Single command for the full Call → Recording → Transcription chain. Use --select with dotted paths to keep the response small enough that an agent can summarise it in a Slack reply.
Quarterly TCPA opt-out audit
twilio-pp-cli opt-out-violations --since 90d --csv > q1-opt-out-audit.csv
Local temporal join finds inbound STOP/UNSUBSCRIBE messages and any subsequent outbound messages to the same number — the report compliance teams pay legal teams to construct manually today.
Find idle numbers wasting money
twilio-pp-cli idle-numbers --since 30d --json --select phone_number,friendly_name,monthly_cost,last_activity
LEFT JOIN over IncomingPhoneNumbers / Messages / Calls flagging numbers with no activity in 30 days. Output is one row per number with the dollar amount being wasted per month.
Auth Setup
Twilio uses HTTP Basic auth. You can authenticate with your Account SID (AC...) plus your Auth Token, OR with a scoped API Key SID (SK...) plus its Secret. The Account SID is always required because it is part of the URL path. Run twilio-pp-cli doctor to verify your credentials, detect whether the key is master or scoped, and warn on parent/subaccount mismatches.
Run twilio-pp-cli doctor to verify setup.
Agent Mode
Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.
Pipeable — JSON on stdout, errors on stderr
Filterable —
--selectkeeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:twilio-pp-cli 2010-04-01 create-account --agent --select id,name,statusPreviewable —
--dry-runshows the request without sendingOffline-friendly — sync/search commands can use the local SQLite store when available
Non-interactive — never prompts, every input is a flag
Explicit retries — use
--idempotentonly when an already-existing create should count as success, and--ignore-missingonly when a missing delete target should count as success
Response envelope
Commands that read from the local store or the API wrap output in a provenance envelope:
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <data>
}
Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
Agent Feedback
When you (or the agent) notice something off about this CLI, record it:
twilio-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
twilio-pp-cli feedback --stdin < notes.txt
twilio-pp-cli feedback list --json --limit 10
Entries are stored locally at ~/.twilio-pp-cli/feedback.jsonl. They are never POSTed unless TWILIO_FEEDBACK_ENDPOINT is set AND either --send is passed or TWILIO_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
Output Delivery
Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
| Sink | Effect |
|---|---|
stdout |
Default; write to stdout only |
file:<path> |
Atomically write output to <path> (tmp + rename) |
webhook:<url> |
POST the output body to the URL (application/json or application/x-ndjson when --compact) |
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
Named Profiles
A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
twilio-pp-cli profile save briefing --json
twilio-pp-cli --profile briefing 2010-04-01 create-account
twilio-pp-cli profile list --json
twilio-pp-cli profile show briefing
twilio-pp-cli profile delete briefing --yes
Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | Usage error (wrong arguments) |
| 3 | Resource not found |
| 4 | Authentication required |
| 5 | API error (upstream issue) |
| 7 | Rate limited (wait and retry) |
| 10 | Config error |
Argument Parsing
Parse $ARGUMENTS:
- Empty,
help, or--help→ showtwilio-pp-cli --helpoutput - Starts with
install→ ends withmcp→ MCP installation; otherwise → see Prerequisites above - Anything else → Direct Use (execute as CLI command with
--agent)
MCP Server Installation
- Install the MCP server:
go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/twilio/cmd/twilio-pp-mcp@latest - Register with Claude Code:
claude mcp add twilio-pp-mcp -- twilio-pp-mcp - Verify:
claude mcp list
Direct Use
- Check if installed:
which twilio-pp-cliIf not found, offer to install (see Prerequisites at the top of this skill). - Match the user query to the best command from the Unique Capabilities and Command Reference above.
- Execute with the
--agentflag:twilio-pp-cli <command> [subcommand] [args] --agent - If ambiguous, drill into subcommand help:
twilio-pp-cli <command> --help.