gmp-cli

Что такое gmp-cli?

gmp-cli — это интерфейс командной строки для работы с сервисами Google Marketing Platform, включая GA4 (Google Analytics Data API), Google Search Console, Google Ads и Google Tag Manager. Основная цель — получать маркетинговые данные и детали конфигурации из терминала (или скриптов), а не вручную через веб-интерфейсы.

Проект создан с учетом «agent-friendly» рабочих процессов: поддерживается передача JSON-вывод в инструменты вроде jq, чтобы напрямую передавать результаты в AI-агент или обрабатывать их в shell-скриптах.

Ключевые возможности

• Единый CLI для нескольких сервисов GMP: GA4, Search Console, Google Ads и Tag Manager доступны через специальные подкоманды.
• Аутентификация и управление токенами: поддерживается OAuth-логин, токены хранятся в ~/.config/gmp-cli/tokens.json с автообновлением.
• Отчеты и фильтры GA4: запуск отчетов по метрикам/измерениям (например, сессии и показатель отказов по пути страницы) с диапазонами дат и фильтрами значений.
• Аналитика Search Console + проверка индекса: список верифицированных сайтов, отчеты по поисковой аналитике, проверка индексации URL и список карт сайта.
• Запросы Google Ads по производительности: список доступных аккаунтов (опционально через MCC), получение кампаний/групп объявлений/ключевых слов/поисковых запросов, выполнение сырых GAQL-запросов.
• Операции с рабочими пространствами Tag Manager: список аккаунтов/контейнеров, тегов/триггеров/переменных, получение опубликованных версий (включая выбор конкретного рабочего пространства).
• Структурированные форматы вывода: команды поддерживают -f / --format (например, таблица или CSV для отчетов GA4), чтобы результаты были удобны для скриптов.

Как использовать gmp-cli

1. Установите CLI из репозитория:

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

2. Настройте OAuth-аутентификацию (только первый раз):

   • Создайте проект в Google Cloud Console.
   • Включите необходимые API (Analytics Data API, Analytics Admin API, Search Console API для Search Console и Google Ads API для Ads).
   • Настройте экран согласия OAuth и создайте OAuth Client ID для Desktop app.
   • Используйте redirect URI http://localhost:3847/callback.
   • Аутентифицируйтесь через:
     • gmp auth set-credentials --client-id YOUR_ID --client-secret YOUR_SECRET
     • gmp auth login
     • gmp auth status

3. Добавьте учетные данные для конкретных сервисов:

   • Для Google Ads: укажите developer token командой gmp auth set-developer-token YOUR_DEVELOPER_TOKEN.
   • При использовании Manager Account (MCC): укажите login customer ID командой gmp auth set-login-customer-id 1234567890.

4. Запускайте отчеты и экспортируйте результаты с помощью соответствующих групп команд (например, gmp ga, gmp gsc, gmp ads, gmp gtm). Используйте -f для управления форматом вывода и перенаправляйте CSV в файлы при необходимости.

Сценарии использования

• Еженедельный обзор производительности GA4 в терминале: сгенерируйте сессии и показатель отказов по pagePath за последние 30 дней, затем экспортируйте как CSV для анализа в таблицах.
• Целевая аналитика GA4 с фильтрами: запустите тот же отчет GA4, но ограничьте результаты конкретным путем страницы (например, pagePath==/product) и задайте произвольный диапазон дат.
• Мониторинг запросов Search Console: список топ-запросов для верифицированного сайта за последние 28 дней или фильтрация по конкретному ключевому слову.
• Отчеты по производительности Google Ads для заинтересованных сторон: список кампаний за диапазон дат и таблицы производительности кампаний/групп объявлений/ключевых слов; опционально используйте GAQL для кастомного запроса метрик.
• Инвентаризация и аудит Tag Manager: список тегов, триггеров и переменных для конкретного контейнера/рабочего пространства и просмотр опубликованных версий.

FAQ

Где хранятся OAuth-токены?

Токены хранятся в ~/.config/gmp-cli/tokens.json и автоматически обновляются.

Нужен ли developer token для Google Ads?

Да. Настройка Google Ads API в проекте требует developer token в дополнение к OAuth-учетным данным.

Как выводить результаты для скриптов?

Многие команды принимают -f / --format для управления выводом. Для отчетов GA4 README показывает вывод в формате table или csv и демонстрирует перенаправление CSV в файл.

Можно ли запрашивать Google Ads через MCC?

README описывает настройку для MCC через gmp auth set-login-customer-id и предоставляет команды списка аккаунтов Ads с опцией MCC.

Как CLI поддерживает «agent-friendly» рабочие процессы?

Проект явно поддерживает передачу JSON-вывод в инструменты вроде jq, которые затем можно направить в AI-агент или использовать в shell-скриптах.

Альтернативы

• Официальные API Google (прямые вызовы): Вместо CLI-оболочки можно использовать API напрямую из кода. Это даёт максимальную гибкость, но требует самостоятельно реализовывать аутентификацию и логику запросов.
• Другие подходы к скриптингу извлечения данных: Можно писать скрипты, вызывающие сервисы Google через REST/официальные клиентские библиотеки, и форматировать результаты в JSON/CSV. Это похоже по целям автоматизации, но без готовой структуры команд.
• Веб-интерфейсы Tag Manager/GMP: Встроенный UI проще для разовых проверок. Однако он менее подходит для повторяемых, скриптовых рабочих процессов по сравнению с CLI.
• BI-инструменты для аналитики/отчётности: BI- или дашборд-инструменты централизуют отчёты и визуализацию. Они обычно акцентируют дашборды, а не терминальные пайплайны/автоматизацию, как в gmp-cli.