pp-google-search-console

Google Search Console — Printing Press CLI

前提条件：CLI をインストールする

このスキルは google-search-console-pp-cli バイナリを使用します。**このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。**インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使用してインストールします。バイナリのインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin がデフォルトです。

   npx -y @mvanhorn/printing-press-library install google-search-console --cli-only
   

2. 確認します：google-search-console-pp-cli --version
3. 報告されたインストールディレクトリが、このスキルを実行するエージェント／ランタイムの $PATH に含まれていることを確認します。

npx でのインストールに失敗した場合（Node がない、オフラインなど）は、Go で直接インストールしてください（Go 1.26.6 以降が必要です）。

go install github.com/mvanhorn/printing-press-library/library/marketing/google-search-console/cmd/google-search-console-pp-cli@latest

インストール後に --version が「command not found」と報告する場合、ランタイムからバイナリディレクトリを $PATH 経由で参照できていません。確認に成功するまで、スキルのコマンドを実行しないでください。

この CLI を使う場面

ウェブ UI を介さずに、エージェントが Google Search Console のプロパティに関する SEO の質問に答える必要があるときは、この CLI を使用してください。期間を指定して上位のクエリやページを取得する、期間を比較する、インデックス登録やサイトマップの悪化を見つける、2 ページ目からの改善候補や流入が減少しているページ、キーワードのカニバリゼーションを見つける、または同期履歴がある場合に API の16か月の取得期間より古いデータについて質問に答える、といった用途に適しています。同期がまだ実行されていない状態で一度限りのアドホックな検索を行う場合には適していません。まず sync を実行してください。

独自の機能

この API 用の他のツールでは、以下の機能を利用できません。

ローカルコーパスから SEO の機会を発見

• quick-wins — インプレッション数が多く CTR が低い、2 ページ目のクエリを提示します。同期済みのコーパスからオフラインで算出し、伸びしろの大きい1ページ目への浮上候補を順位付けします。

  API から再取得せずに、エージェントがプロパティの SEO の機会を上位から提案する必要があるときに使用してください。

  google-search-console-pp-cli quick-wins sc-domain:example.com --position 8-20 --min-imps 100 --json
  

• cannibalization — 複数のページが競合するクエリを、合計インプレッション数の多い順に見つけます。GSC のウェブ UI にはない、キーワードのカニバリゼーション監査機能です。

  クエリの順位が予想より低い理由をエージェントが調査するときに使用してください。同じ URL 上で競合するページを提示します。

  google-search-console-pp-cli cannibalization sc-domain:example.com --min-imps 50 --top 25 --json
  

• outliers — 独自のコーパスで観測された掲載順位別 CTR 曲線から、CTR が外れているクエリやページを見つけます。

  エージェントが直接対処できる、タイトルタグやスニペットの書き換え候補です。インプレッション数が多く、掲載順位に対して CTR が低いものを特定します。

  google-search-console-pp-cli outliers sc-domain:example.com --metric ctr --sigma 2 --top 50 --json
  

時系列分析

• compare — 任意のディメンションについて、クリック数、インプレッション数、CTR、掲載順位の期間ごとの差分を表示します。週次、月次、または任意の期間を比較できます。

  プロパティのトラフィックが変化したときの最初の調査に適しています。エージェントは2つの生のクエリを掘り下げずに差分を取得できます。

  google-search-console-pp-cli compare sc-domain:example.com --period 28d --vs prev-period --dim query --top 50 --agent --select rows.keys,rows.delta_clicks,rows.delta_position
  

• cliff — クリック数やインプレッション数が急落した日を見つけ、同日に起きたサイトマップの問題やインデックス登録数の減少との関連を示す手がかりを提示します。

  人が「トラフィックが落ちた」と伝えたときに、エージェントが最初に実行するコマンドです。該当日と考えられる原因を示します。

  google-search-console-pp-cli cliff sc-domain:example.com --metric clicks --threshold -25% --window 7d
  

