Scout CLI

CLI de prospección técnica: encuentra negocios sin sitio web y genera PRDs asistidos por IA.

Instalación

npm install -g @asuarezz/scout

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

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

# Windows
winget install OpenJS.NodeJS.LTS

Alternativa — instalador shell:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/AndresSuarezz/scout/main/install.sh | bash

# Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/AndresSuarezz/scout/main/install.ps1 | iex

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. Scout consulta Google Places y filtra los que no tienen sitio web
3. Seleccionas un prospecto con las flechas del teclado
4. Chateas con la IA para definir el alcance del proyecto
5. Escribes /done y se genera un PRD_nombre-del-negocio.md

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: 5 minutos

1. Ve a console.cloud.google.com e inicia sesión con tu cuenta de Google.
2. Crea un proyecto nuevo (o selecciona uno existente) — click en el selector de proyectos arriba → Nuevo proyecto.
3. En el menú lateral ve a APIs y servicios → Biblioteca.
4. Busca "Places API" y haz click en Habilitar.
5. Ve a APIs y servicios → Credenciales → Crear credenciales → Clave de API.
6. Copia la key generada.

Límite gratuito: 200 USD de crédito mensual para nuevas cuentas (~2.000 búsquedas de texto gratuitas). Para uso de prospección ocasional nunca llegarás al límite.

Recomendado: en la consola puedes restringir la key para que solo funcione con Places API — click en la key → Restricciones de API → selecciona Places API.

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: gemini-1.5-flash y gemini-2.0-flash tienen cuota gratuita generosa (hasta 1.500 requests/día en el tier gratuito). Para generar PRDs 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

Comandos dentro del chat:

| Comando | Acción | |---------|--------| | /done | Genera el PRD con la conversación actual | | /back | Vuelve a la lista de prospectos | | /save | Guarda el transcript sin generar PRD |

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. Los modelos marcados con ★ son los recomendados por costo/velocidad.

Para cambiar el modelo sin reconfigurar todo:

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

Desarrollo local

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

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

npm test           # Corre los tests
npm run typecheck  # Verifica tipos

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.

Licencia

MIT © Andrés Suárez