xaffinity CLI Usage

REQUIRED FIRST STEP: Verify API Key

Before anything else, run:

xaffinity config check-key --json

• `command not found` (exit 127; e.g. a Claude Cowork VM) — install it once per task:

pip install --user -q --no-warn-script-location "affinity-sdk[cli]==2.0.6" (about 10s), then start every later bash call with export PATH="$HOME/.local/bin:$PATH"; (each call is a fresh shell) and run check-key again. Details and the no-network case: references/setup.md (Claude Cowork).

• `"configured": true` — use the pattern field from the output for ALL subsequent commands:

copy its flags (--dotenv, and --env-file <path> when it names one) into every command.

• `"configured": false` — stop and help the user set up. Read references/setup.md (key

resolution order, xaffinity config setup-key — interactive, the user must run it — and the Cowork key-in-a-connected-folder setup, which needs --env-file with the folder's path).

Read JSON from the right key

--json emits one JSON object (not NDJSON): {"ok", "data", "warnings", "meta", ...}. The shape of data differs by command — reading the wrong key gives null, which looks like real "empty" data. Use this table:

When in doubt, look before you extract: ... --json | jq '.data | if type == "object" then keys else "array of \(length)" end'.

`null` / missing does not mean empty. A plain company get / person get / opportunity get is a cheap lookup that fetches no field values and no list entries: fields: {"requested": false} and a missing listEntries key mean not fetched. meta.notRequested names what was skipped and the flag that fetches it. Never tell the user a record "has no lists" or "empty fields" — and never offer to write values — without having fetched them.

Common pitfalls (READ THIS FIRST)

1. Never redirect stderr to `/dev/null`. Every CLI safety signal — "results truncated", "unknown option", "Filtering locally after fetching every entry" — lives on stderr. Dropping stderr is how you ship a silent-zero-match result and call it a duplicate check.

2. `--filter` goes through Affinity's search. On list export, company ls and person ls, the conditions on fields that Affinity can answer are applied on its side and the whole filter is checked again locally. When part of it runs locally, --all, --max-results (or, on list export, --first-page-only) is required; the error's details.local names those conditions. company ls / person ls --filter need a condition on a company/person field (names: --query). Details: references/filtering.md.

3. Duplicate checks: use `--company-id` / `--person-id`, not `--filter`. xaffinity list export "Pipeline" --company-id 555 --json returns 0 or more rows for that exact company, with its list field values. Zero rows + the emitted warning is the "not on list" signal.

4. Check `meta.truncated` on every JSON response. If true, the answer is incomplete; meta.truncationReason names the cause (firstPageOnly, or partialFailure from field history-bulk). Separately, Affinity returns at most 100 values per multi-value field: a warnings entry like "Field 'X' … shows 100 of 250 values" means that field's list is partial, so don't count or dedupe from it.

5. Side-effecting commands: capture, then parse. A pipeline like xaffinity note create --content "..." --company-id 123 | python3 -c "json.loads(...)" runs the create first, then parses. If you forgot --json, the parser crashes and the pipeline exits 1 — but the note was already created, and a "retry" creates a duplicate. Capture first:

out=$(xaffinity --json note create --content "..." --company-id 123)
note_id=$(printf '%s' "$out" | jq -r '.data.note.id')

The CLI also warns on stderr when identical content from the same author arrives within 5 minutes, but that's a safety net — capture-then-parse is the fix.

6. Person/company field values require numeric IDs, not names. xaffinity list entry field "Pipeline" 999 --set Owner "Jane Doe" aborts with an "Invalid entity ID" error before any write. Resolve names to IDs first, and check the ID is not null:

owner_id=$(xaffinity --readonly --json person ls --query "Jane Doe" --max-results 5 \
  | jq -r '.data.persons[0].id')
[ "$owner_id" != "null" ] || { echo "no match for Jane Doe" >&2; exit 1; }
xaffinity list entry field "Pipeline" 999 --set Owner "$owner_id"

Every --set value is validated before any API call, so one bad value (e.g. a wrong person ID) means nothing is written. The CLI does not resolve names for you.

Reading One Company's / Person's Lists and List Fields

# Which lists is this company on, with each entry's list fields (Status, Owner, ...)
xaffinity --readonly company get 314557093 --expand list-entries --json | jq '.data.listEntries'

# Only one list (--list implies --expand list-entries)
xaffinity --readonly company get 314557093 --list "Dealflow" --json | jq '.data.listEntries'

# Rows for that company on a known list (same values, list-export row shape)
xaffinity --readonly list export "Dealflow" --company-id 314557093 --json | jq '.data.rows'

Read .data.listEntries, not .data.company.listEntries.

IMPORTANT: Write Operations Require Explicit User Request

Always use `--readonly` unless the user explicitly requests writes. Writes include creating, updating, or deleting notes, interactions, reminders, list entries, field values, persons, companies and opportunities. Before writing over an existing field value, read it first and show the user the current value. Write-side gotchas (duplicate refusal on create, read-only and ambiguous fields, global companies, file uploads): references/files-and-writes.md.

Destructive Commands Require Double Confirmation

Before executing ANY command that cannot be undone (delete, merge):

1. Look up the entity first to show the user what will be deleted
2. Ask the user in your response, showing the entity details and requesting confirmation
3. Wait for the user's next message — do NOT proceed until they explicitly confirm
4. Only after the user confirms, run the command with --yes

User: "Delete person 123"
You: xaffinity --readonly person get 123 --json
You: "This will permanently delete John Smith (ID: 123, email: [email protected]).
      Type 'yes' to confirm deletion."
[Stop here and wait for user's response]

User: "yes"
You: xaffinity person delete 123 --yes

Destructive commands: person delete, company delete, opportunity delete, note delete, reminder delete, field delete, list entry delete, interaction delete, person merge, company merge (the duplicate record is removed), field options delete (clears that value on every entry that had it)

The --yes flag bypasses the CLI's interactive prompt; the confirmation must come from the user in the conversation. Without --yes and with nothing answering the prompt, these commands fail with a usage error (exit 2) and change nothing.

Critical Patterns

Always limit results. Use --max-results on every ls, list export, interaction ls, and note ls. Start small (10-50), increase only if needed — unbounded queries can return hundreds of KB and make many API calls.

Extract only what you need with jq once you know the shape (see the table above):

# A person's ID for a follow-up command
xaffinity --readonly person get email:[email protected] --json | jq -r '.data.person.id'

# Just the fields you need to answer the user
xaffinity --readonly person get 123 --json \
  | jq '.data.person | {id, firstName, lastName, primaryEmailAddress}'

# Entity names from a list export
xaffinity --readonly list export "Pipeline" --max-results 20 --json \
  | jq '[.data.rows[] | {entityName, entityId}]'

Multi-Source Tasks: Use a Script

When a task needs data from 2 or more CLI commands (e.g., person details + interactions + list entries), write a single bash script that prints only the summary, instead of running commands one by one — each separate command dumps its full JSON into the conversation. A single command is fine for simple lookups, single writes and quick searches. Worked example (company → interactions summary): references/interactions.md.

For complex joins across 3+ sources, conditional logic, pagination over large datasets, or SDK features like F filters or FieldResolver, write a Python script using the Affinity SDK (the SDK skill has patterns).

Selectors: Use Names, Not Just IDs

Most commands accept names, emails, or domains directly — no ID lookup needed:

xaffinity --readonly person get email:[email protected] --json
xaffinity --readonly company get domain:acme.com --json
xaffinity --readonly list export "My Pipeline" --max-results 20 --json
xaffinity --readonly person get 12345 --json      # IDs also work

Common Commands

# Search entities (always limit results)
xaffinity --readonly person ls --query "John Smith" --max-results 10 --json
xaffinity --readonly company ls --query "Acme" --max-results 10 --json

# Lists by name (case-insensitive substring); entries of one list
xaffinity --readonly list ls --query "pipeline" --json
xaffinity --readonly list export "Pipeline" --max-results 20 --json

# Export to CSV
xaffinity --readonly person ls --all --csv --csv-bom > contacts.csv
xaffinity --readonly list export "Pipeline" --all --csv --csv-bom > output.csv

Searching and filtering (--query vs --filter, saved views, operators): references/filtering.md. Content search (max 100, no paging): note search "text", file search "text" (inside files), company search "description" (semantic; for name/domain use company ls --query). Interactions (types, date ranges, creating them): references/interactions.md. Field change history, org-wide feeds (interaction feed, note feed), transcripts, relationships, merge history and dropdown options: references/history-and-activity.md.

List Entry Fields

# Read specific fields (resolved person/company objects, matching list export format)
xaffinity --readonly list entry field "Pipeline" 12345 --get Owner --get Status --json

# Set a field value (requires write permission)
xaffinity list entry field "Pipeline" 12345 --set Status "Active"

--get and --set are mutually exclusive. --get returns resolved objects for person/company reference fields (firstName, lastName, primaryEmailAddress) and full dropdown option data (text, color).

Expand/Include (N+1 Warning)

--expand on list export triggers one additional API call per record. Use --max-results to control cost.

# Safe: 20 records = ~21 API calls
xaffinity --readonly list export "Pipeline" --expand persons --max-results 20 --json

# DANGEROUS: --expand with --all on a large list (500 entries = 501+ API calls, ~10 minutes)
# xaffinity list export "Pipeline" --expand persons --all  # DON'T do this blindly

Practical limits: <=100 records is safe. 200 records ~5 min. 400+ records may hit timeouts.

Query Command (Advanced)

For aggregation/groupBy, cross-entity filtering, nested AND/OR/NOT, or a cost preview, use xaffinity query. Always `--dry-run` first for queries with include/expand/quantifiers. Full reference (JSON structure, operators, aggregation, examples): references/query-guide.md.

Gotchas & Workarounds

• Smart fields ("Last Meeting", "Next Meeting") are UI-only. Use --with-interaction-dates on

get commands (not ls): xaffinity --readonly company get domain:acme.com --with-interaction-dates --json.

• Internal meetings are NOT in interactions (only meetings with external contacts) — use notes;

see references/interactions.md.

• Opportunities are bound to one list. You cannot search opportunities globally; use

list export on their list. opportunity get needs --details for field values.

• Progress output goes to stderr, so JSON on stdout stays clean. Use --quiet / -q to

suppress progress — but don't discard stderr (pitfall 1).

• Affinity API versions differ. Results come from the API key's default version unless

--api-version (e.g. 2026-09-17) / AFFINITY_API_VERSION is set; meta.affinityApiVersion says which answered. Don't add --api-version unless the user asks.

Quick Reference

Remember: prefix all commands with xaffinity --readonly (and --dotenv if check-key says so). Install: pip install "affinity-sdk[cli]==2.0.6", the version this skill is written for (--user plus the PATH line above when xaffinity isn't found); if a command or flag shown here is missing, the installed CLI is older: install that version. Docs: https://yaniv-golan.github.io/affinity-sdk/latest/