# 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

```bash
# 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

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

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

### other package managers

```bash
# 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

```bash
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

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