customerio

name	customerio
description	Interact with the Customer.io App API via the cio CLI. Use this skill when the user wants to manage Customer.io resources such as customers, segments, campaigns, broadcasts, newsletters, collections, exports, messages, objects, webhooks, or transactional messages. Also use when the user asks to query, filter, create, update, or delete Customer.io data from the command line.

Customer.io CLI (cio)

A CLI tool wrapping the Customer.io App API.

Prerequisites

Before using this skill, ensure the cio CLI is installed and authenticated.

1. Install cio

Check if cio is available:

command -v cio || echo "NOT INSTALLED"

If not installed, install from GitHub Releases:

# 1) Inspect releases
gh release list -R Leechael/customerio-skills

# 2) Download latest artifacts
gh release download -R Leechael/customerio-skills --pattern 'cio-*.tar.gz'

# 3) Extract your platform artifact and install binary
tar -xzf cio-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz
install -m 0755 cio /usr/local/bin/cio

If /usr/local/bin is not writable, use ~/.local/bin (or another writable directory in $PATH).

2. Configure API Token

Run cio status to check authentication:

cio status

If the token is not configured, the user needs to set CUSTOMERIO_API_TOKEN:

export CUSTOMERIO_API_TOKEN="your-app-api-key"

Get an App API key from: https://fly.customer.io/settings/api_credentials

Recommended: use 1Password CLI to avoid storing secrets in shell config:

# Create a .env file referencing a 1Password secret
echo 'CUSTOMERIO_API_TOKEN=op://vault-name/Customer.io/api-token' > .env

# Run cio with the secret injected automatically
op run --env-file=.env -- cio status

This way the token is never written to disk in plaintext. See https://developer.1password.com/docs/service-accounts/use-with-1password-cli for setup.

Quick Reference

# Global flags
cio --region eu ...          # Use EU region (default: us)
cio ... --jq '.field'        # Filter JSON output with jq expression

# Status
cio status                                           # Check auth and connectivity

# Customers
cio customers ls                                     # List customers (POST with empty filter)
cio customers ls --body '{"ids":["u1","u2"]}'        # Filter by IDs
cio customers search --email [e-mail]        # Search by email
cio customers get <id>                               # Get attributes
cio customers activities <id>                        # Get activities
cio customers segments <id>                          # Get segments
cio customers messages <id>                          # Get messages

# Segments
cio segments ls                                      # List all segments
cio segments get <id>                                # Get segment details
cio segments create --body '{"segment":{"name":"VIP"}}'
cio segments rm <id>                                 # Delete segment
cio segments count <id>                              # Customer count
cio segments members <id>                            # Membership list

# Campaigns
cio campaigns ls                                     # List campaigns
cio campaigns get <id>                               # Get campaign
cio campaigns metrics <id>                           # Get metrics
cio campaigns actions <id>                           # List actions

# Broadcasts
cio broadcasts ls                                    # List broadcasts
cio broadcasts get <id>                              # Get broadcast
cio broadcasts trigger <id>                          # Trigger (optional filter body)
cio broadcasts metrics <id>                          # Get metrics

# Newsletters
cio newsletters ls                                   # List newsletters
cio newsletters get <id>                             # Get newsletter
cio newsletters metrics <id>                         # Get metrics

# Transactional
cio transactional ls                                 # List transactional messages
cio transactional get <id>                           # Get message
cio transactional deliveries <id>                    # Get deliveries

# Send messages
cio send email --body '{"to":"[e-mail]","transactional_message_id":"1",...}'
cio send push --body '...'
cio send sms --body '...'

# Collections
cio collections ls                                   # List collections
cio collections get <id>                             # Get collection
cio collections create --body '{"name":"n","data":[...]}'
cio collections update <id> --body '...'
cio collections content <id>                         # GET or PUT content

# Exports
cio exports ls                                       # List exports
cio exports create-customers                         # Export all customers
cio exports create-customers --body '{"filters":{...}}'
cio exports create-deliveries                        # Export all deliveries
cio exports get <id>                                 # Get export status
cio exports download <id>                            # Get download URL

# Objects
cio objects get <type> <id>                          # Get object
cio objects search                                   # Search objects

# Other resources
cio messages get <id>                                # Get message
cio messages deliveries <id>                         # Get deliveries
cio webhooks ls                                      # List webhooks
cio webhooks get <id>                                # GET or PUT webhook
cio webhooks create --body '...'                     # Create webhook
cio sender-identities ls                             # List sender identities
cio snippets ls                                      # List snippets
cio snippets upsert --body '...'                     # Create/update snippet
cio esp-suppression ls                               # List suppressions
cio esp-suppression search                           # Search (optional filter)
cio imports create --body '...'                      # Create import
cio info ip-addresses                                # Get IP addresses
cio workspaces ls                                    # List workspaces

Body Input

Commands that accept a body support two input methods:

# --body flag
cio segments create --body '{"segment":{"name":"Test"}}'

# Pipe via stdin
echo '{"segment":{"name":"Test"}}' | cio segments create

JQ Filtering

Use --jq to extract specific fields from any response:

cio segments ls --jq '.segments[].name'
cio customers get u1 --jq '.customer.email'
cio campaigns ls --jq '.campaigns | map(select(.active)) | length'