• historical — API の過去16か月のローリング期間より古い日付範囲の検索アナリティクスを検索し、キャッシュされた履歴から「2024年3月は平年並みか？」という質問に答えます。

  予測や季節性に関する質問に適しています。単発のエージェントでも、バックアップファイルを取り出さずに「2年前と比べてどうか」に答えられます。

  google-search-console-pp-cli historical sc-domain:example.com --start 2023-01-01 --end 2023-12-31 --dim query --top 100
  

プロパティをまたいだ分析

• roll-up — 1つのコマンドで、確認済みのすべてのプロパティにわたる上位のクエリやページを集計します。API では N 回の往復が必要です。

  エージェントがサイトごとのループを書くことなく、ポートフォリオ全体の好調なページを提示する代理店向けワークフローに適しています。

  google-search-console-pp-cli roll-up --metric clicks --group-by query --top 50 --last 28d --json
  

インデックス登録の診断

• coverage-drift — 期間内に検査状態が変化した URL（インデックス登録済み → 未登録、robots の変更、canonical の変更）。

  状態が元に戻ると API から確認できなくなるため、エージェントが見逃してしまうインデックス登録の後退を検出します。

  google-search-console-pp-cli coverage-drift sc-domain:example.com --field indexingState --days 30 --json
  

• sitemap-watch — スナップショット間でサイトマップの状態を比較し、新たなエラーや警告、コンテンツ数の減少、古い lastDownloaded 時刻を検出します。

  次の月曜日にトラフィックが落ちる前にサイトマップの後退を検出する、金曜日の自動処理です。ローカルデータで実行されるため、追加の API 費用はかかりません。

  google-search-console-pp-cli sitemap-watch sc-domain:example.com --since 7d --json
  

コンテンツのワークフロー

• decaying — ローリング期間にわたってクリック数が単調に減少しているページを、合計表示回数 × 負の傾きでランク付けします。コンテンツ更新候補のキューです。

  コンテンツマーケター向けの木曜日の更新キューです。エージェントが、具体的な裏付けとなる数値をもとに更新候補を選びます。

  google-search-console-pp-cli decaying sc-domain:example.com --window 90d --min-imps 500 --top 50 --json
  

• new-queries — 過去 N 日間に表示回数を獲得し始めた、それ以前はコーパスに存在しなかったクエリです。新たな需要を把握できます。

  マーケター向けのコンテンツ案を見つける機能です。エージェントは一般的な Trends データではなく、このサイトに絞った新たな検索トレンドを取得できます。

  google-search-console-pp-cli new-queries sc-domain:example.com --since 28d --min-imps 50 --top 100 --json
  

コマンドリファレンス

url-inspection — Google 検索における URL のインデックス登録状況を検査します

• google-search-console-pp-cli url-inspection — Google が認識する単一 URL の情報を返します。インデックス登録状況、最終クロール時刻、canonical URL（Google が選択した URL と...

webmasters — ウェブマスターを管理します

• google-search-console-pp-cli webmasters add-site — Search Console におけるユーザーのサイト一覧にサイトを追加します。サイトの確認は別途（DNS 経由で...）行う必要があります。
• google-search-console-pp-cli webmasters delete-site — ユーザーの Search Console のサイト一覧からサイトを削除します。Google が収集したデータは削除されません。
• google-search-console-pp-cli webmasters delete-sitemap — サイトマップ レポートからサイトマップを削除します。サイトマップがまだ...の場合、Google によるクロールは停止しません。
• google-search-console-pp-cli webmasters get-site — ユーザーの権限レベルを含む、特定の確認済みサイトの情報を取得します。
• google-search-console-pp-cli webmasters get-sitemap — 警告、エラー、最終送信時刻／ダウンロード時刻など、特定のサイトマップの情報を取得します。
• google-search-console-pp-cli webmasters list-sitemaps — このサイトに送信されたサイトマップ、またはサイトマップ インデックス ファイルに含まれるサイトマップ（sitemapIndex が...で指定されている場合）を一覧表示します。
• google-search-console-pp-cli webmasters list-sites — 認証済みユーザーが Search Console でアクセスできるすべてのサイト（ドメイン プロパティまたは URL プレフィックス プロパティ）を返します。
• google-search-console-pp-cli webmasters query-search-analytics — 指定したディメンション（クエリ、ページ、国など）ごとにグループ化したクリック数、表示回数、CTR、平均掲載順位を返します。
• google-search-console-pp-cli webmasters submit-sitemap — サイトのサイトマップを送信します。サイトマップ URL は siteUrl と同じサイト上の絶対 URL である必要があります。送信は...

