gmp-cli

gmp-cli 是什么？

gmp-cli 是一个用于操作 Google Marketing Platform 服务的命令行界面，支持 GA4 (Google Analytics Data API)、Google Search Console、Google Ads 和 Google Tag Manager。其核心目的是让您从终端（或脚本）中获取营销数据和配置详情，而非手动通过 Web 界面操作。

该项目针对“代理友好”工作流设计：支持将 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（例如，GA4 报告的表格或 CSV），便于脚本使用结果。

如何使用 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 同意屏幕，并为 Desktop app 创建 OAuth Client ID。
   • 使用重定向 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：使用 gmp auth set-developer-token YOUR_DEVELOPER_TOKEN 设置开发者令牌。
   • 如果使用 Manager Account (MCC)：使用 gmp auth set-login-customer-id 1234567890 设置登录客户 ID。

4. 运行报告并导出结果：使用相关命令组（例如，gmp ga、gmp gsc、gmp ads、gmp gtm）。使用 -f 控制输出格式，并在需要时将 CSV 输出重定向到文件。

使用场景

• 终端中每周 GA4 性能审查：生成过去 30 天按 pagePath 的会话数和跳出率，然后导出为 CSV 用于电子表格审查。
• 带过滤器的针对性 GA4 分析：运行相同 GA4 报告，但限制结果到特定页面路径（例如，pagePath==/product），并设置自定义日期范围。
• Search Console 查询监控：列出过去 28 天已验证站点的顶级查询，或按特定查询关键词过滤结果。
• 面向利益相关者的 Google Ads 性能报告：列出日期范围内的广告系列，并拉取广告系列/广告组/关键词性能表格；可选使用 GAQL 进行自定义指标查询。
• Tag Manager 库存和审计：列出特定容器/工作区的标签、触发器和变量，并审查已发布版本。

常见问题

OAuth 令牌存储在哪里？

令牌存储在 ~/.config/gmp-cli/tokens.json，并自动刷新。

我需要 Google Ads 开发者令牌吗？

是的。项目中描述的 Google Ads API 设置除了 OAuth 凭据外，还需要 developer token。

如何为脚本输出结果？

许多命令接受 -f / --format 控制输出。对于 GA4 报告，README 显示输出为 table 或 csv，并演示将 CSV 输出重定向到文件。

我可以在 MCC 中查询 Google Ads 吗？

README 包含通过 gmp auth set-login-customer-id 的 MCC 特定设置，并提供带 MCC 选项的 Ads 账户列出命令。

CLI 如何支持“代理友好”工作流？

项目明确支持将 JSON 输出 管道传输到 jq 等工具，然后输入 AI 代理或用于 shell 脚本。

替代方案

• Google 官方 API（直接调用）：不使用 CLI 封装，您可以直接在代码中使用 API。这提供最大灵活性，但需要自行构建认证和请求逻辑。
• 其他数据提取脚本方法：您可以编写脚本通过 REST/官方客户端库调用 Google 服务，然后将结果格式化为 JSON/CSV。这在自动化目标上类似，但缺少现成的命令结构。
• Tag Manager/GMP Web 界面：使用内置 UI 对于一次性检查更简单。但是，与 CLI 相比，它不太适合可重复的、可脚本化的工作流。
• Analytics/报告 BI 工具：BI 或仪表板工具可以集中报告和可视化。它们通常强调仪表板，而非 gmp-cli 描述的终端优先管道/自动化工作流。