Cordial Cordial
Talk to sales
cosdk CLI · install from npm

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.

Install → Browse commands
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 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 cosdk
yarn global add cosdk
bun add -g cosdk

# Or run it once, without installing:
npx 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 login --env stg Login to staging
  • 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.

  1. 1

    Read by default

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

  2. 2

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

  3. 3

    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.

Install → Or call the REST API directly