適切なコマンドを見つける

実行したい内容はわかっていても、どのコマンドを使えばよいかわからない場合は、CLI に直接問い合わせてください。

google-search-console-pp-cli which "<capability in your own words>"

which は自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 件の一致があることを示し、終了コード 2 は確信を持てる一致がないことを示します。その場合は --help に切り替えるか、より絞り込んだ問い合わせを使用してください。

レシピ

CTR が低い上位クエリ — title タグの書き換え候補

google-search-console-pp-cli outliers sc-domain:example.com --metric ctr --sigma 2 --top 50 --agent --select rows.keys,rows.position,rows.ctr,rows.expected_ctr

--agent（コンパクトな NDJSON）と --select を組み合わせて応答を絞り込み、エージェントが ApiDataRow オブジェクト全体を確認しなくて済むようにします。ディメンションと、その掲載順位の区分平均に対する CTR の差分のみを出力します。

昨日、トラフィックが減少した理由は？

google-search-console-pp-cli cliff sc-domain:example.com --metric clicks --threshold -20% --window 14d --json

クリック数が前日比で 20% を超えて減少した日と、サイトマップ（新たなエラー）および url_inspections（インデックス登録状態の変化）からの同日シグナルを返します。SEO の事後分析で最もよくある質問に、1 つのコマンドで回答できます。

プロパティ横断の週間サマリー

google-search-console-pp-cli roll-up --metric clicks --group-by query --last 7d --top 25 --csv > weekly.csv

確認済みのすべてのプロパティで、過去7日間のクリック数上位25件のクエリを集計します。CSVはそのままスプレッドシートやデータツールに渡せます。

ファイルからの一括 URL 検査

google-search-console-pp-cli url-inspection inspect-batch --file urls.txt --site sc-domain:example.com --max-per-day 2000 --json

1行につき1件の検査結果を NDJSON でストリーミングします。プロパティごとの1日あたりの上限を遵守します。jq 'select(.indexStatusResult.coverageState != "Submitted and indexed")' に渡すと、問題のある項目だけを抽出できます。

新しいページを公開する前のカニバリゼーション監査

google-search-console-pp-cli cannibalization sc-domain:example.com --min-imps 50 --top 20 --json

サイト内の複数のページがすでに競合している既存のクエリを表示します。同じトピックの新しいコンテンツを公開する前に実行し、既存のページのうち最も有力なものを選ぶか、内容を統合してください。

認証の設定

方法は2つあります。

推奨：auth login — ブラウザーを使った一度限りのログインで、その後は自動的にトークンが更新されます。

google-search-console-pp-cli auth set-client <client_id> <client_secret>   # 5-min Google Cloud Console setup, then run once
google-search-console-pp-cli auth login                                    # browser flow, persists refresh token
google-search-console-pp-cli auth login --no-browser                       # WSL2/SSH/headless variant
google-search-console-pp-cli auth login --scope write                      # opt into sitemap submit / site add+delete

auth login の後は、保存されたリフレッシュトークンを使って、各コマンドが有効期間1時間のアクセストークンを自動的に更新します。ユーザーに再びトークンが表示されることはありません。Google Cloud Console の詳しい手順については README.md を参照してください。

CI／単発スクリプト向け：GSC_ACCESS_TOKEN — OAuth Playground から取得してエクスポートし、実行します。トークンの有効期間は1時間で、自動更新はありません。

export GSC_ACCESS_TOKEN="ya29..."   # https://developers.google.com/oauthplayground/

