Get started with the Customer.io CLI

Updated

The Customer.io CLI gives AI agents and automation tools programmatic access to your workspaces. Install our skill, point an AI assistant at it, and let it drive.

How it works

The Customer.io CLI is a command-line tool that gives AI agents and scripts full access to your Customer.io workspaces. It covers the Journeys UI API and CDP Data Pipelines API through a single cio api command—no per-endpoint code, no SDK boilerplate.

The CLI is an LLM-first tool. Every command returns structured JSON, every endpoint is self-describing via cio schema, and the interface is designed for predictability over interactivity. You can give it to an AI coding assistant—Claude Code, Codex, or similar—and write natural language prompts to do things in Customer.io.

 Make sure you trust your AI tools

The Customer.io CLI works with your AI provider of choice. While our LLM subprocessors don’t store this data, the AI providers you use might. Make sure that you use AI tools that are approved by your organization to ensure the safety of your—and your customers’—data.

Get started with an AI coding assistant

The fastest path is to install our skill—a set of instructions that teaches your AI assistant how to drive the CLI. The skill handles installing the CLI itself, signing in (or signing up), and using the right commands for the task at hand.

  1. Add the skill to your project:

    npx skills add customerio/cli

  2. Open your AI coding assistant in the project (Claude Code, Cursor, Windsurf, Codex, etc.).

  3. Prompt it for any Customer.io task—for example:

    • “Set up Customer.io for my React Native app”
    • “List the active campaigns in my workspace”
    • “Create a new Customer.io account” (the skill walks through signup end-to-end)
    • “Find people who haven’t opened an email in 30 days and create a win-back segment”

The skill detects whether the CLI is installed, walks you through installation and authentication, and then runs the work. It also includes sub-skills for full account onboarding and SDK integration—so the same entry point covers signup, domain setup, sending your first email, and wiring SDKs into your code.

 No skill support? Use cio prime instead

If your AI tool doesn’t support skills, follow the manual install below, then run cio prime and paste the output into your agent’s context. That gives it the full CLI reference in a single block.

Manual install

You can also install and use the CLI directly in your terminal. Use this path if you want to script the CLI in CI/CD, run it without an AI assistant, or your tool doesn’t support skills.

Install

Install with npm:

npm install -g @customerio/cli

Or with Go:

go install github.com/customerio/cli@latest

After installation, the cio command is available in your terminal.

Authenticate

The CLI uses service account tokens (sa_live_...) for authentication. If you don’t have a token yet, create one in your Customer.io account:

  1. Go to Account Settings > API Credentials and click the Service Accounts tab.

  2. Click Create Service Account, give it a name, and click Create.

  3. Click Create Token:

    • Enter a name for the token
    • Choose an expiration
    • Optionally, check Read-only to permanently restrict the token to GET requests.
    • Click Create

  4. Copy the sa_live_ token. You’ll need it for the next step and it’s only shown once.

  5. Log in to the CLI with your token. The CLI handles the OAuth token exchange automatically—you just paste your token.

    # Interactive login — paste your sa_live_ token when prompted
cio auth login

# Non-interactive (for CI/CD pipelines and scripts)
echo "$CIO_TOKEN" | cio auth login --with-token

# Verify your authentication
cio auth status

     Set CIO_TOKEN from a secret store, not from your shell config. See Store tokens securely for recommendations by use case.

Token resolution order

The CLI checks for credentials in this order:

  1. --token flag (highest priority)
  2. CIO_TOKEN environment variable
  3. ~/.cio/config.json file (set by cio auth login)

What you can ask your agent to do

Once your agent has the skill (or the cio prime reference), you can prompt it with natural language:

  • List all active campaigns in my workspace
  • Create a segment of users who signed up in the last 7 days
  • Show me the delivery metrics for my onboarding campaign
  • Set up a new CDP source for my React Native app
  • Find people who haven’t opened an email in 30 days and create a win-back segment

Your agent will translate these into the appropriate cio schema lookups and cio api calls. The CLI handles pagination, error recovery, and multi-step workflows automatically.

Copied to clipboard!
  Contents