Scout CLI

CLI de prospección comercial: encuentra negocios en cualquier parte del mundo y apóyate de un coach para cerrar el deal.

Instalación

npm install -g @asuarezz/scout

o mejor

pnpm install -g @asuarezz/scout

Requisito: Node.js ≥ 18. Si no lo tienes:

# macOS / Linux (recomendado vía nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts

# Windows
winget install OpenJS.NodeJS.LTS

Uso rápido

# 1. Configura tus credenciales (solo la primera vez)
scout init

# 2. Inicia una búsqueda
scout

El flujo completo:

1. Ingresas ciudad y tipo de negocio
2. Gemini genera un banco de 5–8 queries optimizados para Google Places
3. Scout ejecuta cada query, deduplica y filtra los que no tienen sitio web (incluye negocios que solo tienen redes sociales como "presencia digital")
4. Cada prospecto recibe un Score 0–100 basado en: ausencia de web, rating, número de reseñas, nivel de precio y presencia en redes sociales
5. En la lista de resultados puedes:
   • Pulsar e para exportar todos los prospectos a Excel (10 columnas: Score, Nombre, Teléfono, Redes Sociales, Rating, Reseñas, Precio, Google Maps ↗, Dirección, PlaceId)
   • Seleccionar un negocio para entrar al Coach comercial
6. El Coach de Gemini te guía en 3 fases para cerrar el deal:
   • Fase 1 — Te pregunta qué servicio quieres ofrecer, si ya tuviste contacto y tu precio en mente
   • Fase 2 — Genera un 📞 Script de llamada personalizado para ese negocio específico: apertura de 15 segundos, preguntas de descubrimiento, manejo de objeciones y cierre para cita
   • Fase 3 — Si ya hablaste con el cliente, analiza lo descubierto, define el paquete de servicios y calcula el pricing en USD y COP
7. Ejecutas /done y se genera propuesta_nombre-del-negocio.md lista para enviar al prospecto

Credenciales necesarias

Necesitas dos API keys antes de usar Scout. Ambas tienen plan gratuito suficiente para uso personal.

1. Google Places API key

Tiempo estimado: 10 minutos

Paso 1 — Crear el proyecto

1. Ve a console.cloud.google.com e inicia sesión con tu cuenta de Google.
2. En la barra superior, haz click en el selector de proyectos (dice "Select a project" o el nombre del proyecto actual).
3. En el modal que aparece, click en Nuevo proyecto (esquina superior derecha del modal).
4. Escribe un nombre, por ejemplo scout-prospecting, y click en Crear.
5. Espera unos segundos y selecciona el proyecto recién creado desde el selector.

Paso 2 — Activar facturación (obligatorio para usar Places API)

Google exige una cuenta de facturación activa para usar Places API, aunque tengas crédito gratuito y nunca pagues nada.

1. En el menú lateral izquierdo, click en Facturación.
2. Click en Vincular una cuenta de facturación → Crear cuenta de facturación.
3. Completa el formulario con tu país y tarjeta de crédito/débito (no se hace ningún cargo inmediato).
4. Confirma la vinculación con tu proyecto.

Paso 3 — Habilitar la Places API (New)

1. En el menú lateral, click en APIs y servicios → Biblioteca.
2. En el buscador escribe Places API.
3. Aparecerán dos opciones: selecciona Places API (New).
4. Click en Habilitar. Espera a que cargue la página de gestión de la API.

Paso 4 — Crear la clave de API

1. En el menú lateral, click en APIs y servicios → Credenciales.
2. Click en + Crear credenciales (parte superior) → Clave de API.
3. Se genera automáticamente una clave. Cópiala y guárdala en un lugar seguro.
4. Click en Cerrar.

Paso 5 — Restringir la clave (recomendado)

Esto evita que alguien que obtenga tu key la use para otros servicios de Google:

1. En la lista de credenciales, click en el nombre de la key que acabas de crear.
2. En Restricciones de API, selecciona Restringir clave.
3. En el desplegable, busca y selecciona Places API.
4. Click en Guardar.

Crédito gratuito: Google otorga 200 USD mensuales de crédito a todas las cuentas, lo que equivale a aproximadamente 2.000 búsquedas de texto gratuitas por mes. Para prospección ocasional nunca llegarás al límite.

2. Google Gemini API key

Tiempo estimado: 2 minutos

1. Ve a aistudio.google.com/app/apikey e inicia sesión.
2. Click en Create API key.
3. Selecciona el proyecto de Google Cloud donde habilitaste Places (o crea uno nuevo).
4. Copia la key generada.

Plan gratuito: Los modelos gemini-2.0-flash y gemini-1.5-flash tienen cuota gratuita generosa (hasta 1.500 requests/día en el tier gratuito). Para generar propuestas de prospección es más que suficiente.

Una vez tengas ambas keys, ejecuta:

scout init

Scout validará cada key en tiempo real y te pedirá elegir el modelo Gemini antes de guardar.