どちらの方法も併用できます。両方が設定されている場合、環境変数が保存済みのファイルトークンより優先されます。

google-search-console-pp-cli doctor を実行して設定を確認してください。auth status では、リフレッシュトークンの有無と有効期限までの残り時間を確認できます。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションが有効になります：--json --compact --no-input --no-color --yes。

• パイプで利用可能 — 標準出力に JSON、標準エラー出力にエラーを出力します

• フィルタリング可能 — --select でフィールドを絞り込めます。ドット区切りのパスでネストされた構造をたどり、配列では各要素をたどります。出力が多い API でコンテキストを小さく保つために重要です：

  google-search-console-pp-cli url-inspection --inspection-url https://example.com/resource --agent --select id,name,status
  

• 事前確認可能 — --dry-run で、送信せずにリクエストを表示します

• 非対話型 — プロンプトは表示せず、入力はすべてフラグで指定します

• リトライの明示 — すでに存在する項目の作成を成功として扱う場合に限り --idempotent を、削除対象が存在しない場合の削除を成功として扱う場合に限り --ignore-missing を使用します

エージェントからのフィードバック

この CLI について気になる点に気づいた場合（エージェントが気づいた場合も含む）は、記録してください。

google-search-console-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
google-search-console-pp-cli feedback --stdin < notes.txt
google-search-console-pp-cli feedback list --json --limit 10

記録はローカルの ~/.google-search-console-pp-cli/feedback.jsonl に保存されます。GOOGLE_SEARCH_CONSOLE_FEEDBACK_ENDPOINT が設定されており、かつ --send が渡されているか GOOGLE_SEARCH_CONSOLE_FEEDBACK_AUTO_SEND=true が設定されている場合を除き、POST されることはありません。デフォルトではローカルのみに保存されます。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1行で記録します。それが積み重なっていく情報になります。

出力の送信先

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて（または標準出力の代わりに）指定した送信先に送られるため、エージェントはコマンド結果を手動でパイプに渡さずに振り分けられます。次の3つの送信先に対応しています：

送信先	動作
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（tmp + rename）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

未対応のスキームは、対応する送信先を示す構造化エラーとともに拒否されます。Webhook の送信に失敗すると、ゼロ以外の終了コードを返し、URL と HTTP ステータスを標準エラー出力に記録します。

名前付きプロファイル

プロファイルは、コマンド実行間で再利用できるフラグ値の保存セットです。スケジュールされたエージェントが同じ設定で毎回同じコマンドを実行する場合に使用します。HeyGen の「Beacon」パターンがその例です。

google-search-console-pp-cli profile save briefing --json
google-search-console-pp-cli --profile briefing url-inspection --inspection-url https://example.com/resource
google-search-console-pp-cli profile list --json
google-search-console-pp-cli profile show briefing
google-search-console-pp-cli profile delete briefing --yes

明示的に指定したフラグは、常にプロファイルの値より優先されます。プロファイルの値はデフォルト値より優先されます。agent-context は、すべての利用可能なプロファイルを available_profiles に一覧表示するため、情報を調べるエージェントは実行時にプロファイルを検出できます。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が誤っています）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → google-search-console-pp-cli --help の出力を表示します
2. install で始まる → mcp で終わる場合は → MCP のインストール。それ以外の場合は → 上記の前提条件を確認してください
3. それ以外 → 直接使用（--agent を付けて CLI コマンドとして実行します）

MCP サーバーのインストール

この CLI の公開ライブラリーエントリーまたはビルド済みリリースから MCP バイナリーをインストールし、登録します。

claude mcp add google-search-console-pp-mcp -- google-search-console-pp-mcp

確認：claude mcp list

直接使用

1. インストール済みか確認します：which google-search-console-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある前提条件を参照してください）。
2. ユーザーのクエリーに最適なコマンドを、上記の「固有の機能とコマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します。

   google-search-console-pp-cli <command> [subcommand] [args] --agent
   

4. あいまいな場合は、サブコマンドのヘルプを確認します：google-search-console-pp-cli <command> --help。