gmp-cli

O que é o gmp-cli?

gmp-cli é uma interface de linha de comando para trabalhar com serviços do Google Marketing Platform, incluindo GA4 (Google Analytics Data API), Google Search Console, Google Ads e Google Tag Manager. Seu propósito principal é permitir que você busque dados de marketing e detalhes de configuração pelo terminal (ou scripts), em vez de manualmente pelas interfaces web.

O projeto é construído com fluxos de trabalho “amigáveis a agentes” em mente: ele suporta o pipe de saída JSON para ferramentas como jq, para que você possa passar resultados diretamente para um agente de IA ou processá-los em scripts de shell.

Principais Recursos

• CLI unificada para múltiplos serviços GMP: GA4, Search Console, Google Ads e Tag Manager são acessados via subcomandos dedicados.
• Autenticação e gerenciamento de tokens: Suporte a login baseado em OAuth, com tokens armazenados em ~/.config/gmp-cli/tokens.json e auto-refresh.
• Relatórios e filtros do GA4: Execute relatórios para métricas/dimensões (ex.: sessões e taxa de rejeição por caminho de página) com intervalos de datas e filtros de valor.
• Análises do Search Console + inspeção de índice: Liste sites verificados, gere relatórios de análises de busca, inspecione indexação de URL e liste sitemaps.
• Consultas do Google Ads para desempenho: Liste contas acessíveis (opcionalmente via MCC), recupere campanhas/grupos de anúncios/palavras-chave/termos de busca e execute consultas GAQL raw.
• Operações em workspaces do Tag Manager: Liste contas/contêineres, liste tags/gatilhos/variáveis e recupere versões publicadas (incluindo seleção de um workspace específico).
• Formatos de saída estruturados: Comandos suportam -f / --format (por exemplo, tabela ou CSV para relatórios GA4) para tornar os resultados utilizáveis em scripts.

Como Usar o gmp-cli

1. Instale a CLI do repositório:

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

2. Configure a autenticação OAuth (apenas na primeira vez):

   • Crie um projeto no Google Cloud Console.
   • Ative as APIs necessárias (Analytics Data API, Analytics Admin API, Search Console API para Search Console e Google Ads API para Ads).
   • Configure a tela de consentimento OAuth e crie um OAuth Client ID para um Desktop app.
   • Use o URI de redirecionamento http://localhost:3847/callback.
   • Autentique via:
     • gmp auth set-credentials --client-id YOUR_ID --client-secret YOUR_SECRET
     • gmp auth login
     • gmp auth status

3. Adicione credenciais específicas do serviço:

   • Para Google Ads: defina um developer token com gmp auth set-developer-token YOUR_DEVELOPER_TOKEN.
   • Se usando uma Manager Account (MCC): defina o login customer ID com gmp auth set-login-customer-id 1234567890.

4. Execute relatórios e exporte resultados usando o grupo de comandos relevante (ex.: gmp ga, gmp gsc, gmp ads, gmp gtm). Use -f para controlar o formato de saída e redirecione saída CSV para arquivos quando necessário.

Casos de Uso

• Revisão semanal de desempenho GA4 no terminal: Gere sessões e taxa de rejeição por pagePath para os últimos 30 dias, depois exporte como CSV para análise em planilhas.
• Análise direcionada do GA4 com filtros: Execute o mesmo relatório GA4, mas restrinja resultados a um caminho de página específico (ex.: pagePath==/product) e defina um intervalo de datas personalizado.
• Monitoramento de consultas do Search Console: Liste as principais consultas para um site verificado nos últimos 28 dias, ou filtre resultados por uma palavra-chave específica.
• Relatórios de desempenho do Google Ads para stakeholders: Liste campanhas para um intervalo de datas e extraia tabelas de desempenho de campanha/grupo de anúncios/palavra-chave; opcionalmente use GAQL para uma consulta de métrica personalizada.
• Inventário e auditoria do Tag Manager: Liste tags, gatilhos e variáveis para um contêiner/workspace específico e revise versões publicadas.

FAQ

Onde os tokens OAuth são armazenados?

Os tokens são armazenados em ~/.config/gmp-cli/tokens.json e são auto-refrescados.

Preciso de um developer token do Google Ads?

Sim. A configuração da Google Ads API descrita no projeto exige um developer token além das credenciais OAuth.

Como gero saídas para scripts?

Muitos comandos aceitam -f / --format para controlar a saída. Para relatórios GA4, o README mostra saída como table ou csv e demonstra redirecionamento de saída CSV para um arquivo.

Posso consultar Google Ads em um MCC?

O README inclui configuração específica para MCC via gmp auth set-login-customer-id e fornece comandos de listagem de contas Ads com opção de MCC.

Como a CLI suporta fluxos de trabalho “amigáveis a agentes”?

O projeto suporta explicitamente o pipe de saída JSON para ferramentas como jq, que podem então ser alimentadas em um agente de IA ou usadas em scripts de shell.

Alternativas

• APIs oficiais do Google (chamadas diretas): Em vez de um wrapper CLI, você pode usar as APIs diretamente no seu código. Isso oferece máxima flexibilidade, mas exige construir autenticação e lógica de requisições por conta própria.
• Outras abordagens de scripts para extração de dados: Você pode escrever scripts que chamam serviços do Google via REST/bibliotecas oficiais de cliente e formatam resultados como JSON/CSV. É similar nos objetivos de automação, mas sem a estrutura de comandos pronta.
• Interfaces web do Tag Manager/GMP: Usar a UI integrada pode ser mais simples para verificações pontuais. No entanto, é menos adequada para fluxos de trabalho repetíveis e scriptáveis em comparação com uma CLI.
• Ferramentas de BI para análise/relatórios: Ferramentas de BI ou dashboards podem centralizar relatórios e visualizações. Elas geralmente enfatizam dashboards em vez de fluxos de automação via terminal como os descritos para o gmp-cli.