This page is part of the Customer.io documentation. For the complete documentation index, see llms.txt.

10

Get started with the Customer.io CLI

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.

Get started with an AI coding assistant

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

1. Install the CLI:

   # With npm
   npm install -g @customerio/cli
   
   # With Go
   go install github.com/customerio/cli@latest
   

2. Install skills:

   cio skills install
   

   cio skills install prompts you to install globally (for every project) or into the current project. This writes a bootstrap skill to the location you select; the rest of the skills are served on demand so they stay current with Customer.io’s capabilities.

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

4. Prompt it to complete tasks in Customer.io:

   • “Set up Customer.io for my React Native app”
   • “List the active campaigns in my workspace”
   • “Find people who haven’t opened an email in 30 days and create a win-back segment”

Then your agent can use the CLI to do the things you can do in Customer.io. The CLI 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.

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 Description.
   • Determine whether the account is a User service account or a System service account. User-based service accounts are tied to a person and get their permissions from that person’s role. System-based service accounts are not tied to a person; you’ll assign them a role to determine what they can do. See Service accounts for more information.

3. Click Create Token. The settings for the token change a bit based on the service account type:

   • Enter a name for the token
   • Choose an expiration
   • User token only: check Read-only to permanently restrict the token to GET requests.
   • System token only: select a Role from the dropdown. The token gets that role’s permissions for all workspaces in the account.

4. Click Create

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

6. Log in to the CLI with your token. The CLI exchanges your token for a short-lived JWT automatically and refreshes it as needed.

   # 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.

Troubleshoot a conversation

If you’re experiencing issues with authentication, malformed requests, or incorrect endpoints, check the following items to troubleshoot the problem before you escalate to our support team:

• Confirm authentication with cio auth status. An expired or read-only token causes most permission and 401 errors.

• Re-run the failing command with --dry-run to see the resolved URL, method, and body. A request that fails --dry-run has a problem the CLI can see locally, like a missing path parameter or a bad body.

• Confirm the endpoint exists with cio schema.

• Read the exit code to tell an authentication/credential problem (3, 4) from a Customer.io server-side problem (5).

   Feed the exit code back into the conversation

  If the assistant repeats the same failed call, paste the exact error and exit code back into the conversation and ask it to read the relevant cio schema before trying again. That can break your agent out of a loop.

Share a conversation with support

Customer.io doesn’t keep transcripts of CLI sessions, so your conversation history with your coding agent stays with your coding agent. To help our support team troubleshoot issues, you’ll need to export and share your conversation history with your coding agent.

• Claude Code: run /export <file> to write the conversation to a file (or /export alone to copy it to your clipboard). For full fidelity, the raw session is stored as JSONL under ~/.claude/projects/<project>/<session-id>.jsonl.
• Cursor, Windsurf, and others: export or copy the conversation from the chat panel.
• Any tool: record the terminal with script -q cio-session.log, reproduce the problem, then exit. This captures every command and its output regardless of which assistant you use.

When you contact support you should include:

• the prompt you gave your agent
• the redacted transcript
• your environment details—the agent and version, your operating system, the workspace or environment ID, and the CLI version (cio --version)