@roilab/crm-cli

CLI for humans and AI agents to drive the ROILab SEO+CRM platform.

CLI para el SEO + CRM de ROILab, pensado tanto para humanos como para agentes de IA (Claude Code, Cursor, Windsurf). Envoltura JSON siempre, exit codes numéricos, escrituras idempotentes y login sin pegar API keys en texto plano (flujo de dispositivo tipo OAuth).

Instalación

Agentes (recomendado)

Sin instalación previa, siempre la última versión:

npx -y @roilab/crm-cli@latest <comando>

Humanos

Para dejar crm en el PATH:

npm i -g @roilab/crm-cli
crm --help

Actualiza con:

npm i -g @roilab/crm-cli@latest

El propio CLI comprueba una vez al día si hay una versión nueva en npm y avisa por stderr. Para forzar la comprobación, ejecuta crm doctor.

Primer login (30 segundos)

crm auth login --device-name mi-portatil
# Abre la URL que aparece en el navegador, aprueba.
crm auth whoami
crm doctor

El CLI guarda tokens rotativos en ~/.config/crm/credentials.json (modo 0600). Nunca se escribe una API key en claro en disco por esta vía.

Comandos

crm recall https://example.com/pricing
crm task list --status todo --domain dom_xyz --limit 20
crm task create --title "Arreglar H1 en /pricing" --domain dom_xyz --shadow
crm comment create --task tsk_abc --body "Desplegado en prod" --kind agent_log
crm domain metrics dom_xyz --start 2026-03-01 --end 2026-04-01 --markdown
crm review list --mine

crm --help imprime todos los sustantivos; crm <noun> --help imprime los verbos; la documentación completa vive en la app, pestaña Documentación, que se auto-genera desde el registro de endpoints — siempre refleja la versión servida.

Flags globales

Disponibles en cada comando:

• --json — envoltura JSON completa (por defecto).
• --quiet — solo data.
• --ids-only — un id por línea.
• --count — un único entero.
• --markdown — resumen legible (no es JSON).
• --jq <expr> — jq mini (.a, .a.b, .a[], .a[].b).
• --shadow — fuerza que la escritura aterrice como propuesta pendiente de revisión humana.
• --wait-for-approval --timeout 30m — bloquea hasta que un humano decida.
• --idempotency-key <key> — idempotency key estable (automática en escrituras).

Seguridad

• Sin scripts preinstall / postinstall / install — nada que se ejecute al instalar el paquete.
• Auth por flujo de dispositivo: no se comparten secretos entre máquinas; el access token caduca en 1 h y el refresh token rota en cada uso.
• Archivo de credenciales con permisos 0600, aislado por perfil.
• Publicación con atestación de procedencia (npm publish --provenance) para que se pueda verificar el origen del tarball.

Licencia

MIT — ver LICENSE.