gmp-cli

gmp-cli 是什麼？

gmp-cli 是用於 Google Marketing Platform 服務的命令列介面，包含 GA4 (Google Analytics Data API)、Google Search Console、Google Ads 和 Google Tag Manager。其核心目的是讓您從終端機（或腳本）擷取行銷資料和設定細節，而非手動透過網頁 UI 操作。

專案以「代理友好」工作流程為設計考量：支援將 JSON 輸出 管道傳送到 jq 等工具，讓您直接將結果傳入 AI 代理或在 shell 腳本中處理。

主要功能

• 多個 GMP 服務的統一 CLI：透過專屬子指令存取 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 設定開發人員權杖。
   • 若使用經理帳戶 (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 網頁介面：使用內建 UI 對單次檢查更簡單。然而，相較 CLI，它較不適合可重複、腳本化的工作流程。
• Analytics/報表 BI 工具：BI 或儀表板工具可集中報表與視覺化。它們通常強調儀表板，而非 gmp-cli 所述的終端機優先管線/自動化工作流程。