generated: '2026-08-13'
method: searched
source: >-
  https://docs.customer.io/ai/cli/get-started.md and
  https://docs.customer.io/ai/cli/reference.md
provider: Customer.io
providerId: customer-io
name: Customer.io CLI
binary: cio
description: >-
  An LLM-first command-line client for the Journeys App API and the CDP Data
  Pipelines API. Customer.io designed it for coding agents rather than humans:
  every command emits structured JSON, every endpoint is self-describing through
  `cio schema`, and the tool ships an installable Agent Skill (`cio skills
  install`) that teaches an assistant how to drive it. Customer.io's own docs
  recommend the CLI over the MCP server for terminal-based agents, because it
  reaches the full API surface without any MCP setup.
repository: https://github.com/customerio/cli
package: '@customerio/cli'
version: 0.0.20
released: '2026-07-23'
install:
- method: npm
  command: npm install -g @customerio/cli
- method: go
  command: go install github.com/customerio/cli@latest
- method: skills
  command: cio skills install
  note: >-
    Writes a bootstrap Agent Skill globally or into the current project; the
    remaining skills are served on demand so they stay current with Customer.io.
authentication:
  credential: service account token
  prefix: sa_live_
  create_at: https://fly.customer.io/settings/api_credentials?keyType=service_accounts
  exchange: >-
    The CLI trades the sa_live_ token for a short-lived JWT and refreshes it
    automatically.
  resolution_order:
  - --token flag
  - CIO_TOKEN environment variable
  - ~/.cio/config.json (written by `cio auth login`)
  commands:
  - cio auth login
  - echo "$CIO_TOKEN" | cio auth login --with-token
  - cio auth status
  token_types:
  - name: User service account
    note: >-
      Tied to a person; inherits that person's role. May be marked read-only at
      creation, permanently restricting it to GET.
  - name: System service account
    note: >-
      Not tied to a person; assigned a role that applies across every workspace
      in the account.
command_groups:
- group: auth
  commands:
  - cio auth login
  - cio auth login --with-token
  - cio auth status
  purpose: Sign in with a service account token and inspect session state.
- group: skills
  commands:
  - cio skills install
  - cio skills list
  - cio skills read <skill_name>
  purpose: >-
    Install and read Customer.io-maintained agent skills — the multi-step
    workflow instructions an assistant follows before calling the API.
- group: schema
  commands:
  - cio schema
  - cio schema <resource>
  - cio schema <resource>.<endpoint>
  purpose: >-
    Discover the API without leaving the terminal. `cio schema` lists resources,
    `cio schema campaigns` lists that resource's endpoints, and `cio schema
    campaigns.list` returns the full endpoint definition.
- group: api
  commands:
  - cio api <path> --params '{...}'
  - cio api <path> --json '{...}'
  - cio api <path> -X DELETE
  purpose: >-
    Call any endpoint. Defaults to GET; passing --json infers POST. Path
    placeholders are filled from --params.
key_flows:
- name: Agent onboarding
  steps:
  - npm install -g @customerio/cli
  - cio skills install
  - open the coding assistant in the project and prompt it in natural language
  note: >-
    Customer.io ships sub-skills for full account onboarding and SDK
    integration, so the same entry point covers signup, domain setup, sending a
    first email, and wiring an SDK into application code.
- name: Safe write
  steps:
  - cio schema <resource>.<endpoint>
  - cio api ... --json '{...}' --dry-run
  - cio api ... --json '{...}'
  note: >-
    --dry-run resolves and validates the URL, method and body locally without
    executing, which is how an agent catches a missing path parameter before it
    becomes a 4xx.
flags:
- flag: --token
  env: CIO_TOKEN
  description: Service account token override.
- flag: -X, --method
  description: HTTP method override.
- flag: --json
  description: JSON request body, or @filename.
- flag: --params
  description: Path and query parameters as JSON.
- flag: --jq
  description: jq expression applied to the response.
- flag: --dry-run
  description: Preview the resolved request without executing it.
- flag: --page
  description: Page number.
- flag: --limit
  description: Page size.
- flag: --page-all
  description: Auto-paginate; emits NDJSON, one JSON object per line.
- flag: --timeout
  env: CIO_TIMEOUT
  description: Request timeout. Default 30s.
exit_codes:
- code: 0
  meaning: Success
- code: 1
  meaning: General error
- code: 2
  meaning: Validation or input error
- code: 3
  meaning: Authentication error
- code: 4
  meaning: Authorization error
- code: 5
  meaning: API error (4xx/5xx)
docs:
  get_started: https://docs.customer.io/ai/cli/get-started/
  reference: https://docs.customer.io/ai/cli/reference/
  service_accounts: https://docs.customer.io/ai/cli/service-accounts/
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com