synappsis-crm-cli

Agent-first CLI for the Synappsis multi-tenant CRM. Designed primarily to be invoked by LLM agents running in a Claude Managed Agents sandbox, but also usable by humans at a terminal.

See AGENT-CONTEXT.md for the agent-oriented reference. This README is for humans.

Install

Published to npm:

npm install -g @synappsisai/crm-cli

Or, in a CMA environment, add it to the packages.npm field of the environment config:

{
  "config": {
    "type": "cloud",
    "packages": {
      "npm": ["@synappsisai/crm-cli"]
    }
  }
}

The binary is crm.

Configure

The CLI reads its credentials from environment variables. There is no config file, no ~/.crm/ directory, no interactive login.

export CRM_SUPABASE_URL="https://<your-project>.supabase.co"
export CRM_SUPABASE_KEY="<service_role key>"
export CRM_TENANT_ID="synappsis"

In AgentFleet, these are injected per turn by the worker Lambda before the agent runs.

Usage

# List the latest 10 deals
crm deals list --limit 10

# Filter by stage, get JSON
crm deals list --stage prospecto --json

# Show a specific deal
crm deals show <uuid>

# Search contacts
crm contacts search "Alonso Bravo"

# Discover the full API
crm schema

Design principles

This CLI follows the Synappsis house standard for agent-first CLIs. See docs/AGENT-FIRST-CLI-DESIGN.md in the AgentFleet repo for the full rationale. Summary:

• Noun-verb command hierarchy (crm <noun> <verb>)
• JSON to stdout, everything else to stderr
• TTY-aware default output mode (JSON when piped, table when interactive)
• Meaningful exit codes (2 = usage, 3 = not found, 4 = permission, 5 = conflict, 6 = rate limited, 7 = upstream, 1 = internal)
• Structured errors with code, message, and suggestion fields
• No interactive prompts
• crm schema dumps the full API contract as JSON

Development

cd cli
npm install
npm run dev -- deals list --limit 5    # run via tsx without compiling
npm run build                            # compile to dist/
./dist/index.js deals list --limit 5     # run the compiled binary

Publishing

cd cli
npm version patch   # or minor/major
npm publish

prepublishOnly runs the build automatically.

Status

v0.1.0 — POC / read-only. Only deals list, deals show, contacts search, contacts show, and schema are implemented. Mutations (create, update, delete, ensure) are deliberately not in this version — they come once the auth model is tightened (see AgentFleet docs/CRM-RLS-AUTH-SPEC.md).