Comandos

scout              # Inicia el flujo de prospección
scout init         # Reconfigura credenciales o cambia el modelo Gemini
scout --help       # Muestra la ayuda
scout --version    # Muestra la versión instalada
scout --verbose    # Activa logs de debug

Atajos en la pantalla de resultados:

| Tecla | Acción | |-------|--------| | ↑ ↓ | Navegar la lista de prospectos | | Enter | Iniciar el Coach comercial con el negocio seleccionado | | e | Exportar todos los prospectos a Excel (.xlsx) | | q | Volver a la búsqueda |

Comandos dentro del Coach:

Escribe / en el input para ver el menú de comandos disponibles. Navega con ↑ ↓ y confirma con Enter. También puedes escribir el comando directamente:

| Comando | Acción | |---------|--------| | /done | Genera la propuesta comercial con la conversación actual | | /save | Guarda el transcript sin generar propuesta | | /back | Vuelve a la lista de prospectos | | Esc | Cierra el menú / o vuelve a la lista de prospectos |

Selección de modelo Gemini

Durante scout init, después de validar tu API key, Scout lista automáticamente los modelos disponibles para tu cuenta y te permite elegir.

Guía rápida de selección:

| Modelo | Velocidad | Cuota gratuita | Recomendado para | |--------|-----------|---------------|-----------------| | gemini-2.0-flash | ★★★★★ | Alta | Uso diario — mejor balance velocidad/calidad | | gemini-2.0-flash-lite | ★★★★★ | Alta | Búsquedas rápidas, bajo consumo de cuota | | gemini-1.5-flash | ★★★★☆ | Alta | Alternativa estable y probada | | gemini-1.5-pro | ★★★☆☆ | Media | Propuestas más detalladas, más lento | | gemini-2.5-flash | ★★★★☆ | Media | Máxima calidad con buena velocidad |

Para cambiar el modelo sin reconfigurar todo:

scout init
# → Elige "No, usar la existente" y luego cambia el modelo

Arquitectura

Stack: TypeScript ESM · React + Ink · tsup · Vitest

La CLI renderiza interfaces interactivas en la terminal usando React Ink, sin servidor ni bundler de UI. Un único archivo dist/cli.js se instala como binario global scout.

El flujo de pantallas sigue una máquina de estados lineal: cada pantalla vive en src/commands/ como un componente React que recibe onDone/onBack como props y llama a navigate(nextScreen) para avanzar. El estado compartido (config, resultados, negocio seleccionado) vive en el contexto de App.

init → search → loading → results → coach → export
                    ↑_________|    │
                                   └─ (tecla e) → export (Excel)

Los servicios externos están encapsulados en src/services/:

| Servicio | Responsabilidad | |----------|----------------| | places.ts | Búsqueda en Google Places, deduplicación, filtro de webs y redes sociales | | gemini.ts | Generación de queries, scoring con IA, streaming del Coach, síntesis de propuesta | | scoring.ts | Score heurístico (base) + re-ranking con Gemini sobre los top-20 | | excel.ts | Exportación a .xlsx con ExcelJS | | config.ts | Persistencia de credenciales cifradas con AES-256-CBC vía conf |

Desarrollo local

git clone https://github.com/AndresSuarezz/scout
cd scout
pnpm install

pnpm run dev        # Watch mode: recompila al guardar
node dist/cli.js    # Prueba la CLI compilada

pnpm test           # Corre todos los tests
pnpm run typecheck  # Verifica tipos sin compilar
pnpm run lint       # ESLint sobre src/

Para probar la API de Google Places en aislado:

PLACES_KEY=tu_key npx tsx scripts/test-places.ts "Montería" "Restaurantes"

Troubleshooting

API key inválida — Verifica que la key tiene permisos para Places API o Generative Language API en Google Cloud Console.

Cuota agotada — Google Places tiene límite de requests por día en el plan gratuito. Espera 24h o actualiza el plan.

Modelo no disponible — Ejecuta scout init para seleccionar otro modelo Gemini.

La terminal se ve mal — Scout usa estilos ANSI. Asegúrate de usar una terminal moderna (Windows Terminal, iTerm2, cualquier terminal en Linux/macOS).

Sin resultados — Prueba con un nicho más amplio o una ciudad más grande.

Advertencia amarilla "banco de búsqueda con IA falló" — Gemini no pudo generar los queries optimizados (cuota, red, parseo). Scout cae al query simple "{nicho} en {ciudad}" y completa la búsqueda igualmente.

Advertencia amarilla "rerank con IA falló" — El rerank de Gemini falló. Los scores quedan calculados por la heurística local (sin website, rating y cantidad de reseñas). La lista sigue ordenada y exportable.

Config no se puede descifrar — Las credenciales están cifradas con una clave derivada del hostname y usuario actual. Si cambiaste de máquina o usuario, ejecuta scout init para reconfigurar.

Licencia

MIT © Andrés Suárez