gmp-cli

Qu'est-ce que gmp-cli ?

gmp-cli est une interface en ligne de commande pour travailler avec les services Google Marketing Platform, incluant GA4 (Google Analytics Data API), Google Search Console, Google Ads et Google Tag Manager. Son objectif principal est de vous permettre de récupérer des données marketing et des détails de configuration depuis votre terminal (ou des scripts) plutôt que manuellement via les interfaces web.

Le projet est conçu avec des workflows « agent-friendly » en tête : il supporte le pipe de sortie JSON vers des outils comme jq, pour passer directement les résultats à un agent IA ou les traiter dans des scripts shell.

Fonctionnalités principales

• CLI unifiée pour plusieurs services GMP : GA4, Search Console, Google Ads et Tag Manager sont accessibles via des sous-commandes dédiées.
• Authentification et gestion des tokens : Connexion basée sur OAuth, avec tokens stockés dans ~/.config/gmp-cli/tokens.json et actualisation automatique.
• Rapports et filtres GA4 : Exécutez des rapports pour métriques/dimensions (ex. : sessions et taux de rebond par chemin de page) avec plages de dates et filtres de valeurs.
• Analyses Search Console + inspection d'index : Listez les sites vérifiés, générez des rapports d'analyses de recherche, inspectez l'indexation d'URL et listez les sitemaps.
• Requêtes Google Ads pour performances : Listez les comptes accessibles (optionnellement via MCC), récupérez campagnes/groupes publicitaires/mots-clés/termes de recherche, et exécutez des requêtes GAQL brutes.
• Opérations sur espaces de travail Tag Manager : Listez comptes/conteneurs, listez tags/triggers/variables, et récupérez les versions publiées (y compris sélection d'un espace spécifique).
• Formats de sortie structurés : Les commandes supportent -f / --format (ex. : table ou CSV pour rapports GA4) pour rendre les résultats utilisables dans des scripts.

Comment utiliser gmp-cli

1. Installez la CLI depuis le dépôt :

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

2. Configurez l'authentification OAuth (première fois uniquement) :

   • Créez un projet dans Google Cloud Console.
   • Activez les API requises (Analytics Data API, Analytics Admin API, Search Console API pour Search Console, et Google Ads API pour Ads).
   • Configurez l'écran de consentement OAuth et créez un OAuth Client ID pour une application de bureau.
   • Utilisez l'URI de redirection http://localhost:3847/callback.
   • Authentifiez-vous via :
     • gmp auth set-credentials --client-id YOUR_ID --client-secret YOUR_SECRET
     • gmp auth login
     • gmp auth status

3. Ajoutez des identifiants spécifiques aux services :

   • Pour Google Ads : définissez un developer token avec gmp auth set-developer-token YOUR_DEVELOPER_TOKEN.
   • Si utilisation d'un Manager Account (MCC) : définissez l'ID client de connexion avec gmp auth set-login-customer-id 1234567890.

4. Exécutez des rapports et exportez les résultats en utilisant le groupe de commandes pertinent (ex. : gmp ga, gmp gsc, gmp ads, gmp gtm). Utilisez -f pour contrôler le format de sortie et redirigez la sortie CSV vers des fichiers si nécessaire.

Cas d'usage

• Revue hebdomadaire des performances GA4 dans le terminal : Générez sessions et taux de rebond par pagePath pour les 30 derniers jours, puis exportez en CSV pour analyse dans un tableur.
• Analyse GA4 ciblée avec filtres : Exécutez le même rapport GA4 mais limitez les résultats à un chemin de page spécifique (ex. : pagePath==/product) et définissez une plage de dates personnalisée.
• Surveillance des requêtes Search Console : Listez les meilleures requêtes pour un site vérifié sur les 28 derniers jours, ou filtrez par mot-clé spécifique.
• Rapports de performances Google Ads pour parties prenantes : Listez les campagnes sur une plage de dates et récupérez les tableaux de performances campagne/groupe publicitaire/mot-clé ; utilisez optionnellement GAQL pour une requête métrique personnalisée.
• Inventaire et audit Tag Manager : Listez tags, triggers et variables pour un conteneur/espace spécifique et examinez les versions publiées.

FAQ

Où sont stockés les tokens OAuth ?

Les tokens sont stockés dans ~/.config/gmp-cli/tokens.json et sont actualisés automatiquement.

Ai-je besoin d'un developer token Google Ads ?

Oui. La configuration de l'API Google Ads décrite dans le projet requiert un developer token en plus des identifiants OAuth.

Comment sortir les résultats pour des scripts ?

De nombreuses commandes acceptent -f / --format pour contrôler la sortie. Pour les rapports GA4, le README montre des sorties en table ou csv et démontre la redirection de sortie CSV vers un fichier.

Puis-je interroger Google Ads via un MCC ?

Le README inclut une configuration spécifique MCC via gmp auth set-login-customer-id et fournit des commandes de liste de comptes Ads avec option MCC.

Comment la CLI supporte-t-elle les workflows « agent-friendly » ?

Le projet supporte explicitement le pipe de sortie JSON vers des outils comme jq, qui peuvent ensuite être fournis à un agent IA ou utilisés dans des scripts shell.

Alternatives

• API officielles de Google (appels directs) : Au lieu d'un wrapper CLI, vous pouvez utiliser les API directement depuis votre code. Cela offre une flexibilité maximale mais nécessite de construire vous-même l'authentification et la logique de requêtes.
• Autres approches de scripting d'extraction de données : Vous pouvez écrire des scripts qui appellent les services Google via REST/bibliothèques clientes officielles, puis formater les résultats en JSON/CSV. Cela est similaire en termes d'objectifs d'automatisation mais manque de structure de commandes prête à l'emploi.
• Interfaces web Tag Manager/GMP : Utiliser l'UI intégrée peut être plus simple pour des vérifications ponctuelles. Cependant, elle est moins adaptée aux workflows répétables et scriptables par rapport à une CLI.
• Outils BI d'analyse/reporting : Les outils BI ou de tableaux de bord peuvent centraliser les rapports et la visualisation. Ils mettent généralement l'accent sur les dashboards plutôt que sur les workflows de piping/automation en terminal décrits pour gmp-cli.