要点（最初に結論）
- Google Search Console と Google Analytics 4（GA4）を、ターミナルから操作できる CLI「gsc-ga4-cli」を作って OSS として公開しました。
- 検索パフォーマンス取得・URL検査・サイトマップ管理・GA4レポート・プロパティ管理などを1コマンドで実行できます。専用サブコマンドがない操作も
rawサブコマンドで API の全エンドポイントを呼び出せます。 - Python 版と Node.js 版（実行時依存ゼロ）の2実装を同一インターフェースで用意しました。
- Claude Code 用のスキルを同梱しているので、「先月の検索クエリ上位を見せて」のような依頼を AI エージェントにそのまま任せられます。
- リポジトリはこちらです。 https://github.com/nogataka/gsc-ga4-cli
はじめに
サイトの検索パフォーマンス確認やアクセス集計は、毎回ブラウザで Search Console と GA4 を開いて、画面を切り替えながら数字を拾う作業になりがちです。
私はこの確認作業を AI エージェント（Claude Code）に任せたいと考えていました。
ところが、gcloud のような公式 CLI は Search Console と GA4 には存在しません。
API 自体は両方とも公開されているので、「API でできる操作をひととおり CLI に落とし込み、ついでに AI エージェント用のスキルも付ける」という方針でツールを作りました。
この記事では、セットアップから主要コマンドの使い方、Claude Code との連携までを、読んだ方がそのまま使い始められる粒度で解説します。
対象読者は、次のいずれかに当てはまる方です。
- Search Console / GA4 の確認作業をコマンド1発にしたい方
- SEO レポートやアクセス集計を cron やスクリプトで自動化したい方
- Claude Code などの AI エージェントに自サイトの計測データを扱わせたい方
動作確認環境は次のとおりです（2026年7月時点）。
- Python 版: Python 3.13（3.9 以上で動作）+ google-auth 2.x
- Node.js 版: Node.js v24（18 以上で動作）・実行時依存パッケージなし
記事中のコマンド出力例は、ドメインやプロパティIDを example.com や 123456789 などのダミー値に置き換えています。コマンド自体はすべて実際に動かして確認したものです。
作ったもの
リポジトリは https://github.com/nogataka/gsc-ga4-cli です（MITライセンス）。
gsc と ga4 という2つのコマンドが入ります。
| コマンド | 対応API | 主な操作 |
|---|---|---|
gsc |
Search Console API | 検索パフォーマンス、URL検査、サイトマップ、プロパティ管理 |
ga4 |
GA4 Data API + Admin API | レポート、リアルタイム、アカウント/プロパティ/ストリーム管理 |
設計面では次の3点にこだわりました。
1. 専用サブコマンド＋raw パススルーの二段構え
よく使う操作（レポート取得や URL 検査など）は専用サブコマンドにして、オプションで直感的に呼べるようにしました。
一方で、API には数が多くて全部をサブコマンド化しにくいエンドポイント（Google広告リンク、オーディエンス管理など）もあります。
そこで両コマンドに raw METHOD PATH という汎用サブコマンドを用意し、任意のエンドポイントを呼び出せるようにしました。
この構成なら、API 側に新機能が追加されても CLI の改修を待たずに使えます。
2. 人間と AI エージェントの両方が読める出力
レポートや一覧などの取得系コマンドは、既定では整形されたテーブルで表示し、--json を付ければ API の生レスポンスをそのまま出力します（get や raw のように常に JSON を返すコマンドもあります）。
集計スクリプトや AI エージェントには JSON、目視確認にはテーブル、という使い分けができます。
3. 破壊的操作のガード
プロパティやサイトマップの削除系コマンドは、--yes を明示しない限り実行されません。
AI エージェントに操作を任せる前提のツールなので、不可逆な操作には一段ブレーキを入れています。
なお、実装は Claude Code と対話しながら進めました。
コードの生成は AI に任せつつ、コマンド体系の設計と、全コマンドを実データで動かす動作確認は人間側で行っています。
インストール
Python 版と Node.js 版のどちらか使いやすいほうを選んでください。
主要なコマンド名・オプション・出力形式は共通です（引数解析などの細部には実装差があります）。
Node.js 版は実行時依存パッケージがゼロなので、Node.js 18 以上さえあれば追加インストールなしで動きます。
# Node.js 版
npm install -g gsc-ga4-cli
Python 版は Python 3.9 以上と Git が前提です。
環境によってはシステム Python への pip インストールが制限されているため、その場合は pipx を使ってください。
# Python 版
python3 -m pip install git+https://github.com/nogataka/gsc-ga4-cli.git
# または
pipx install git+https://github.com/nogataka/gsc-ga4-cli.git
インストール後、gsc --help / ga4 --help が表示されれば準備完了です。
セットアップ（サービスアカウントの用意）
このツールはサービスアカウント方式で認証します。
OAuth のようにブラウザでの同意画面を毎回経由しないため、スクリプトや AI エージェントからの実行に向いています。
初回だけ次の4ステップが必要です。
1. サービスアカウントを作成する
Google Cloud コンソールの「IAMと管理 → サービスアカウント」で新規作成し、JSONキーをダウンロードします。
プロジェクトは既存のものでも新規でも構いません。
ダウンロードした JSON キーは秘密情報なので、リポジトリ管理下に置かないよう注意してください。
2. API を有効化する
同じ Google Cloud プロジェクトで、次の3つの API を有効化します。
- Search Console API（
searchconsole.googleapis.com） - Google Analytics Data API（
analyticsdata.googleapis.com） - Google Analytics Admin API（
analyticsadmin.googleapis.com）
有効化を忘れた場合でも、CLI が 403 エラーから有効化ページの URL を抽出して表示します。
「動かしてみてエラーの案内に従う」進め方でも大丈夫です。
3. データへのアクセス権を付与する
サービスアカウントのメールアドレス（xxx@プロジェクト名.iam.gserviceaccount.com）を、閲覧したいデータ側に登録します。
Google Cloud 側の設定だけでは自分のサイトのデータは見えず、このステップを忘れると 403 エラーになります。
- Search Console: 対象プロパティの「設定 → ユーザーと権限」でメールアドレスを追加します（レポート閲覧だけなら制限付きでも動作しますが、サイトマップ送信などまで使うならフル権限を推奨します）
- GA4: 「管理 → プロパティのアクセス管理」でメールアドレスを追加します
- レポート取得や設定の参照だけなら閲覧者で足ります
- プロパティやデータストリームの作成・変更・削除まで使う場合は編集者以上が必要です
4. 設定ファイルを置く
~/.config/gsc-ga4-cli/config.json を作成します。
最初は JSON キーのパスだけで動きます。
{
"key_file": "/path/to/service-account-key.json"
}
この状態で gsc sites list と ga4 summaries を実行すると、アクセスできるサイトと GA4 プロパティIDが確認できます。
確認できた値を default_site と default_property に追記しておくと、以降は --site や --property を毎回書かずに済みます（どちらも任意項目です）。
{
"key_file": "/path/to/service-account-key.json",
"default_site": "sc-domain:example.com",
"default_property": "123456789"
}
-
default_siteは Search Console のプロパティ名です。ドメインプロパティはsc-domain:example.com、URLプレフィックスプロパティはhttps://example.com/の形式です -
default_propertyは GA4 のプロパティID（数値）です - 複数サイトを扱う場合は、コマンド実行時にオプションで上書きできます
Search Console を操作する（gsc コマンド）
検索パフォーマンスを取得する
いちばん使う機会が多いのは検索アナリティクスの取得だと思います。
引数なしなら「直近28日・検索クエリ別」で取得します。
gsc query
query clicks impressions ctr position
------------------- ------ ----------- ----- --------
サンプルクエリ1 12 340 3.53% 4.2
サンプルクエリ2 8 120 6.67% 2.1
...
(24 rows, 2026-06-18..2026-07-15, site=sc-domain:example.com)
ディメンションや期間、フィルタを組み合わせられます。
# ページ別・期間指定
gsc query --dimensions page --start 2026-06-01 --end 2026-06-30
# 「blog」を含むクエリだけに絞る（フィルタは複数指定でAND）
gsc query --dimensions query,page --filter "query contains blog" --row-limit 100
# 日別の推移（クリック数・表示回数のトレンド確認）
gsc query --dimensions date
# Google Discover のパフォーマンス
gsc query --type discover --dimensions page
--dimensions には query, page, country, device, date, searchAppearance, hour を指定できます。
このうち hour（時間別）だけは速報データ専用のため、--data-state hourly_all との併用が必要です。
フィルタの演算子は contains / notContains / equals / notEquals / includingRegex / excludingRegex の6種類で、正規表現も使えます。
集計に回したいときは --json を付けると API の生レスポンスが得られます。
gsc query --dimensions date --json > search-performance.json
URL検査でインデックス状態を確認する
「このページ、インデックスされてる？」をコマンド1発で確認できます。
gsc inspect https://example.com/some-page
URL: https://example.com/some-page
verdict: PASS
coverageState: 送信して登録されました
indexingState: INDEXING_ALLOWED
robotsTxtState: ALLOWED
pageFetchState: SUCCESSFUL
lastCrawlTime: 2026-07-15T14:14:18Z
googleCanonical: https://example.com/some-page
userCanonical: https://example.com/some-page
console: https://search.google.com/search-console/inspect?...
最終クロール日時や、Google が認識している canonical URL まで分かります。
リライト後に再クロールされたかの確認や、新規ページのインデックス状況の定点観測に便利です。
サイトマップを管理する
# 登録済みサイトマップの一覧（送信数・インデックス数・エラー数が見える）
gsc sitemaps list
# サイトマップの送信（再送信も同じコマンド）
gsc sitemaps submit https://example.com/sitemap.xml
sitemaps list では「送信した URL 数」と「インデックスされた数」の差が見えます。
私の場合、この差分がきっかけでインデックス未登録ページの存在に気づけたので、定期実行してウォッチする使い方をおすすめします。
専用コマンドがない操作は raw で呼ぶ
Search Console API のエンドポイントであれば何でも呼び出せます。
gsc raw GET /webmasters/v3/sites
gsc raw POST "/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query" \
--json '{"startDate":"2026-07-01","endDate":"2026-07-14","dimensions":["query"]}'
GA4 を操作する（ga4 コマンド）
まずプロパティ一覧を確認する
GA4 の操作にはプロパティIDが必要です。
最初に summaries で、サービスアカウントがアクセスできるアカウントとプロパティを確認します。
ga4 summaries
account property propertyId type
---------- -------------- -------------------- ----------------------
MyAccount My Website properties/123456789 PROPERTY_TYPE_ORDINARY
ここで得た数値ID（123456789）を config の default_property に入れておくと、以降のコマンドで --property を省略できます。
レポートを取得する
引数なしなら「直近28日・日別のアクティブユーザー / ページビュー / セッション」を取得します。
ga4 report
date activeUsers screenPageViews sessions
-------- ----------- --------------- --------
20260701 35 48 39
20260702 28 41 30
...
(28 rows shown / 28 total)
ディメンション・指標・並び順・フィルタを組み合わせると、管理画面で見る主要レポートは一通り再現できます。
# ページ別PVランキング上位20
ga4 report --dimensions pagePath --metrics screenPageViews \
--order-by screenPageViews --desc --limit 20
# 流入元別セッション
ga4 report --dimensions sessionSource,sessionMedium --metrics sessions,activeUsers
# ランディングページ別（期間指定つき。keyEvents はキーイベント数）
ga4 report --dimensions landingPage --metrics sessions,keyEvents \
--start 2026-06-01 --end 2026-06-30
# 「/blog」配下だけ、かつセッション10超のページに絞る
ga4 report --dimensions pagePath --filter "pagePath^=/blog" --metric-filter "sessions>10"
フィルタの演算子は ==（完全一致）、*=（含む）、^=（前方一致）、$=（後方一致）、~=（正規表現）です。
日付には 2026-06-01 のような固定日のほか、7daysAgo / yesterday / today という相対指定も使えます。
どんなディメンション・指標が使えるかは metadata で確認できます。
カスタムディメンションを定義している場合も、ここに出てくる apiName をそのまま指定できます。
ga4 metadata
リアルタイムと管理系
# いまサイトにいるアクティブユーザー
ga4 realtime
# データストリームと測定ID（G-XXXXXXX）の確認
ga4 streams list
# キーイベント（旧コンバージョン）の定義一覧
ga4 key-events list
# データ保持期間の確認
ga4 data-retention get
data-retention get は個人的に一度確認しておくことをおすすめします。
GA4 のイベントデータ保持期間は既定で2か月に設定されており、探索レポートで過去比較をする場合は14か月への変更を検討する余地があるためです。
高度なレポートと raw
ピボット・ファネルなどの複雑なレポートは、リクエストボディを JSON で直接渡す方式にしています。
ga4 pivot --json @pivot-request.json
ga4 funnel --json @funnel-request.json
Admin API / Data API の任意エンドポイントも呼び出せます。
ga4 raw GET /properties/123456789/googleAdsLinks
ga4 raw GET /properties/123456789/audienceLists --api data --version v1alpha
Claude Code から使う（スキル同梱）
ここからが個人的な本命です。
リポジトリの skills/ ディレクトリに、Claude Code 用のスキル定義（SKILL.md）を同梱しています。
Claude Code のスキルは「この種の依頼が来たら、このツールをこう使う」という手順書のようなものです。
スキルは npm / pip のパッケージには含まれないため、リポジトリを取得してスキルディレクトリにコピーします。
git clone --depth 1 https://github.com/nogataka/gsc-ga4-cli.git
mkdir -p ~/.claude/skills
cp -r gsc-ga4-cli/skills/gsc-cli gsc-ga4-cli/skills/ga4-cli ~/.claude/skills/
導入すると、Claude Code への自然言語の依頼が CLI 実行に変換されるようになります。
たとえば次のような依頼が、そのまま通ります。
- 「先月の検索クエリ上位20を見せて」 →
gsc queryを期間・件数指定で実行 - 「トップページのインデックス状態を確認して」 →
gsc inspectを実行 - 「今月のPVを流入元別にまとめて」 →
ga4 reportを実行して集計・整形
スキルには、コマンドリファレンスだけでなく運用上の注意も書き込んであります。
たとえば「削除系コマンドは実行前に必ずユーザーへ確認する」というルールをスキル側に持たせているため、エージェントが勝手にプロパティを消すような事故を防ぎやすくなっています。
CLI と直接関係のない話ですが、この「ツール＋スキルをセットで配る」形は他のツールにも応用できると感じています。
CLI の README を人間向けに書き、SKILL.md をエージェント向けに書く、という役割分担です。
つまずきやすいポイント
セットアップで詰まりやすい箇所をまとめます。
| 症状 | 原因 | 対処 |
|---|---|---|
| 403 + 有効化URLが表示される | Google Cloud プロジェクトで API が未有効 | 表示された URL から API を有効化する |
| 403 + アクセス管理の案内 | サービスアカウントがデータ側に未登録 | Search Console の「ユーザーと権限」/ GA4 の「アクセス管理」に追加する |
gsc query が0行 |
データ反映のタイムラグ | Search Console のデータは2〜3日遅れます。--data-state all で速報値を含められます |
| 指標名のエラー | ディメンション・指標の apiName 誤り |
ga4 metadata で正確な名前を確認する |
| 想定と違うヘルプが出る | npm 上の同名の別パッケージと bin 名が衝突 |
which gsc / which ga4 で実体のパスを確認する |
API 有効化やアクセス権付与の反映には数分かかることがあります。
設定直後に 403 が出ても、少し待ってから再実行すると通る場合があります。
まとめ
Search Console と GA4 の操作をターミナルで完結させる CLI「gsc-ga4-cli」を紹介しました。
サービスアカウントの用意さえ済ませれば、検索パフォーマンスの取得からインデックス確認、GA4 のレポートまでコマンド1発で実行できます。
raw サブコマンドがあるので、専用コマンド化されていない API 操作もカバーできます。
Claude Code を使っている方は、スキルの導入までセットで試していただくのが手軽だと思います。
「数字の確認はエージェントに聞く」という体験は、一度慣れると管理画面には戻りにくくなりました。
リポジトリはこちらです。issue や PR も歓迎します。
https://github.com/nogataka/gsc-ga4-cli