pp-google-search-console

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/marketing/google-search-console/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Google Search Console — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `google-search-console-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install google-search-console --cli-only
   ```
2. Verify: `google-search-console-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

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

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for this CLI when an agent needs to answer SEO questions for a Google Search Console property without round-tripping to the web UI. It is the right choice for: pulling top queries and pages for any window; comparing periods; finding indexing or sitemap regressions; surfacing page-2 quick wins, decaying pages, or keyword cannibalization; and answering questions about data older than the API's 16-month window once a sync history exists. It is not the right choice for one-off ad-hoc lookups when a sync hasn't run -- start with `sync` first.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### SEO opportunities from local corpus
- **`quick-wins`** — Surface page-2 queries with high impressions and low CTR -- page-2-to-page-1 candidates ranked by upside, computed offline from your synced corpus.

  _Reach for this when an agent needs to recommend the top SEO opportunities for a property without re-fetching from the API._

  ```bash
  google-search-console-pp-cli quick-wins sc-domain:example.com --position 8-20 --min-imps 100 --json
  ```
- **`cannibalization`** — Find queries where multiple pages compete, ranked by combined impressions -- the keyword-cannibalization audit the GSC web UI doesn't offer.

  _Use when an agent investigates why a query ranks worse than expected -- surfaces the competing pages on its own URL._

  ```bash
  google-search-console-pp-cli cannibalization sc-domain:example.com --min-imps 50 --top 25 --json
  ```
- **`outliers`** — Queries or pages with click-through rates that deviate from the observed CTR-by-position curve in your own corpus.

  _Title-tag and snippet-rewrite candidates an agent can act on directly -- high impressions, low CTR for their position._

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

### Time-series analysis
- **`compare`** — Period-over-period delta on clicks, impressions, CTR, and position for any dimension -- week-over-week, month-over-month, or arbitrary windows.

  _First-line investigation when a property's traffic shifts -- the agent gets the deltas without spelunking two raw queries._

  ```bash
  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`** — Find the day clicks or impressions cratered, with signature hints matching same-day sitemap regressions or indexing drops.

  _The first command an agent should run when a human says 'traffic dropped' -- points at the day and likely cause._

  ```bash
  google-search-console-pp-cli cliff sc-domain:example.com --metric clicks --threshold -25% --window 7d
  ```
- **`historical`** — Search analytics for date ranges older than the API's 16-month rolling window -- answer 'is this March-2024 normal?' from cached history.

  _Forecasting and seasonality questions; a one-shot agent can answer 'compared to two years ago' without breaking out a backup file._

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

### Cross-property analysis
- **`roll-up`** — Aggregate top queries or pages across every verified property in one command -- the API forces N round-trips.

  _Agency workflows where the agent surfaces top performers across a portfolio without writing per-site loops._

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

### Indexing diagnostics
- **`coverage-drift`** — URLs whose inspection state flipped (indexed → not indexed, robots changed, canonical changed) within a window.

  _Catches indexing regressions an agent would otherwise miss because the API hides them once the state has flipped back._

  ```bash
  google-search-console-pp-cli coverage-drift sc-domain:example.com --field indexingState --days 30 --json
  ```
- **`sitemap-watch`** — Diff sitemap state between snapshots -- surface new errors, new warnings, content-count drops, and stale lastDownloaded times.

  _Friday automation that catches sitemap regressions before the next Monday traffic dip -- runs from local data, no extra API spend._

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

### Content workflows
- **`decaying`** — Pages with monotonic click decline over a rolling window, ranked by total impressions × negative slope -- the content-refresh queue.

  _Content marketers' Thursday refresh queue -- the agent picks update candidates with concrete supporting numbers._

  ```bash
  google-search-console-pp-cli decaying sc-domain:example.com --window 90d --min-imps 500 --top 50 --json
  ```
- **`new-queries`** — Queries that started showing up with impressions in the last N days but didn't exist in the corpus before -- emerging demand.

  _Content-ideas surface for marketers; the agent gets emerging-search trends scoped to this site rather than generic Trends data._

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

## Command Reference

**url-inspection** — Inspect a URL's index status in Google Search

- `google-search-console-pp-cli url-inspection` — Returns Google's view of a single URL: index status, last crawl time, canonical URL (Google-selected vs...

**webmasters** — Manage webmasters

- `google-search-console-pp-cli webmasters add-site` — Adds a site to the set of the user's sites in Search Console. The site must still be verified separately (via DNS,...
- `google-search-console-pp-cli webmasters delete-site` — Removes a site from the set of the user's Search Console sites. Does not delete data Google has collected.
- `google-search-console-pp-cli webmasters delete-sitemap` — Deletes a sitemap from the Sitemaps report. Does not stop Google from crawling the sitemap if it's still...
- `google-search-console-pp-cli webmasters get-site` — Retrieves information about a specific verified site, including the user's permission level.
- `google-search-console-pp-cli webmasters get-sitemap` — Retrieves information about a specific sitemap, including warnings, errors, last submitted/downloaded times, and...
- `google-search-console-pp-cli webmasters list-sitemaps` — Lists the sitemaps submitted for this site, or included in the sitemap index f