Every Customer.io action a marketer or ops engineer takes — campaigns, broadcasts, segments, deliveries, exports, suppressions, Reverse-ETL — wrapped in named verbs, backed by a local SQLite cache, and served through a bundled MCP server.
The official customerio/cli exposes the API as raw passthrough. This CLI gives you typed commands for every meaningful workflow, plus eight commands no other tool has — journey funnels cross-cut by segment, multi-segment overlap, customer 360 timelines, broadcast pre-flight, suppression audit trails, Reverse-ETL health, bulk suppress with provenance, and incident-ready delivery triage bundles. It is also the only Customer.io tool that ships an MCP server.
Authentication
Customer.io uses Service Account tokens (sa_live_* prefix). The CLI exchanges the token for a short-lived JWT via the OAuth client-credentials endpoint at https://us.fly.customer.io/v1/service_accounts/oauth/token (or eu.fly.customer.io for EU workspaces) and uses the JWT as the Bearer for both the Journeys UI API (/v1/...) and the CDP control plane (/cdp/api/...). Run customer-io auth login --sa-token $CIO_TOKEN --region us once; the cached JWT auto-refreshes. The Track API (separate Site ID + API Key auth) is intentionally out of scope for v1 — the SA token is the unified credential.
Quick Start
# One-time SA token exchange; the JWT is cached and refreshed automatically.
customer-io auth login --sa-token $CIO_TOKEN --region us
# Confirms token, region, account_id, and which workspaces are reachable.
customer-io doctor
# Populate the local SQLite cache so SQL/search/funnel/timeline work offline.
customer-io sync --resources customers,segments,deliveries --since 30d
# Smoke-test: list campaigns and pluck just the fields you need.
customer-io campaigns list --json --select id,name,state,created_at
# Run pre-flight before any broadcast — the 1 req / 10 s throttle is unforgiving.
customer-io broadcasts preflight bcr_77 --segment seg_19
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
campaigns funnel — Render a step-by-step journey funnel (sent → delivered → opened → clicked → converted) for one campaign, optionally cross-cut by segment.
Reach for this when an agent is asked 'what fraction of segment X completed journey Y' — the answer is one query against synced data, not two exports and a spreadsheet.
customer-io campaigns funnel cmp_482 --segment seg_19 --since 30d --json
-
segments overlap — Compute pairwise and multi-way Venn diagrams of segment memberships from the local store.
Use when validating audience design — 'are my churned-risk and high-value segments overlapping?' — without exporting twice.
customer-io segments overlap seg_19 seg_42 seg_88 --json
-
customers timeline — Chronological per-customer event stream merging identifies, deliveries, suppressions, and segment-membership events from the local store.
Reach for this on incident triage or 'did the welcome SMS go out to this user?' — one command instead of a UI scroll-fest.
customer-io customers timeline alice@example.com --since 30d --json
Send-time safety
-
broadcasts preflight — Before triggering a broadcast, check target segment size, suppression overlap, and last-sent recency from the local deliveries cache; emit a green/yellow/red verdict with structured reasons.
Use before any broadcast to avoid double-sending, accidental over-mailing, or 429 storms.
customer-io broadcasts preflight 123457 bcr_77 --segment seg_19 --json
-
suppressions audit — Attribute every suppression in a window to the triggering bounce or complaint delivery (or 'manual' if no preceding event).
Use when an ops engineer needs to explain why a customer is suppressed, or when auditing complaint-driven churn.
customer-io suppressions audit --since 30d --reason bounce --json
-
cdp-reverse-etl health — Named verb over Reverse-ETL run history with status, row counts, error reasons, and an optional --watch poll mode.
Use as the daily standup question 'are warehouse syncs healthy?' — replaces three separate api calls + jq filters.
customer-io cdp-reverse-etl health --since 24h --watch
Audit and provenance
-
suppressions bulk add — Read a CSV or JSONL of email/customer-id, fan out real suppress calls with adaptive throttle, append every call to a local JSONL audit log keyed by date.
Use for compliance-driven bulk actions where you need to defend later 'who got suppressed when, by whom, with what status code'.
customer-io suppressions bulk add --from-csv complaints.csv --reason complaint --dry-run
-
deliveries triage — Filter live + local deliveries by template + status + window, write a self-contained bundle (summary.md with SQL group-by error reasons, deliveries.jsonl, recipients.txt) ready to paste into an incident doc.
Pipe the bundle into Claude or a Notion doc for one-shot incident handoff; replaces 30+ minutes of UI scrolling.
customer-io deliveries triage --template tx_91 --status bounced --since 1h --bundle ./incident-2026-05-07
Usage
Run customer-io-pp-cli --help for the full command reference and flag list.
Commands
broadcasts
List, inspect, and trigger one-off broadcasts (1 req / 10 s rate-limited)
customer-io-pp-cli broadcasts get - Get one broadcastcustomer-io-pp-cli broadcasts list - List broadcasts in an environmentcustomer-io-pp-cli broadcasts metrics - Read metrics for one broadcastcustomer-io-pp-cli broadcasts trigger - Trigger a broadcast (rate-limited to 1 req / 10 s)
campaigns
List campaigns and read campaign + journey metrics
customer-io-pp-cli campaigns get - Get one campaigncustomer-io-pp-cli campaigns journey_metrics - Read step-by-step journey funnel metricscustomer-io-pp-cli campaigns list - List campaigns in an environmentcustomer-io-pp-cli campaigns metrics - Read aggregate metrics for a campaign
cdp_destinations
List CDP destinations (Premium feature)
customer-io-pp-cli cdp_destinations list - List CDP destinations
cdp_reverse_etl
List Reverse-ETL syncs (Premium feature)
customer-io-pp-cli cdp_reverse_etl list - List Reverse-ETL syncs
cdp_sources
List CDP data sources (Premium feature)
customer-io-pp-cli cdp_sources list - List CDP sources
customers
Manage Customer.io customer profiles within an environment (workspace)
customer-io-pp-cli customers get - Get a customer's attributescustomer-io-pp-cli customers list_activities - List activity events for a customercustomer-io-pp-cli customers list_messages - List messages sent to a customercustomer-io-pp-cli customers list_segments - List the segments a customer belongs to
deliveries
Inspect delivery events (sends, opens, clicks, bounces, complaints)
customer-io-pp-cli deliveries get - Get one deliverycustomer-io-pp-cli deliveries list - List recent deliveries
exports
Start, monitor, and download data exports (segment members, deliveries, customers, etc.)
customer-io-pp-cli exports download - Get the signed download URL for a finished exportcustomer-io-pp-cli exports get - Get the status of an exportcustomer-io-pp-cli exports list - List recent exports
segments
List segments and inspect segment membership
customer-io-pp-cli segments customer_count - Get the customer count for a segmentcustomer-io-pp-cli segments get - Get one segmentcustomer-io-pp-cli segments list - List segments in an environmentcustomer-io-pp-cli segments members - List customer IDs in a segment
suppressions
Suppress and unsuppress customers; the official audit surface for compliance actions
customer-io-pp-cli suppressions add - Suppress a customercustomer-io-pp-cli suppressions count - Get the count of suppressed customers in an environment (Customer.io has no list endpoint; use 'exports email_suppressions' for the full list)customer-io-pp-cli suppressions remove - Remove a suppression
transactional
Inspect transactional templates and metrics
customer-io-pp-cli transactional get_template - Get one transactional templatecustomer-io-pp-cli transactional list_templates - List transactional templatescustomer-io-pp-cli transactional template_metrics - Read metrics for one transactional template
webhooks
Manage Reporting Webhooks for delivery + engagement events
customer-io-pp-cli webhooks get - Get one Reporting Webhookcustomer-io-pp-cli webhooks list - List Reporting Webhooks
workspaces
List the environments (workspaces) visible to the Service Account
customer-io-pp-cli workspaces account - Get the current account detailscustomer-io-pp-cli workspaces list - Read the current account, including environment_ids visible to the SA token
Output Formats
# Human-readable table (default in terminal, JSON when piped)
customer-io-pp-cli broadcasts list mock-value
# JSON for scripting and agents
customer-io-pp-cli broadcasts list mock-value --json
# Filter to specific fields
customer-io-pp-cli broadcasts list mock-value --json --select id,name,status
# Dry run — show the request without sending
customer-io-pp-cli broadcasts list mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
customer-io-pp-cli broadcasts list mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
customer-io-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/customer-io-pp-cli/config.toml
Environment variables:
| Name | Kind | Required | Description |
|---|
CUSTOMERIO_TOKEN | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
customer-io-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $CUSTOMERIO_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 Unauthorized on every call — Run
customer-io auth status; if the JWT is expired, re-run customer-io auth login --sa-token $CIO_TOKEN --region <us|eu>. SA tokens themselves are long-lived; only the minted JWT expires.
- Calls go to the wrong region — Pass
--region eu (or set CUSTOMERIO_REGION=eu) — both the JWT exchange and the API calls must target the same region.
- 429 Too Many Requests on broadcast trigger — Broadcast triggers are limited to 1 request per 10 seconds. Use
customer-io broadcasts preflight first; the trigger command itself adapts to the limit. Don't wrap it in retry-without-backoff loops.
segments members or customers timeline returns empty — Run customer-io sync --resources segment_members,deliveries first. Some commands read from the local store rather than the live API.- Reverse-ETL endpoints return 403 — Reverse-ETL is a Premium-tier feature; the endpoint is reachable but returns 403 on Essentials accounts. List the workspaces visible to your Service Account with
customer-io-pp-cli workspaces.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press