gmp-cli

¿Qué es gmp-cli?

gmp-cli es una interfaz de línea de comandos para trabajar con servicios de Google Marketing Platform, incluyendo GA4 (Google Analytics Data API), Google Search Console, Google Ads y Google Tag Manager. Su propósito principal es permitirte obtener datos de marketing y detalles de configuración desde la terminal (o scripts) en lugar de manualmente a través de interfaces web.

El proyecto está diseñado con flujos de trabajo “compatibles con agentes” en mente: soporta el uso de tuberías con salida JSON hacia herramientas como jq, para pasar resultados directamente a un agente de IA o procesarlos en scripts de shell.

Características principales

• CLI unificada para múltiples servicios GMP: GA4, Search Console, Google Ads y Tag Manager se acceden mediante subcomandos dedicados.
• Autenticación y gestión de tokens: Soporta inicio de sesión basado en OAuth, con tokens almacenados en ~/.config/gmp-cli/tokens.json y renovación automática.
• Informes y filtros de GA4: Ejecuta informes para métricas/dimensiones (p. ej., sesiones y tasa de rebote por ruta de página) con rangos de fechas y filtros de valores.
• Análisis de Search Console + inspección de índice: Lista sitios verificados, genera informes de análisis de búsquedas, inspecciona indexación de URL y lista sitemaps.
• Consultas de Google Ads para rendimiento: Lista cuentas accesibles (opcionalmente vía MCC), recupera campañas/grupos de anuncios/palabras clave/términos de búsqueda, y ejecuta consultas GAQL directas.
• Operaciones en espacios de trabajo de Tag Manager: Lista cuentas/contenedores, lista etiquetas/desencadenadores/variables, y recupera versiones publicadas (incluyendo selección de un espacio de trabajo específico).
• Formatos de salida estructurados: Los comandos admiten -f / --format (por ejemplo, tabla o CSV para informes de GA4) para hacer los resultados utilizables en scripts.

Cómo usar gmp-cli

1. Instala la CLI desde el repositorio:

   • git clone https://github.com/lucianfialho/gmp-cli.git
   • cd gmp-cli
   • npm install
   • npm run build
   • npm link

2. Configura la autenticación OAuth (solo la primera vez):

   • Crea un proyecto en Google Cloud Console.
   • Habilita las APIs requeridas (Analytics Data API, Analytics Admin API, Search Console API para Search Console, y Google Ads API para Ads).
   • Configura la pantalla de consentimiento OAuth y crea un OAuth Client ID para una aplicación de escritorio.
   • Usa el URI de redirección http://localhost:3847/callback.
   • Autentícate mediante:
     • gmp auth set-credentials --client-id YOUR_ID --client-secret YOUR_SECRET
     • gmp auth login
     • gmp auth status

3. Agrega credenciales específicas del servicio:

   • Para Google Ads: establece un token de desarrollador con gmp auth set-developer-token YOUR_DEVELOPER_TOKEN.
   • Si usas una Cuenta de Administrador (MCC): establece el ID de cliente de inicio de sesión con gmp auth set-login-customer-id 1234567890.

4. Ejecuta informes y exporta resultados usando el grupo de comandos relevante (p. ej., gmp ga, gmp gsc, gmp ads, gmp gtm). Usa -f para controlar el formato de salida y redirige la salida CSV a archivos cuando sea necesario.

Casos de uso

• Revisión semanal de rendimiento GA4 en la terminal: genera sesiones y tasa de rebote por pagePath para los últimos 30 días, luego exporta como CSV para revisión en hojas de cálculo.
• Análisis dirigido de GA4 con filtros: ejecuta el mismo informe de GA4 pero restringe resultados a una ruta de página específica (p. ej., pagePath==/product) y establece un rango de fechas personalizado.
• Monitoreo de consultas de Search Console: lista las principales consultas para un sitio verificado en los últimos 28 días, o filtra resultados por una palabra clave específica.
• Informes de rendimiento de Google Ads para interesados: lista campañas para un rango de fechas y extrae tablas de rendimiento de campaña/grupo de anuncios/palabra clave; opcionalmente usa GAQL para una consulta de métrica personalizada.
• Inventario y auditoría de Tag Manager: lista etiquetas, desencadenadores y variables para un contenedor/espacio de trabajo específico y revisa versiones publicadas.

Preguntas frecuentes

¿Dónde se almacenan los tokens OAuth?

Los tokens se almacenan en ~/.config/gmp-cli/tokens.json y se renuevan automáticamente.

¿Necesito un token de desarrollador de Google Ads?

Sí. La configuración de la API de Google Ads descrita en el proyecto requiere un token de desarrollador además de las credenciales OAuth.

¿Cómo genero salidas para scripting?

Muchos comandos aceptan -f / --format para controlar la salida. Para informes de GA4, el README muestra salidas como table o csv y demuestra redirigir la salida CSV a un archivo.

¿Puedo consultar Google Ads a través de un MCC?

El README incluye configuración específica para MCC mediante gmp auth set-login-customer-id y proporciona comandos de listado de cuentas de Ads con opción de MCC.

¿Cómo soporta la CLI flujos de trabajo “compatibles con agentes”?

El proyecto soporta explícitamente el uso de tuberías con salida JSON hacia herramientas como jq, que luego pueden alimentar un agente de IA o usarse en scripts de shell.

Alternativas

• APIs oficiales de Google (llamadas directas): En lugar de un envoltorio CLI, puedes usar las APIs directamente desde tu código. Esto ofrece máxima flexibilidad, pero requiere construir tú mismo la autenticación y lógica de solicitudes.
• Otros enfoques de scripting para extracción de datos: Puedes escribir scripts que llamen a servicios de Google vía REST/bibliotecas oficiales de cliente y luego formateen resultados como JSON/CSV. Es similar en objetivos de automatización, pero carece de la estructura de comandos lista para usar.
• Interfaces web de Tag Manager/GMP: Usar la UI integrada puede ser más simple para verificaciones puntuales. Sin embargo, es menos adecuada para flujos de trabajo repetibles y scriptables en comparación con una CLI.
• Herramientas BI de análisis/informes: Las herramientas BI o de paneles pueden centralizar informes y visualización. Suelen enfatizar paneles en lugar de flujos de trabajo de piping/automatización desde terminal como los descritos para gmp-cli.