@badgie/crm-cli (badgie-crm)

Versión publicada: 0.7.0 — ver CHANGELOG.md.

CLI para operar el Badgie CRM desde la terminal. Reemplaza los scripts sueltos de /scripts/ y expone el CRM vía MCP a agentes IA (openclaw, Claude Desktop, Cursor...).

Nombre del binario: badgie-crm — dejamos badgie reservado para el CLI principal de Badgie (próximo).

Instalación

Para usuarios del equipo:

npm install -g @badgie/crm-cli
badgie-crm login
badgie-crm whoami --pretty

Para actualizar:

npm update -g @badgie/crm-cli

Desarrollo local

Desde la raíz del repo:

cd cli
npm install
npm run build
npm link      # expone `badgie-crm` como binario global

Después, desde cualquier sitio:

badgie-crm               # banner + estado + atajos
badgie-crm --help

Para desarrollo rápido sin build continuo:

cd cli && npm run dev -- leads list --pretty

Configuración

El CLI lee credenciales de Supabase en este orden:

1. BADGIE_CRM_SUPABASE_URL / BADGIE_CRM_SUPABASE_ANON_KEY (env vars explícitas).
2. BADGIE_SUPABASE_URL / BADGIE_SUPABASE_ANON_KEY (retrocompat).
3. NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY del .env.local del repo.
4. Valores guardados en ~/.badgie-crm/config.json tras el primer badgie-crm login.
5. Defaults públicos embebidos (DEFAULT_SUPABASE_URL / anon key pública) para que el paquete npm funcione sin repo clonado.

Si tenías un ~/.badgie/config.json de la versión anterior, se migra automáticamente la primera vez que se arranca el CLI.

Autenticación

Dos modos:

Modo usuario (interactivo, respeta RLS)

badgie-crm login

Te pide email + contraseña de tu cuenta Badgie (el mismo login que la app web). Aplica las mismas reglas: cuentas @badgie.com entran directas, otras deben tener fila en team_members activa. La sesión se guarda en ~/.badgie-crm/config.json (permisos 0600) y los tokens se refrescan automáticamente.

badgie-crm whoami          # JSON
badgie-crm whoami --pretty # texto
badgie-crm logout          # limpia la sesión

Modo service (CI / automatización, bypassa RLS)

export BADGIE_CRM_SERVICE_KEY=eyJhbGc...
badgie-crm leads list

BADGIE_CRM_SERVICE_KEY (o BADGIE_SERVICE_KEY / SUPABASE_SERVICE_ROLE_KEY) tiene precedencia sobre la sesión interactiva. Úsalo solo en entornos confiables.

Módulos

La versión 0.7.0 expone 110 comandos. Módulos principales:

leads, clients, contacts, tasks, development, finance, outbound, directory, marketing, intelligence, mission-control, top-clients, federations, web-design, team, sports, activities, demos, onboarding, webhooks, admin, search, query, docs, mcp.

Explora todo con:

badgie-crm docs                    # tree completo
badgie-crm docs finance            # filtrado por módulo
badgie-crm docs --json             # manifest JSON para agentes IA
badgie-crm docs --agent-hints      # guidance extra para LLMs

Ejemplos frecuentes

# Facturas de marzo de la categoría salarios
badgie-crm finance invoices list --category salarios --since 2026-03-01 --until 2026-03-31 --pretty

# Factura con IRPF (retención): total_amount sigue siendo el neto a pagar; ver withholding_rate / withholding_amount
badgie-crm finance invoices list --since 2026-01-01 --pretty

# Finance OS: cockpit operativo de caja
badgie-crm finance control summary --pretty
badgie-crm finance health --critical-only
badgie-crm finance aging --date 2026-04-30
badgie-crm finance tax-summary --year 2026 --quarter 2 --pretty
badgie-crm finance tax-summary --year 2026 --quarter 2 --csv > fiscal-q2.csv

# Finance OS: forecast manual y cierres
badgie-crm finance forecast summary --pretty
badgie-crm finance forecast list --active-only --pretty
badgie-crm finance forecast add --type expense --name "Oficina" --amount 350 --recurrence monthly --next-date 2026-05-01 --pretty
badgie-crm finance closings list --year 2026 --pretty
badgie-crm finance closings close --year 2026 --month 4 --notes "Abril revisado" --pretty

# Query genérico — cualquier columna de cualquier tabla
badgie-crm query invoices --where "category=salarios" --where "invoice_date:gte:2026-03-01" --pretty
badgie-crm query count bank_movements --where "amount:gte:1000" --where "movement_date:gte:2026-03-01"
badgie-crm query describe invoices --pretty

