gw-searchconsole

Files (1)

• SKILL.md

SKILL.md (first lines)

# Google Search Console

Read-only by construction. `sites.add`, `sites.delete` and the sitemap write methods are not
exposed, and a test asserts they stay unreachable.

## Invocation

```bash
CLI="python3 ${CLAUDE_PLUGIN_ROOT}/cli/gw.py"
```

## Scope prerequisite

Search Console is an opt-in scope, so a default `gw` token does not carry it. Add it once:

```bash
$CLI auth login --add-scopes searchconsole
```

`--add-scopes` unions with the scopes the account already has. Do not use
`--scopes searchconsole`: a login replaces the token, so that form would drop Gmail, Calendar,
Drive, Sheets, Docs, Tasks and Forms. The scope granted is `webmasters.readonly`.

## Commands

```bash
$CLI searchconsole sites --compact

$CLI searchconsole query --site SITE \
  [--dimensions query] [--since 28daysAgo] [--until 3daysAgo] \
  [--limit 25] [--start-row 0] [--type web] [--data-state final] \
  [--filter "page~~/blog"]

$CLI searchconsole sitemaps --site SITE
$CLI searchconsole inspect --site SITE --url URL
```

## Resolve the property first

`sc-domain:example.com` and `https://example.com/` are different properties holding different
data. Run `searchconsole sites` and use the exact string it returns; a guess fails or, worse,
answers about the wrong property.

## Flags

| Flag | Values |
|---|---|
| `--dimensions` | `query`, `page`, `country`, `device`, `searchAppearance`, `date`, `hour` |
| `--since` / `--until` | `YYYY-MM-DD`, `today`, `yesterday`, `NdaysAgo` |
| `--limit` | up to 25000; page beyond that with `--start-row` |
| `--type` | `web`, `image`, `video`, `news`, `discover`, `googleNews` |
| `--data-state` | `final`, `all`, `hourlyAll` |
| `--filter` | repeatable and ANDed: `dim==value`, `dim!=value`, `dim~~substring`, `dim=~regex` |

Filters accept `query`, `page`, `country`, `device` and `searchAppearance` only. `date` and
`hour` can be grouped by but not filtered on; narrow the window with `--since` and `--until`
instead. Grouping by `hour` requires `--data-state hourlyAll`.

Values are normalised to the spelling the v1 discovery document defines, so either case works
on input.

## The window

`--until` defaults to `3daysAgo` because the data lags. Asking for yesterday reliably returns
less than the real figure and reads as a drop. Quote the `window` echoed back in the response
rather than the window you asked for.

## Cheapest output for an agent

`--output csv` collapses the rows to a header and lines, far smaller than the JSON:

```bash
$CLI --output csv searchconsole query --site SITE --dimensions query --limit 25
```

`--output` and `--fields` are **group-level** flags: they go **before** the subcommand.
`--compact` and `--account` go after it.

## Response shapes (validated)

`sites`: `{"sites":[{"site_url","permission_level"}],"count"}`

`query` returns named records, not positional keys:

```json
{"site":"sc-domain:example.com","window":{"since":"2026-08-01","until":"2026-08-31"},
 "dimensions":["query"],
 "rows":[{"query":"pricing","clicks":3,"impressions":40,"ctr":0.075,"position":8.2}],
 "returned":1,"aggregation_type":"byProperty","note":null}
```

When grouped by `query`, `note` warns that rows below Google's privacy threshold are withheld,
so the column does not sum to the site total. For the total, pass `--dimensions ''`.

`sitemaps`: `{"site","sitemaps":[{"path","last_submitted","last_downloaded","is_pending","errors","warnings","contents"}],"count"}`

`inspect`: `{"site","url","verdict","coverage_state","robots_txt_state","indexing_state","page_fetch_state","last_crawl_time","google_canonical","user_canonical","sitemaps","mobile_usability_verdict","rich_results_verdict","inspection_link"}`

## Anything not covered here

`gw-api` reaches the rest of the API. It can also reach the write methods, which it gates
behind `--confirm`; dry-run first and never pass `--confirm` to a call you have not inspected.

```bash
$CLI api call searchconsole:v1 searchanalytics.query \
  --params '{"siteUrl":"SITE"}' --json '{...}' --dry-run --compact
```

From Elnora-AI/elnora-google-workspace, Apache-2.0.

More from Elnora-AI/elnora-google-workspace