seo-google Checked

| Tier | Detection | Available Commands |

|------|-----------|-------------------|

| **0** (API Key) | api_key present | pagespeed, crux, crux-history, youtube, nlp, entity, safety |

| **1** (OAuth/SA) | + OAuth token or service account | Tier 0 + gsc, inspect, sitemaps, index |

| **2** (Full) | + ga4_property_id configured | Tier 1 + ga4, ga4-pages, ga4-referrals, ga4-channel-mix, ga4-properties |

| **3** (Ads) | + ads_developer_token + ads_customer_id | Tier 2 + keywords, volume |

Always communicate the detected tier before running commands.

Quick Reference

| Command | What it does | Tier |

|---------|-------------|------|

| setup | Check/configure API credentials | -- |

| pagespeed <url> | PSI Lighthouse + CrUX field data | 0 |

| crux <url> | CrUX field data only (p75 metrics) | 0 |

| crux-history <url> | 25-week CWV trend analysis | 0 |

| gsc <property> | Search Console: clicks, impressions, CTR, position | 1 |

| inspect <url> | URL Inspection: index status, canonical, crawl info | 1 |

| inspect-batch <file> | Batch URL Inspection from file | 1 |

| sitemaps <property> | GSC sitemap status | 1 |

| index <url> | Submit URL to Indexing API | 1 |

| index-batch <file> | Batch submit up to 200 URLs | 1 |

| ga4 [property-id] | GA4 organic traffic report | 2 |

| ga4-pages [property-id] | Top organic landing pages | 2 |

| ga4-referrals [property-id] | Referral sessions by source — AI assistants by default | 2 |

| ga4-channel-mix [property-id] | Sessions split by channel group (Direct / Organic / Referral / Paid …) | 2 |

| ga4-properties | List every GA4 account + property the service account can read | 2 |

| youtube <query> | YouTube video search (views, likes, duration) | 0 |

| youtube-video <id> | YouTube video details + top comments | 0 |

| nlp <url-or-text> | NLP entity extraction + sentiment + classification | 0 |

| entities <url-or-text> | Entity analysis only (for E-E-A-T) | 0 |

| keywords <seed> | Keyword ideas from Google Ads Keyword Planner | 3 |

| volume <keywords> | Search volume lookup from Keyword Planner | 3 |

| entity <query> | Knowledge Graph entity check | 0 |

| safety <url> | Web Risk URL safety check | 0 |

| quotas | Show rate limits for all APIs | -- |

| report <type> | Generate a PDF/HTML/XLSX report from collected JSON | -- |

---

PageSpeed + CrUX

### pagespeed <url>

Combined Lighthouse lab data + CrUX field data.

**Script:** python scripts/pagespeed_check.py <url> --json

**Reference:** references/pagespeed-crux-api.md

**Default:** Both mobile + desktop strategies, all Lighthouse categories.

Output merges lab scores (point-in-time Lighthouse) with field data (28-day Chrome user metrics). CrUX tries URL-level first, falls back to origin-level.

### crux <url>

CrUX field data only (no Lighthouse run). Faster.

**Script:** python scripts/pagespeed_check.py <url> --crux-only --json

### crux-history <url>

25-week CrUX History trends. Shows whether CWV metrics are improving, stable, or degrading.

**Script:** python scripts/crux_history.py <url> --json

**Reference:** references/pagespeed-crux-api.md

Output includes per-metric trend direction, percentage change, and weekly p75 values.

---

Search Console

### gsc <property>

Search Analytics: clicks, impressions, CTR, position for last 28 days.

**Script:** python scripts/gsc_query.py --property <property> --json

**Reference:** references/search-console-api.md

**Default:** 28 days, dimensions=query,page, type=web, limit=1000.

Includes quick-win detection: queries at position 4-10 with high impressions.

**Filtering:** --device {desktop,mobile,tablet}, --country <ISO3>, --page <url-or-substring> (defaults to contains match; pass --page-match equals for exact-URL match). Combine for per-URL query analysis: --page /blog/best-ai-seo-tools/ --dimensions query.

**AI Overview / AI Mode:** --ai-overview (or --ai-mode) filters results to queries where Google rendered an AI Overview / AI Mode SERP that included one of your URLs. This is Google's first-party answer to *"are we cited in AI Overview?"* — clicks, impressions, CTR, and avg position straight from GSC. Combine with --dimensions query,page to see which queries+pages earned AI Overview presence, or with --page /post/ to scope to one URL. For other appearance types (RICH_RESULT, REVIEW_SNIPPET, etc.) use --search-appearance <value>.

### inspect <url>

URL Inspection: real indexation status from Google.

**Script:** python scripts/gsc_inspect.py <url> --json

Returns: verdict (PASS/FAIL), coverage state, robots.txt status, indexing state, page fetch state, canonical selection, mobile usability, rich results.

### inspect-batch <file>

Batch inspection from a file (one URL per line). Rate limited to 2,000/day per site.

**Script:** python scripts/gsc_inspect.py --batch <file> --json

### sitemaps <property>

List submitted sitemaps with status, errors, warnings.

**Script:** python scripts/gsc_query.py sitemaps --property <property> --json

---

Indexing API

### index <url>

Notify Google of a URL update.

**Script:** python scripts/indexing_notify.py <url> --json

**Reference:** references/indexing-api.md

The Indexing API is officially for JobPosting and BroadcastEvent/VideoObject pages. Always inform the user of this restriction. Daily quota: 200 publish requests.

### index-batch <file>

Batch submit URLs from a file. Tracks quota usage.

**Script:** python scripts/indexing_notify.py --batch <file> --json

---

GA4 Traffic

All GA4 reports accept an optional --page <path-or-url> flag to scope the report to a single landing page (EXACT match against GA4's landingPage dimension; full URLs are auto-stripped to path). Use it whenever the question is "how is *this* post performing?" rather than site-wide.

--report organic and --report top-pages accept --channel <name|all>: defaults to organic (Organic Search), pass all to drop the channel filter (required for whole-page weekly trends across all traffic sources), or any GA4 default channel group verbatim — Direct, Referral, Paid Search, Organic Social, etc.

### ga4 [property-id]

Daily