gmp-cli

Cos'è gmp-cli?

gmp-cli è un'interfaccia a riga di comando per lavorare con i servizi di Google Marketing Platform, inclusi GA4 (Google Analytics Data API), Google Search Console, Google Ads e Google Tag Manager. Il suo scopo principale è consentire di recuperare dati di marketing e dettagli di configurazione dal terminale (o da script) invece che manualmente tramite interfacce web.

Il progetto è costruito con flussi di lavoro “agent-friendly” in mente: supporta il piping di output JSON a tool come jq, così puoi passare i risultati direttamente a un AI agent o elaborarli in script shell.

Caratteristiche Principali

• CLI unificata per più servizi GMP: GA4, Search Console, Google Ads e Tag Manager sono accessibili tramite sottocomandi dedicati.
• Autenticazione e gestione token: supportato login basato su OAuth, con token salvati in ~/.config/gmp-cli/tokens.json e auto-refresh.
• Reporting e filtraggio GA4: esegui report per metriche/dimensioni (es. sessioni e bounce rate per page path) con intervalli di date e filtri sui valori.
• Analytics Search Console + ispezione indice: elenca siti verificati, genera report analytics di ricerca, ispeziona indicizzazione URL e elenca sitemap.
• Query Google Ads per performance: elenca account accessibili (opzionalmente via MCC), recupera campagne/gruppi annunci/keyword/termini di ricerca e esegui query GAQL raw.
• Operazioni workspace Tag Manager: elenca account/container, elenca tag/trigger/variabili e recupera versioni pubblicate (inclusa selezione workspace specifico).
• Formati output strutturati: i comandi supportano -f / --format (es. table o CSV per report GA4) per rendere i risultati utilizzabili in script.

Come Usare gmp-cli

1. Installa la CLI dal repository:

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

2. Configura autenticazione OAuth (solo prima volta):

   • Crea un progetto in Google Cloud Console.
   • Abilita le API richieste (Analytics Data API, Analytics Admin API, Search Console API per Search Console e Google Ads API per Ads).
   • Configura lo schermo consenso OAuth e crea un OAuth Client ID per un'app Desktop.
   • Usa redirect URI http://localhost:3847/callback.
   • Autentica con:
     • gmp auth set-credentials --client-id YOUR_ID --client-secret YOUR_SECRET
     • gmp auth login
     • gmp auth status

3. Aggiungi credenziali specifiche per servizio:

   • Per Google Ads: imposta un developer token con gmp auth set-developer-token YOUR_DEVELOPER_TOKEN.
   • Se usi un Manager Account (MCC): imposta il login customer ID con gmp auth set-login-customer-id 1234567890.

4. Esegui report ed esporta risultati usando il gruppo di comandi rilevante (es. gmp ga, gmp gsc, gmp ads, gmp gtm). Usa -f per controllare il formato output e reindirizza output CSV a file quando necessario.

Casi d'Uso

• Revisione performance GA4 settimanale nel terminale: genera sessioni e bounce rate per pagePath negli ultimi 30 giorni, poi esporta come CSV per revisione in foglio di calcolo.
• Analisi GA4 mirata con filtri: esegui lo stesso report GA4 ma limita i risultati a un page path specifico (es. pagePath==/product) e imposta un intervallo date personalizzato.
• Monitoraggio query Search Console: elenca top query per un sito verificato negli ultimi 28 giorni, o filtra risultati per keyword specifica.
• Reporting performance Google Ads per stakeholder: elenca campagne per un intervallo date e recupera tabelle performance campagna/gruppo annunci/keyword; opzionalmente usa GAQL per query metrica custom.
• Inventario e audit Tag Manager: elenca tag, trigger e variabili per un container/workspace specifico e revisiona versioni pubblicate.

FAQ

Dove sono salvati i token OAuth?

I token sono salvati in ~/.config/gmp-cli/tokens.json e sono auto-refreshed.

Ho bisogno di un developer token Google Ads?

Sì. La configurazione Google Ads API descritta nel progetto richiede un developer token oltre alle credenziali OAuth.

Come outputto risultati per scripting?

Molti comandi accettano -f / --format per controllare l'output. Per report GA4, il README mostra output come table o csv e dimostra reindirizzamento output CSV a file.

Posso queryare Google Ads su un MCC?

Il README include setup MCC-specifico via gmp auth set-login-customer-id e fornisce comandi listing account Ads con opzione MCC.

Come supporta la CLI flussi di lavoro “agent-friendly”?

Il progetto supporta esplicitamente il piping di output JSON a tool come jq, che possono poi essere passati a un AI agent o usati in script shell.

Alternative

• API ufficiali di Google (chiamate dirette): Invece di un wrapper CLI, puoi usare le API direttamente dal tuo codice. Offre la massima flessibilità ma richiede di implementare tu l'autenticazione e la logica delle richieste.
• Altri approcci di scripting per estrazione dati: Puoi scrivere script che chiamano i servizi Google tramite REST/librerie client ufficiali e poi formattano i risultati in JSON/CSV. Simile negli obiettivi di automazione ma manca della struttura di comandi pronta all'uso.
• Interfacce web di Tag Manager/GMP: Usare l'interfaccia integrata può essere più semplice per controlli sporadici. Tuttavia, è meno adatta a workflow ripetibili e scriptabili rispetto a una CLI.
• Strumenti BI di analisi/reporting: Gli strumenti BI o di dashboarding possono centralizzare report e visualizzazioni. Tendono a enfatizzare i dashboard rispetto ai workflow di piping/automazione da terminale descritti per gmp-cli.