# Directory
badgie-crm directory schools list --sport golf --province Madrid --min-rating 4.5 --pretty

# Búsqueda global
badgie-crm search "valencia" --pretty

Finance OS

Los comandos badgie-crm finance control|health|aging|tax-summary|forecast|closings cubren la capa nueva de Finanzas como sistema operativo de caja:

• finance control summary es el primer comando recomendado para un agente: devuelve cierre del periodo, incidencias, fiscal, aging y forecast 30/60/90.
• finance health llama al endpoint autenticado de la app y usa las mismas incidencias que Control → Salud.
• finance tax-summary usa el cálculo trimestral de la app; --csv emite una fila lista para exportar.
• finance forecast add|update|pause|resume|delete llama a los endpoints Finance OS para respetar finance_access, audit log y bloqueo de periodos cerrados.
• finance closings close|reopen también pasa por la app; no edites finance_period_closings con query salvo inspección de solo lectura.
• finance forecast delete es destructivo: los agentes deben pedir confirmación explícita.

Descubrimiento completo:

badgie-crm docs finance --json
badgie-crm docs finance

Top Clients

Top Clients usa client_monthly_reviews para las revisiones mensuales. La pantalla actual no tiene una tabla separada de preguntas/configuración: las preguntas del modal son columnas de esa tabla (notes, needs, testimonials, risk_level, next_actions, status, reviewed_at) y el contacto semanal vive en metadata.contact_log.

# Listar reviews existentes del mes
badgie-crm top-clients list --month 4 --year 2026 --limit 10

# Ver detalle completo de una review
badgie-crm top-clients get <review-id>

# Ver las preguntas/campos que puede responder un agente
badgie-crm top-clients questions list

# Ver respuestas guardadas
badgie-crm top-clients answers list --review-id <review-id>

# Resumen mensual
badgie-crm top-clients summary --month 4 --year 2026

# Previsualizar creación de reviews para clientes activos/free trial
badgie-crm top-clients generate --month 4 --year 2026 --dry-run

# Escribir respuestas
badgie-crm top-clients answer set --review-id <review-id> --question risk_level --value high
badgie-crm top-clients notes set --review-id <review-id> --notes "Cliente estable; revisar expansión"
badgie-crm top-clients owner set --review-id <review-id> --kam Greg

# Config por cliente derivada de campos existentes en clients
badgie-crm top-clients config get --client-id "Club Example"
badgie-crm top-clients config set --client-id "Club Example" --kam Greg --dry-run

Para descubrir todos los flags y ejemplos:

badgie-crm docs top-clients
badgie-crm docs top-clients --json

Distribución al equipo

El canal normal es npm:

npm install -g @badgie/crm-cli
badgie-crm login

Para desarrollo del propio CLI usa npm link desde cli/. Vercel no interviene: Vercel despliega la app Next (/app) y el CLI es un paquete npm independiente.

Publish futuro:

cd cli
npm version patch
npm publish --access public --auth-type=web
git push --follow-tags

Antes de publicar, revisa knowledge/cli/npm-publish-cli-gotchas.md.

Agentes IA (openclaw, Claude, Cursor…)

Ver cli/AGENTS.md. Dale eso al agente + el manifest JSON:

badgie-crm docs --json > ~/.badgie-crm/manifest.json

El agente carga ese JSON como catálogo de tools y respeta los tags [read|write|destructive|http] para saber qué es seguro.

MCP local

badgie-crm mcp serve expone los comandos como tools MCP tipadas sobre stdio:

{
  "mcpServers": {
    "badgie-crm": {
      "command": "badgie-crm",
      "args": ["mcp", "serve"]
    }
  }
}

Esto funciona en clientes nativos que pueden lanzar procesos locales (Claude Desktop, Cursor, VS Code, openclaw local). No funciona en UIs web que no puedan ejecutar procesos en la máquina del usuario.

Roadmap

Ver tasks/badgie-crm-cli-mcp.md para el estado actual y próximos huecos. Los más relevantes: imports directos de facturas/banco desde archivos, tests automáticos del CLI, y seguir migrando scripts legacy cuando haga falta.

Notas

• La carpeta cli/ está excluida de la build de Next (outputFileTracingExcludes en next.config.ts + exclude en tsconfig.json raíz).
• ~/.badgie-crm/config.json no debe commitearse — es local del usuario.