CLI Reference | Cakemail Documentation

Pagination, filtering, error codes, and authentication details.

Authentication

The CLI resolves credentials in priority order:

CLI flags — --access-token, --email, --password
Environment variables — CAKEMAIL_ACCESS_TOKEN or CAKEMAIL_EMAIL + CAKEMAIL_PASSWORD
Config file — ~/.cakemail/config.json (saved after first auth)
Interactive prompt — asks for credentials if TTY is available

Tokens are cached and auto-refreshed. Passwords are never stored — only OAuth tokens.

Account switching

# Show current account
cakemail accounts get

# Switch to a sub-account
cakemail campaigns list --account-id 789

Pagination

All list commands support pagination:

# Basic pagination
cakemail campaigns list --page 2 --per-page 25

# Response metadata (JSON format)
# { "data": [...], "count": 25, "total": 247, "page": 2, "per_page": 25 }

Iterate all pages in a script

PAGE=1
while true; do
  RESPONSE=$(cakemail campaigns list --format json --batch --page $PAGE --per-page 100)
  COUNT=$(echo "$RESPONSE" | jq '.data | length')
  [ "$COUNT" -eq 0 ] && break
  echo "$RESPONSE" | jq '.data[]'
  PAGE=$((PAGE + 1))
done

Filtering and sorting

# Filter by field (== exact match)
cakemail campaigns list --filter "status==delivered"

# Multiple filters (AND logic, semicolon separated)
cakemail campaigns list --filter "status==delivered;name==Newsletter"

# Sort ascending (+) or descending (-)
cakemail campaigns list --sort "-created_on"

# Combined
cakemail campaigns list --filter "status==draft" --sort "+name" --per-page 10

Filterable fields

Resource	Fields
Campaigns	`status`, `name`, `created_on`, `scheduled_for`
Contacts	`status`, `email`, `subscribed_on`
Lists	`status`, `name`, `created_on`
Templates	`name`, `created_on`
Senders	`confirmed`, `email`, `name`

Error codes

The CLI maps API errors to actionable messages:

Code	Meaning	What to do
400	Invalid parameters	Check `--help` for correct syntax
401	Authentication failed	Run `cakemail config show` to check credentials
403	Permission denied	Verify account context with `--account-id`
404	Resource not found	List resources to find the correct ID
409	Conflict	Resource may already exist
422	Validation error	Check email format, date format (YYYY-MM-DD)
429	Rate limit	Add `sleep 1` between requests in scripts
500+	Server error	Retry after a moment

Exit codes

cakemail campaigns get 123
echo $?  # 0 = success, 1 = error

# Use in conditionals
if cakemail campaigns get 123 > /dev/null 2>&1; then
  echo "Campaign exists"
fi

Global flags

Flag	Description
`--format <json\|table\|compact>`	Output format
`--profile <developer\|marketer\|balanced>`	Override active profile
`--access-token <token>`	Override credentials
`--account-id <id>`	Target a sub-account
`--batch`	Disable all interactive features
`--help`	Show command help
`--version`	Show CLI version