gmp-cli

Was ist gmp-cli?

gmp-cli ist eine Kommandozeilen-Schnittstelle für Google Marketing Platform-Dienste, einschließlich GA4 (Google Analytics Data API), Google Search Console, Google Ads und Google Tag Manager. Der Hauptzweck ist es, Marketingdaten und Konfigurationsdetails direkt aus dem Terminal (oder Skripten) abzurufen, statt manuell über Weboberflächen.

Das Projekt ist mit „agentenfreundlichen“ Workflows konzipiert: Es unterstützt das Weiterleiten von JSON-Ausgaben an Tools wie jq, sodass Ergebnisse direkt an einen AI-Agenten weitergegeben oder in Shell-Skripten verarbeitet werden können.

Wichtige Funktionen

• Einheitliche CLI für mehrere GMP-Dienste: GA4, Search Console, Google Ads und Tag Manager werden über dedizierte Unterbefehle angesprochen.
• Authentifizierung und Token-Management: OAuth-basierter Login mit Speicherung der Tokens in ~/.config/gmp-cli/tokens.json und automatischer Erneuerung.
• GA4-Reporting und Filterung: Berichte für Metriken/Dimensionen (z. B. Sessions und Bounce Rate nach Page Path) mit Datumsbereichen und Wertfiltern.
• Search Console-Analyse + Index-Prüfung: Verifizierte Sites auflisten, Search-Analytics-Berichte erstellen, URL-Indexierung prüfen und Sitemaps auflisten.
• Google Ads-Abfragen für Performance: Zugängliche Accounts auflisten (optional via MCC), Kampagnen/Werbegruppen/Keywords/Search Terms abrufen und rohe GAQL-Abfragen ausführen.
• Tag Manager-Workspace-Operationen: Accounts/Container auflisten, Tags/Trigger/Variablen auflisten und veröffentlichte Versionen abrufen (inkl. Auswahl eines spezifischen Workspaces).
• Strukturierte Ausgabeformate: Befehle unterstützen -f / --format (z. B. Tabelle oder CSV für GA4-Berichte), um Ergebnisse skriptbar zu machen.

So verwenden Sie gmp-cli

1. CLI installieren aus dem Repository:

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

2. OAuth-Authentifizierung einrichten (nur beim ersten Mal):

   • Projekt in der Google Cloud Console erstellen.
   • Erforderliche APIs aktivieren (Analytics Data API, Analytics Admin API, Search Console API für Search Console und Google Ads API für Ads).
   • OAuth-Zustimmungsbildschirm konfigurieren und eine OAuth Client ID für eine Desktop-App erstellen.
   • Redirect-URI http://localhost:3847/callback verwenden.
   • Authentifizieren via:
     • gmp auth set-credentials --client-id YOUR_ID --client-secret YOUR_SECRET
     • gmp auth login
     • gmp auth status

3. Dienst-spezifische Credentials hinzufügen:

   • Für Google Ads: Developer Token mit gmp auth set-developer-token YOUR_DEVELOPER_TOKEN setzen.
   • Bei Verwendung eines Manager Accounts (MCC): Login-Kunden-ID mit gmp auth set-login-customer-id 1234567890 setzen.

4. Berichte ausführen und Ergebnisse exportieren mit der relevanten Befehlsgruppe (z. B. gmp ga, gmp gsc, gmp ads, gmp gtm). -f für Ausgabeformat steuern und CSV-Ausgabe bei Bedarf in Dateien umleiten.

Anwendungsfälle

• Wöchentliche GA4-Performance-Überprüfung im Terminal: Sessions und Bounce Rate nach pagePath für die letzten 30 Tage generieren, dann als CSV für Tabellenkalkulation exportieren.
• Ge zielte GA4-Analyse mit Filtern: Gleichen GA4-Bericht ausführen, aber Ergebnisse auf einen spezifischen Page Path beschränken (z. B. pagePath==/product) und benutzerdefinierten Datumsbereich setzen.
• Search Console-Query-Monitoring: Top-Queries für eine verifizierte Site für die letzten 28 Tage auflisten oder nach spezifischem Query-Keyword filtern.
• Google Ads-Performance-Reporting für Stakeholder: Kampagnen für einen Datumsbereich auflisten und Kampagnen-/Werbegruppen-/Keyword-Performance-Tabellen abrufen; optional GAQL für benutzerdefinierte Metriken nutzen.
• Tag Manager-Inventar und Audit: Tags, Trigger und Variablen für einen spezifischen Container/Workspace auflisten und veröffentlichte Versionen prüfen.

FAQ

Wo werden OAuth-Tokens gespeichert?

Tokens werden in ~/.config/gmp-cli/tokens.json gespeichert und automatisch erneuert.

Brauche ich einen Google Ads Developer Token?

Ja. Die Google Ads API-Einrichtung im Projekt erfordert neben OAuth-Credentials einen Developer Token.

Wie gebe ich Ergebnisse für Skripte aus?

Viele Befehle akzeptieren -f / --format zur Ausgabesteuerung. Für GA4-Berichte zeigt das README table oder csv und demonstriert die Umleitung von CSV in eine Datei.

Kann ich Google Ads über ein MCC abfragen?

Das README enthält MCC-spezifische Einrichtung via gmp auth set-login-customer-id und Ads-Account-Auflistungs-Befehle mit MCC-Option.

Wie unterstützt die CLI „agentenfreundliche“ Workflows?

Das Projekt unterstützt explizit das Weiterleiten von JSON-Ausgaben an Tools wie jq, die dann in einen AI-Agenten eingespeist oder in Shell-Skripten verwendet werden können.

Alternativen

• Offizielle Google-APIs (direkte Aufrufe): Statt eines CLI-Wrappers können Sie die APIs direkt aus Ihrem Code nutzen. Das bietet maximale Flexibilität, erfordert aber den eigenen Aufbau von Authentifizierung und Anfragenlogik.
• Andere Skriptansätze zur Datenextraktion: Sie können Skripte schreiben, die Google-Dienste über REST/offizielle Client-Bibliotheken aufrufen und Ergebnisse als JSON/CSV formatieren. Das ist ähnlich in den Automatisierungszielen, fehlt aber die fertige Befehlsstruktur.
• Tag Manager/GMP-Weboberflächen: Die integrierte UI kann für einmalige Überprüfungen einfacher sein. Sie eignet sich jedoch weniger für wiederholbare, skriptbare Workflows im Vergleich zu einer CLI.
• Analytics-/Reporting-BI-Tools: BI- oder Dashboard-Tools können Reporting und Visualisierung zentralisieren. Sie legen typischerweise den Fokus auf Dashboards statt auf terminalbasierte Pipelines/Automatisierungs-Workflows wie bei gmp-cli.