close-crm-cli 0.1.0

package/README.md

@@ -0,0 +1,242 @@
+# close-crm-cli
+
+> Full-featured CLI and MCP server for the [Close CRM](https://close.com) platform. Every API endpoint available as a terminal command **and** as an MCP tool for AI agents.
+
+## Features
+
+- **160+ commands** across 30 resource groups — full Close API coverage
+- **MCP server built-in** — run `close mcp` to expose all commands as Claude/Cursor tools
+- **JSON output** by default — pipe to `jq`, script freely, or feed directly to AI agents
+- **Authentication** via env var, flag, or stored config (`close login`)
+- **HTTP Basic Auth** — Close's native auth method, handled automatically
+- **Pagination** — offset-based `_limit`/`_skip` pagination with `has_more`
+- **Retry + rate limit handling** — automatic exponential backoff on 429/5xx
+
+## Installation
+
+```bash
+npm install -g close-crm-cli
+```
+
+Or use without installing:
+```bash
+npx close-crm-cli leads list
+```
+
+## Authentication
+
+Get your API key from **https://app.close.com/settings/api**
+
+```bash
+# Option 1: Environment variable (recommended)
+export CLOSE_API_KEY="your-api-key"
+
+# Option 2: Interactive login (stores in ~/.close/config.json)
+close login
+
+# Option 3: Per-command flag
+close leads list --api-key "your-api-key"
+```
+
+## Quick Start
+
+```bash
+# Get your user profile
+close users me
+
+# List leads
+close leads list
+
+# Create a lead
+close leads create --name "Acme Corp" --url "https://acme.com"
+
+# Create a contact on a lead
+close contacts create --lead-id lead_abc123 --name "Jane Doe" \
+  --emails '[{"email":"jane@acme.com","type":"office"}]'
+
+# Log a call
+close calls create --lead-id lead_abc123 --direction outbound --duration 900 \
+  --note "Discussed Q2 priorities"
+
+# Create a follow-up task
+close tasks create --lead-id lead_abc123 --text "Send proposal" \
+  --type email --due-date "2025-04-07T09:00:00"
+
+# Move opportunity to next stage
+close opportunities update oppo_abc123 --status-id "stat_demo_scheduled"
+```
+
+## Output Options
+
+```bash
+# Default: compact JSON (machine-readable)
+close leads list
+
+# Pretty-printed JSON
+close leads list --pretty
+
+# Select specific fields
+close leads list --fields id,display_name,status_label
+
+# Suppress output (exit codes only: 0=success, 1=error)
+close leads list --quiet
+```
+
+## Command Groups
+
+| Group | Commands | Description |
+|-------|----------|-------------|
+| `leads` | list, get, create, update, delete, merge, search | CRM leads |
+| `contacts` | list, get, create, update, delete | Contacts within leads |
+| `opportunities` | list, get, create, update, delete | Pipeline opportunities |
+| `tasks` | list, get, create, update, delete, bulk-update | Tasks & follow-ups |
+| `activities` | list | Unified activity stream |
+| `calls` | list, get, create, update, delete | Call logs |
+| `notes` | list, get, create, update, delete | Notes |
+| `emails` | list, get, create, update, delete | Email activities |
+| `sms` | list, get, create, delete | SMS activities |
+| `meetings` | list, get, update, delete | Meetings |
+| `users` | me, list, get, availability | Users |
+| `pipelines` | list, get, create, update, delete | Sales pipelines |
+| `lead-statuses` | list, get, create, update, delete | Lead status labels |
+| `opportunity-statuses` | list, get, create, update, delete | Pipeline stages |
+| `custom-fields` | list/get/create/update/delete-{lead\|contact\|opportunity\|activity\|shared} | Custom fields |
+| `webhooks` | list, get, create, update, delete | Webhook subscriptions |
+| `sequences` | list, get, create, update, delete, subscribe, list-subscriptions | Outreach sequences |
+| `email-templates` | list, get, create, update, delete, render | Email templates |
+| `sms-templates` | list, get, create, update, delete | SMS templates |
+| `smart-views` | list, get, create, update, delete | Saved views |
+| `reports` | activity-metrics, activity-report, funnel | Analytics |
+| `phone-numbers` | list, get, update, delete | Phone numbers |
+| `connected-accounts` | list, get | Connected email accounts |
+| `organizations` | get, update | Organization settings |
+| `groups` | list, get, create, update, delete | User groups |
+| `roles` | list, get | User roles |
+| `exports` | list, get, create-lead, create-opportunity | Data exports |
+| `unsubscribe` | list, add, delete | Email unsubscribe list |
+
+## MCP Server
+
+Expose all commands as tools for Claude, Cursor, Windsurf, or any MCP-compatible AI:
+
+```bash
+close mcp
+```
+
+### Claude Desktop / Cursor Configuration
+
+Add to your MCP config (`~/.claude/config.json` or Cursor settings):
+
+```json
+{
+  "mcpServers": {
+    "close": {
+      "command": "npx",
+      "args": ["close-crm-cli", "mcp"],
+      "env": {
+        "CLOSE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+Or with a global install:
+
+```json
+{
+  "mcpServers": {
+    "close": {
+      "command": "close",
+      "args": ["mcp"],
+      "env": {
+        "CLOSE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+Once configured, Claude can call any Close CRM action directly. Example prompts:
+- "List all leads with status Potential"
+- "Create a new opportunity for Acme Corp worth $50k"
+- "Log a 15-minute outbound call to lead_abc123"
+- "Enroll Jane Doe in the Q1 follow-up sequence"
+- "Show me this week's activity metrics"
+
+## Pagination
+
+```bash
+# First page
+close leads list --limit 50
+
+# Next page
+close leads list --limit 50 --skip 50
+```
+
+## Custom Fields
+
+```bash
+# List available custom fields
+close custom-fields list-lead
+
+# Set custom fields on create/update
+close leads create --name "Acme Corp" --custom '{"cf_budget":"500000","cf_industry":"SaaS"}'
+close leads update lead_abc123 --custom '{"cf_stage":"Pilot"}'
+```
+
+## Advanced Search
+
+```bash
+# Simple query string
+close leads list --query "Acme"
+
+# Advanced DSL via POST /data/search/
+close leads search --query '{
+  "type": "and",
+  "queries": [
+    {"type":"field","field":{"type":"regular","field_name":"status_label"},"negate":false,"condition":{"type":"text","mode":"equals","value":"Potential"}}
+  ]
+}' --limit 100
+```
+
+## Development
+
+```bash
+git clone https://github.com/bcharleson/close-crm-cli
+cd close-crm-cli
+npm install
+
+# Run in dev mode
+npm run dev -- leads list
+
+# Build
+npm run build
+
+# Type check
+npm run typecheck
+```
+
+## Architecture
+
+The CLI is built on a `CommandDefinition` pattern — one object per API endpoint that serves as the single source of truth for both the CLI subcommand and the MCP tool:
+
+```typescript
+interface CommandDefinition {
+  name: string;          // MCP tool name (e.g. "leads_create")
+  group: string;         // CLI group (e.g. "leads")
+  subcommand: string;    // CLI subcommand (e.g. "create")
+  description: string;   // Used in --help and MCP tool description
+  inputSchema: ZodObject; // Shared input validation
+  cliMappings: CliMapping; // How fields map to CLI args/options
+  endpoint: { method, path }; // HTTP endpoint
+  fieldMappings: Record<string, 'path'|'query'|'body'>; // Where fields go
+  handler: Function;     // Executes the request
+}
+```
+
+See [AGENTS.md](AGENTS.md) for the full AI agent integration guide.
+
+## License
+
+MIT