gmp-cli

gmp-cliとは？

gmp-cliは、Google Marketing Platformのサービス（GA4 (Google Analytics Data API)、Google Search Console、Google Ads、Google Tag Managerを含む）を操作するためのコマンドラインインターフェースです。主な目的は、Web UIを手動で操作するのではなく、ターミナル（またはスクリプト）からマーケティングデータや設定詳細を取得することです。

このプロジェクトは「エージェント対応」のワークフローを念頭に構築されており、JSON出力をjqなどのツールにパイプして、AIエージェントに直接渡したり、シェルスクリプトで処理したりできます。

主な機能

• 複数の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用Search Console API、Ads用Google Ads API）。
   • OAuth同意画面を設定し、デスクトップアプリ用のOAuthクライアント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インベントリと監査: 特定コンテナ/ワークスペースのタグ、トリガー、変数一覧と公開バージョンのレビュー。

FAQ

OAuthトークンはどこに保存される？

トークンは~/.config/gmp-cli/tokens.jsonに保存され、自動更新されます。

Google Ads開発者トークンは必要？

はい。プロジェクトのGoogle Ads API設定では、OAuth認証情報に加えて開発者トークンが必要です。

スクリプト用に出力するには？

多くのコマンドで-f / --formatを指定可能。GA4レポートではREADMEにtableやcsv出力例とCSVのファイルリダイレクトを示しています。

MCC経由でGoogle Adsをクエリ可能？

READMEにgmp auth set-login-customer-idによるMCC設定とMCCオプション付きアカウント一覧コマンドを記載。

CLIは「エージェント対応」ワークフローをどうサポート？

プロジェクトはJSON出力をjqなどにパイプすることを明示的にサポートし、AIエージェントやシェルスクリプトに活用可能。

代替案

• Google公式API（直接呼び出し）: CLIラッパーの代わりに、コードからAPIを直接使用できます。最大の柔軟性がありますが、認証やリクエストロジックを自分で構築する必要があります。
• その他のデータ抽出スクリプト手法: REST/公式クライアントライブラリ経由でGoogleサービスを呼び出し、結果をJSON/CSV形式に整形するスクリプトを作成できます。自動化の目標は似ていますが、すぐに使えるコマンド構造がありません。
• Tag Manager/GMPウェブインターフェース: ビルトインUIは一回限りの確認にシンプルです。ただし、CLIに比べて繰り返し実行可能なスクリプト化ワークフローに適していません。
• Analytics/レポートBIツール: BIやダッシュボードツールはレポートと可視化を一元化できます。通常、gmp-cliで説明されるターミナル優先のパイプライン/自動化ワークフローよりダッシュボードを重視します。