CLI¶

The SDK ships an optional xaffinity CLI that dogfoods the SDK. Install it as an extra so library-only users don't pay the dependency cost.

Key Features¶

CSV Export: Export people, companies, opportunities, and list entries to CSV with --csv flag (CSV Export Guide)
Filtering: Server-side filtering on custom fields with --filter (Filtering Guide)
JSON Output: All commands support --json for programmatic use (Scripting Guide)
Pagination: Fetch all pages with --all or control page size with --page-size
Name Resolution: Use names instead of IDs for lists, fields, and entities
Session Caching: Share metadata across pipeline commands with session start/end (Pipeline Optimization)

See Commands Reference for complete command documentation.

Connect any MCP-compatible AI tool (Claude Desktop, Cursor, Windsurf, VS Code + Copilot) to Affinity. See MCP Server.

Using Claude Code? Install the CLI plugin for AI-assisted usage:

/plugin marketplace add yaniv-golan/affinity-sdk
/plugin install cli@xaffinity

This teaches Claude CLI patterns and provides the /affinity-help quick reference command. See Claude Code plugins for all available plugins.

Recommended for end-users:

pipx install "affinity-sdk[cli]"

Or in a virtualenv:

pip install "affinity-sdk[cli]"

The CLI never makes "background" requests. It only calls the API for commands that require it.

Check if a key is already configured:

xaffinity config check-key

Set up a new key securely (hidden input, not echoed):

xaffinity config setup-key

The CLI checks these sources in order (highest precedence first):

For project-specific keys, use --dotenv to load from .env:

xaffinity --dotenv whoami
xaffinity --dotenv --env-file ./dev.env whoami

The config setup-key --scope project command creates a .env file and adds it to .gitignore automatically.

--json is supported on every command.
In --json mode, JSON is written to stdout. Progress/logging go to stderr.
Human/table output goes to stdout; diagnostics go to stderr.
Commands build a single structured result and then render it as either JSON or table output (no “double implementations”).
In --json mode, data is an object keyed by section name (even for single-section commands), and pagination tokens/URLs live in meta.pagination.<section>.
If --max-results truncates results mid-page, the CLI may omit meta.pagination.<section> to avoid producing an unsafe resume token.

The CLI enables SDK in-memory caching for cacheable metadata requests (e.g., field metadata) automatically.

For pipelines running multiple commands, use session caching to share metadata across invocations:

export AFFINITY_SESSION_CACHE=$(xaffinity session start)
xaffinity list export "My List" | xaffinity person get
xaffinity session end

The CLI writes logs to platform-standard locations (via platformdirs), with rotation and redaction.

Override with:

These flags expose useful SDK behaviors directly from the CLI:

For testing against mock servers, these environment variables override API base URLs:

AFFINITY_V1_BASE_URL: Override V1 API base URL (default: https://api.affinity.co)
AFFINITY_V2_BASE_URL: Override V2 API base URL (default: https://api.affinity.co/v2)

These can also be set per-profile in the config file.