npm package: @startanaicompany/crm
Description: AI-first CRM CLI — manage leads and API keys from the terminal
Latest version: 2.21.0

# @startanaicompany/crm

AI-first CRM CLI (`saac_crm`) — manage leads, API keys, and user accounts from the terminal.

## Installation

```bash
npm install -g @startanaicompany/crm
```

---

## 🏢 Multi-Tenant Architecture

This CRM is **multi-tenant**: each company gets its own isolated workspace. All data (leads, contacts, calls, contracts, etc.) is completely separated between workspaces.

- One workspace slug per company (e.g. `mygardeningcompany`, `johnscarshop`)
- All agents of a company share the same workspace — one key per "fleet" or one key per agent, your choice
- Cross-workspace data access is impossible: a key from workspace `mygardeningcompany` can never see data from `johnscarshop`

---

## 🤖 AI Agent Quick Start (zero-auth)

Agents bootstrap themselves in two steps:

```bash
# Step 1: Point at the CRM deployment
saac_crm config set --url https://crm.startanaicompany.com

# Step 2: Bootstrap your workspace + get an API key (no auth needed, no human required)
saac_crm workspace init --workspace mygardeningcompany --name my-agent
# → Returns crm_xxxx API key + saves key + workspace to ~/.saac_crm/config.json

# Step 3: Start working (workspace is automatically used from config)
saac_crm leads create --name "Jane Smith" --email "jane@example.com"
saac_crm leads list

# Optional: attribute actions to a named agent for audit trail
saac_crm leads create --name "Bob Jones" --email "bob@example.com" --from-agent-name "discovery-agent-v2"
```

> **Auth priority**: `--api-key` flag > `SAAC_CRM_API_KEY` env var > config file (`~/.saac_crm/config.json`)
> **Workspace priority**: `--workspace` flag > `SAAC_CRM_WORKSPACE` env var > config file `workspace` field

> ⚠️ **Agents: `workspace init` is idempotent** — if the workspace already exists, it just creates a new key for it. Safe to call from any agent on first run.

---

## 👤 Operator Setup (one-time, human)

For the initial admin setup or to create admin-scope keys:

```bash
# 1. Point at your deployment
saac_crm config set --url https://crm.startanaicompany.com

# 2. Create admin-scope key for your workspace (requires deployment admin password)
saac_crm keys create --name "admin-key" --workspace mycompany --scope admin
# → Prompts for admin password

# 3. Save admin key to config and create the first human user account
saac_crm config set --api-key crm_xxx_admin_key
saac_crm users create --email admin@example.com --name "Admin" --role admin
```

---

## Commands

### Workspace

```bash
# Bootstrap workspace + create API key in one step (recommended for agent auto-init)
saac_crm workspace init --workspace mycompany --name "my-agent"
saac_crm workspace init --workspace mycompany --name "admin-key" --scope admin

# Via REST: POST /api/v1/workspaces/register
# Body: { workspace, key_name, scope?, admin_password? }
```

### API Keys

```bash
# Create agent key — workspace required (auto-creates workspace if it doesn't exist yet)
saac_crm keys create --name "my-agent" --workspace mycompany

# Create admin scope key (requires deployment password)
saac_crm keys create --name "admin-key" --workspace mycompany --scope admin

# List all keys in current workspace
saac_crm keys list

# Show current key info
saac_crm keys self

# Revoke a key by ID
saac_crm keys revoke <id>
```

### Leads

```bash
# Create a lead (optional: --from-agent-name for audit trail)
saac_crm leads create --name "Jane Smith" --email "jane@example.com" --company "Acme" --from-agent-name "lead-gen-agent"

# List leads (with filters)
saac_crm leads list --status new --tag vip

# Get single lead
saac_crm leads get <id>

# Update lead
saac_crm leads update <id> --status contacted --notes "Called, interested"

# Soft-delete lead
saac_crm leads delete <id>

# Status change history
saac_crm leads history <id>

# Move lead to pipeline stage
saac_crm leads stage <id> --stage discovery
```

### Contacts

```bash
saac_crm contacts create --email contact@example.com --first-name "Jane" --from-agent-name "enrichment-agent"
saac_crm contacts list
saac_crm contacts get <id>
saac_crm contacts update <id> --company "Acme"
saac_crm contacts delete <id>
```

### Calls

```bash
saac_crm calls create --lead-id <id> --direction outbound --outcome connected --from-agent-name "call-agent"
saac_crm calls list [--lead-id <id>]
saac_crm calls get <id>
```

### Meetings

```bash
saac_crm meetings create --lead-id <id> --title "Demo call" --from-agent-name "scheduler-agent"
saac_crm meetings list
saac_crm meetings get <id>
```

### Emails

```bash
saac_crm emails create --lead-id <id> --subject "Follow-up" --direction sent --from-agent-name "outreach-agent"
saac_crm emails list [--lead-id <id>]
saac_crm emails get <id>
```

### Quotes

```bash
saac_crm quotes create --lead-id <id> --title "Q-2026-001" --value 5000 --from-agent-name "quote-agent"
saac_crm quotes list
saac_crm quotes get <id>
saac_crm quotes status <id> --status accepted
saac_crm quotes add-line <id> --description "License" --quantity 1 --unit-price 5000
```

### Contracts

```bash
saac_crm contracts create --lead-id <id> --title "Service Agreement" --from-agent-name "contract-agent"
saac_crm contracts list
saac_crm contracts get <id>
saac_crm contracts status <id> --status sent
saac_crm contracts signatories <id>
saac_crm contracts add-signatory <id> --contact-id <cid> --party customer --role signer
saac_crm contracts sign <id> --contact-id <cid>
saac_crm contracts decline-signature <id> --contact-id <cid>
saac_crm contracts remind-signatory <id> --contact-id <cid>
saac_crm contracts remind-all-pending <id>
```

### Users (requires admin scope key)

```bash
saac_crm users create --email admin@example.com --name "Admin User" --role admin
saac_crm users list
saac_crm users update <id> --role viewer
saac_crm users deactivate <id>
```

### Human Login

```bash
# Log in as admin/viewer — saves JWT to config for dashboard access
saac_crm login --workspace mycompany --email admin@example.com
# → Prompts for password, saves JWT to ~/.saac_crm/config.json
```

### Configuration

```bash
saac_crm config set --url https://crm.startanaicompany.com
saac_crm config set --api-key crm_xxxxxxxxxxxx
saac_crm config set --workspace mycompany
saac_crm config set --agent-name "my-agent-v2"   # default --from-agent-name for all commands
saac_crm config get
```

## Global Options

```
--api-key <key>   Override API key for this command
--url <url>       Override API base URL for this command
```

## `--from-agent-name` Attribution

Pass `--from-agent-name <name>` (or set `SAAC_CRM_AGENT_NAME` env / `config.defaultAgentName`) on any create command to attribute the action to a named agent. This is for **audit trail only** — it does NOT affect authentication or authorization. The same workspace key is shared across all agents of that workspace.

```bash
export SAAC_CRM_AGENT_NAME=discovery-agent-v2
saac_crm leads create --name "Alice" --email "alice@example.com"
# → lead.from_agent_name = "discovery-agent-v2"
```

## Architecture

This is a **multi-tenant** system: multiple workspace slugs per deployment, each fully isolated.

- **Agents** → `workspace init` once → `leads create` → manage leads with workspace isolation
- **Operators** → `keys create --scope admin` → `users create` → human accounts
- **Humans** → `login` → web dashboard (only shows their workspace's data)
- **Audit** → `--from-agent-name` for per-agent attribution within a workspace