cosdk CLI — Cordial from your terminal

The Cordial CLI. For agents and humans.

One npm install wraps the whole platform — audiences, messages, orchestrations, content, analytics — in commands that compose cleanly. JSON output by default, so it pipes straight into your scripts, your CI, and your agents.

five-minute tour

# 1. Sign in (OAuth in your browser)
cosdk login
✓ Logged in as alex@brand.com (acme-prod)

# 2. Confirm scopes
cosdk whoami
  user:     alex@brand.com
  account:  acme-prod
  scopes:   read, write, profile

# 3. Look around
cosdk audiences list --query "loyalty"
ID         NAME                       COUNT
aud_3d70   Loyalty tier 3+            198,455
aud_5e21   Loyalty signups · 7d        12,083

# 4. Drill into a message
cosdk messages info msg_2025_blackfriday
  status:   sent
  sent_at:  2025-11-29 09:00 PST
  reach:    1,284,902
  CTR:      4.3%   ↑ +0.7pp vs L30

# 5. Pipe analytics into your tooling
cosdk analytics overview --start 1y --compare --json | jq '.channels'

Distribution

npm · cosdk

Platforms

darwin · linux · win

Coverage

Whole platform

Default output

--json ready

Install

One command, any platform.

Install from npm, run cosdk login, and you're connected. Works anywhere Node.js runs — macOS, Linux, Windows.

npm

# Install the CLI globally from npm
npm install -g @cordialexperience/cosdk

# Verify the install, then sign in
cosdk --version
cosdk login

other package managers

# Prefer another package manager? All of these work:
pnpm add -g @cordialexperience/cosdk
yarn global add @cordialexperience/cosdk
bun add -g @cordialexperience/cosdk

# Or run it once, without installing:
npx @cordialexperience/cosdk whoami

Requirements

Node.js 18 or newer. The CLI ships as a single npm package — nothing to download, no binary to put on your PATH.

Shell completions

source <(cosdk completion zsh)
source <(cosdk completion bash)
cosdk completion fish > ~/.config/fish/completions/cosdk.fish

Commands

One namespace per concept.

Every command takes the same flags. Pipe --json straight into jq, your scripts, or your agents.

Auth

OAuth2 browser login, with auto-refresh of saved tokens.

cosdk login OAuth2 browser login
cosdk whoami Current user, account, scopes
cosdk whoami --token Print fresh access token
cosdk logout Remove saved credentials

Analytics

Account overview, trends, ad-hoc and saved reports.

cosdk analytics overview Last 30 days, all channels
cosdk analytics overview --start 1y --compare 1 year vs prior period
cosdk analytics audiences --period 7 7-day audience trends
cosdk analytics reports adhoc --channel email Ad-hoc report
cosdk analytics reports run <id> Execute a saved report

Messages

Inspect batch and automated messages and their content.

cosdk messages list --type batch --status sent Filter by type/status
cosdk messages info <message-id> Message dashboard
cosdk messages sends <template-id> Child sends of an automation
cosdk messages preview <message-id> Render a preview
cosdk messages preview <id> --open-raw Open preview in browser

Contacts

Search contacts and inspect attributes, events, and orders.

cosdk contacts search jane Search by ID or email
cosdk contacts info <contact-id> --detailed Profile with attribute types
cosdk contacts attributes List attribute definitions
cosdk contacts events <contact-id> Activity timeline
cosdk contacts orders list <contact-id> Purchase history

Audiences

List saved audiences, translate criteria, and count contacts.

cosdk audiences list --query test Search saved audiences
cosdk audiences info <id> --count Detail with current count
cosdk audiences translate '<criteria-json>' Criteria → human text
cosdk audiences query-count '<criteria-json>' Count matching contacts
cat q.json | cosdk audiences translate Read criteria from stdin

Content

HTML includes and image assets — full CRUD.

cosdk includes list --query header Search HTML includes
cosdk includes create <key> --name 'Promo' Create an include
cosdk images list --query hero --sort name Search images
cosdk images upload ./hero.png --tags banner Upload with tags
cosdk images tags <id> add new-tag Tag an image

Orchestrations

Inspect journey orchestrations including DAG visualization.

cosdk orchestrations list --query welcome Find an orchestration
cosdk orchestrations info <id> Detail with DAG tree
cosdk orchestrations info <id> --mermaid Mermaid flowchart
cosdk orchestrations info <id> --published Show published version

Data

Recurring data automations and one-off batch jobs.

cosdk data automations list Recurring/triggered automations
cosdk data automations info <id> Automation detail
cosdk data batches list Batch import/export jobs
cosdk data batches info <id> Batch job stats

Jobs

Track background processing across the platform.

cosdk jobs list --status Failed Failed jobs only
cosdk jobs list --type ImportContacts Filter by job type
cosdk jobs info <job-id> Job detail

Supplements / Products / Tags

Browse the supporting data model.

cosdk supplements list --contact-linked Tables linked to contacts
cosdk supplements records <key> Browse table records
cosdk products list --query jacket Search products
cosdk tags info <name> Tag details and asset counts

Other

Account info and semantic search across artifacts.

cosdk account info Account info, timezone, features
cosdk artifacts search audience 'high intent' Semantic search
cosdk skill Install agent skills

Global flags

Same flags. Everywhere.

Every command supports the same handful of flags: --json for machine-readable output, --yes to skip write confirmations for automation, --verbose to dump HTTP traffic, and --tracing to capture OpenTelemetry spans.

--json Compact JSON output for piping into jq, scripts, agents
--yes / -y Skip write confirmation prompts (for automation)
--verbose / -V Print HTTP requests and responses to stderr
--tracing / -T Collect OpenTelemetry spans for the run
--help Per-command help with examples

piping into jq

# Top 5 audiences by current count
cosdk audiences list --json \
  | jq -r '.audiences | sort_by(-.count) | .[:5] | .[] | "\(.count)\t\(.name)"'

# Save a CSV of message performance for the last quarter
cosdk analytics reports adhoc --channel email \
  --start 90 --json > q4-email.json

# Translate raw audience criteria into human language
echo '{"and":[{"channels":{"email":{"in":true}}}]}' \
  | cosdk audiences translate

Safety

Write actions confirm before they fire.

Read by default

Read calls always succeed without prompting. Write operations halt before the network call and ask for confirmation.

--yes for automation

When you're running in CI or an agent loop, pass --yes to skip prompts. The CLI remembers your choice for the session.

Scoped to your login

Every command runs against the one account you signed in to — nothing reaches another tenant, and switching accounts means an explicit cosdk login.

Install the CLI.

Installs from npm in seconds — macOS, Linux, Windows. Sign in the first time you run it.