/affinity-help

Show a quick reference for using the xaffinity CLI.

IMPORTANT: Read-Only by Default

Always use --readonly unless the user explicitly approves data modification. CRM data is sensitive!

CLI Quick Start

First: Run xaffinity config check-key --json to get the CLI pattern, then use it for all commands.

# Standard pattern for queries
xaffinity --readonly person search "John Smith" --json
xaffinity --readonly person get 123 --json
xaffinity --readonly company get domain:acme.com --json

# Export to CSV (no --json needed)
xaffinity --readonly person ls --all --csv people.csv --csv-bom

# Export list with associations
xaffinity --readonly list export LIST_ID --expand people --all --csv output.csv

# Parse JSON with jq
xaffinity --readonly person ls --json --all | jq '.data.persons[]'

Key Gotchas

1. Always use --json: For structured, parseable output
2. Always use --readonly: Only allow writes when user explicitly approves
3. Use the pattern from check-key: Run xaffinity config check-key --json and use the pattern field for all commands
4. --all can be slow: Exports with --all paginate through entire dataset - may take minutes for large CRMs
5. list export --filter is client-side: Fetches ALL data then filters locally (slow). Use --saved-view instead for large lists
6. Filters only work on custom fields - not type, name, domain, etc.
7. Check --help: Never guess command options

Common Commands

More Info

• CLI help: xaffinity --help
• Command help: xaffinity <command> --help (e.g., xaffinity person --help)
• SDK docs: https://yaniv-golan.github.io/affinity-sdk/latest/