@gscdump/cli 5.2.0 → 5.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 Google Search Console CLI and MCP server.
 
-Choose [Local or Hosted mode](../../docs/gscdump-cli/guides/1.start/2.choose-access.md) before login. Local mode calls Google with your own credentials: a service account or an OAuth client. Hosted mode opens gscdump.com, saves a CLI session, and reads your hosted record. It never calls Google.
+Choose [Local or Hosted mode](../../docs/gscdump-cli/guides/1.start/2.choose-access.md) before login. Local mode calls Google with your own credentials: a service account or an OAuth client. Hosted mode opens gscdump.com, saves a CLI session, and reads your hosted record. Explicit `indexing inspect --yes` requests spend URL Inspections through the platform.
 
 ```bash
 npm install -g @gscdump/cli

package/dist/bing-data.mjs

@@ -2,6 +2,7 @@ import { toCSV } from "./utils.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
+import { BING_THROTTLE_IP_ERROR_CODE } from "gscdump/bing";
 const BING_DATASETS = [
 	"traffic",
 	"pages",
@@ -37,7 +38,7 @@ function parseBingDumpOptions(args) {
 function unwrapBing(result) {
 	if (result.ok) return result.value;
 	const error = result.error;
-	const help = error._tag === "AuthenticationRequired" ? " Run `gscdump bing login` again." : error._tag === "Throttled" && error.retryAfterMs !== void 0 ? ` Retry after ${Math.ceil(error.retryAfterMs / 1e3)} seconds.` : "";
+	const help = error._tag === "AuthenticationRequired" ? " Run `gscdump bing login` again." : error._tag === "Throttled" && error.errorCode === BING_THROTTLE_IP_ERROR_CODE ? " Bing refused requests from this IP address. Waiting does not lift the block. Retry from another network." : error._tag === "Throttled" && error.retryAfterMs !== void 0 ? ` Retry after ${Math.ceil(error.retryAfterMs / 1e3)} seconds.` : "";
 	throw new Error(`Bing request failed: ${error._tag}.${help}`);
 }
 function siteIdentity(value) {

package/dist/command-meta.mjs

@@ -32,7 +32,7 @@ const inspectCommandMeta = {
 };
 const indexingCommandMeta = {
 	name: "indexing",
-	description: "Notify Google about URL changes (Indexing API); list hosted URL Inspection results"
+	description: "Notify Google about URL changes (Indexing API); read and refresh hosted URL Inspection results"
 };
 const entitiesCommandMeta = {
 	name: "entities",

package/dist/commands/auth.mjs

@@ -40,6 +40,7 @@ const HOSTED_COMMANDS = [
 	"sitemaps lastmod",
 	"sitemaps export",
 	"indexing urls",
+	"indexing inspect",
 	"indexing summary",
 	"indexing watch",
 	"bing login",

package/dist/commands/indexing-inspect.mjs

@@ -0,0 +1,73 @@
+import { commandLineError, stopError } from "../stop.mjs";
+import { OUTPUT_ARGS, applyOutputMode, logger, readUrlList } from "../utils.mjs";
+import { HOSTED_ARGS, resolveHostedSite } from "../hosted-site.mjs";
+import { defineCommand } from "citty";
+import { isGscdumpV1Error } from "@gscdump/sdk/v1";
+const indexingInspectCommand = defineCommand({
+	meta: {
+		name: "inspect",
+		description: "Refresh Google URL Inspection results through gscdump.com (hosted; spends URL Inspections)"
+	},
+	args: {
+		...HOSTED_ARGS,
+		...OUTPUT_ARGS,
+		urls: {
+			type: "positional",
+			required: false,
+			description: "Up to 10 URLs on the Site host"
+		},
+		file: {
+			type: "string",
+			alias: "f",
+			description: "File with URLs (one per line), or use stdin"
+		},
+		yes: {
+			type: "boolean",
+			alias: "y",
+			default: false,
+			description: "Allow this request to spend URL Inspections"
+		}
+	},
+	async run({ args }) {
+		const { json } = applyOutputMode(args);
+		if (!args.yes) throw commandLineError("This request spends URL Inspections. Pass --yes to proceed.");
+		const urls = [...new Set(await readUrlList({
+			file: args.file,
+			positionals: args._
+		}))];
+		if (urls.length === 0 || urls.length > 10) throw commandLineError("Pass 1 to 10 URLs. This command sends one request and does not split batches.");
+		for (const value of urls) {
+			const url = URL.parse(value);
+			if (!url || !["https:", "http:"].includes(url.protocol) || url.username || url.password || url.hash) throw commandLineError(`Invalid URL: ${value}. Pass an HTTP URL without credentials or a fragment.`);
+		}
+		const { client, site } = await resolveHostedSite({
+			...args,
+			_: []
+		}, {
+			name: "indexing inspect",
+			localAlternative: "run `gscdump inspect --site <site> <url...>`"
+		});
+		const { data } = await client.inspectSiteUrls({
+			params: { siteId: site.siteId },
+			body: { urls }
+		}).catch((error) => {
+			if (!isGscdumpV1Error(error) || error.code !== "rate_limited") throw error;
+			const seconds = error.details.retryAfterSeconds;
+			const wait = typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0 ? ` Wait ${Math.ceil(seconds)} seconds before trying again.` : " Wait for the quota reset before trying again.";
+			throw stopError({
+				code: "QUOTA_USED_UP",
+				message: `${error.message}${wait}`,
+				nextCommand: null
+			});
+		});
+		if (json) console.log(JSON.stringify(data, null, 2));
+		else {
+			for (const result of data.results) console.log(`${result.url}: ${result.coverageState ?? result.verdict ?? "unknown"}`);
+			for (const error of data.errors) console.log(`${error.url}: ${error.error}`);
+			for (const skipped of data.skipped) console.log(`${skipped.url}: skipped (${skipped.reason})`);
+			logger.info(`${data.rateLimit.remaining} of ${data.rateLimit.limit} daily URL Inspections remain.`);
+		}
+		if (data.errors.length || data.skipped.length) throw new Error("Some URLs were not inspected. Read the errors and skipped URLs before trying again.");
+	}
+});
+export { indexingInspectCommand };

package/dist/commands/indexing.mjs

@@ -3,6 +3,7 @@ import { indexingCommandMeta } from "../command-meta.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, parseIntegerOption, readUrlList } from "../utils.mjs";
 import { createCommandContext } from "../context.mjs";
 import { loadSitemapUrls } from "../sitemap.mjs";
+import { indexingInspectCommand } from "./indexing-inspect.mjs";
 import { indexingSummaryCommand } from "./indexing-summary.mjs";
 import { indexingUrlsCommand } from "./indexing-urls.mjs";
 import { indexingWatchCommand } from "./indexing-watch.mjs";
@@ -306,6 +307,7 @@ const indexingCommand = defineCommand({
 		"quota": quotaCommand,
 		"urls": indexingUrlsCommand,
 		"summary": indexingSummaryCommand,
+		"inspect": indexingInspectCommand,
 		"watch": indexingWatchCommand
 	}
 });

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "5.2.0";
+var version = "5.4.0";
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "CLI for Google Search Console and Bing with hosted or local authentication, data exports, and an MCP server",
   "author": {
     "name": "Harlan Wilton",
@@ -44,16 +44,16 @@
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "@duckdb/node-api": "1.5.5-r.5",
-    "@gscdump/analysis": "^5.2.0",
-    "@gscdump/contracts": "^5.2.0",
-    "@gscdump/engine": "^5.2.0",
-    "@gscdump/engine-gsc-api": "^5.2.0",
-    "@gscdump/sdk": "^5.2.0",
+    "@gscdump/analysis": "^5.3.0",
+    "@gscdump/contracts": "^5.3.0",
+    "@gscdump/engine": "^5.3.0",
+    "@gscdump/engine-gsc-api": "^5.3.0",
+    "@gscdump/sdk": "^5.3.1",
     "@modelcontextprotocol/sdk": "^1.30.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.1.0",
-    "gscdump": "^5.2.0",
+    "gscdump": "^5.3.1",
     "ofetch": "^1.5.1",
     "open": "^11.0.4",
     "proper-lockfile": "^4.1.2",

package/skills/gscdump/SKILL.md

@@ -38,7 +38,7 @@ gscdump has 2 access modes. Check `gscdump auth status --json` before queries. R
 | Mode | Credentials | What it reads |
 | --- | --- | --- |
 | `local` | The user's own Google credentials: a service account (recommended) or an OAuth client. Bing API key or OAuth | Calls Google and Bing directly. Keeps a local Store |
-| `hosted` | A browser-approved gscdump.com CLI session, or a gscdump user API key (`GSCDUMP_API_KEY`) | Reads the hosted record on gscdump.com. Never calls Google |
+| `hosted` | A browser-approved gscdump.com CLI session, or a gscdump user API key (`GSCDUMP_API_KEY`) | Reads the hosted record on gscdump.com. Explicit `indexing inspect --yes` requests spend URL Inspections |
 
 In Local mode, `googleAuthenticated: true` means Google accepted the credentials. When it is false, `googleError` says why.
 In Hosted mode, `hostedSync` lists each hosted Site with `syncStatus` and `syncProgress`, and `commands` lists what Hosted mode can run.
@@ -72,9 +72,9 @@ gscdump query --site example.com -d page -f json
 ```
 
 Hosted mode can run only these commands: `sites`, `query`, `sitemaps current`, `sitemaps history`, `sitemaps membership`,
-`sitemaps lastmod`, `sitemaps export`, `indexing urls`, `indexing summary`, `indexing watch list|add|remove`,
+`sitemaps lastmod`, `sitemaps export`, `indexing urls`, `indexing inspect --yes`, `indexing summary`, `indexing watch list|add|remove`,
 and the `bing` commands `login --site`, `sites`, `status`, `dump`, `inspect`, and `verify`.
-Every other command calls Google, so it needs Local mode: `sync`, `inspect`, `query --live`, `analyze --live`, `report --live`,
+Direct Google commands need Local mode: `sync`, `inspect`, `query --live`, `analyze --live`, `report --live`,
 `sites add|get|delete|verify*`, `sitemaps list|get|submit|delete`, `indexing submit|remove|status|batch`, `entities`, and `mcp`.
 In Hosted mode these commands stop with this error: `This command calls Google, so it needs Local mode.`
 Tell the user. Do not switch modes for them.
@@ -247,7 +247,7 @@ A routing stop also has `siteUrl`. `STORE_RANGE_NOT_COVERED` adds `missingDates`
 | `LIVE_ONLY` | Only `--live` can answer the read |
 | `LOGIN_CANCELLED` | The user selected Cancel on the gscdump.com login page. Ask before you run `nextCommand` |
 | `LOCAL_MODE_REQUIRED` | The command calls Google, and Hosted mode is selected |
-| `HOSTED_MODE_REQUIRED` | The command reads the hosted record, and Local mode is selected |
+| `HOSTED_MODE_REQUIRED` | The command needs Hosted mode, and Local mode is selected |
 | `HOSTED_CREDENTIALS_MISSING` | Hosted mode has no CLI session and no API key |
 | `HOSTED_CREDENTIALS_REJECTED` | gscdump.com rejected the CLI session or API key. For an API key, `nextCommand` is null: the user needs a new key from the app that issued it |
 | `NO_SITES` | The hosted record has no Sites. The message says where the user connects one |
@@ -276,6 +276,7 @@ A routing stop also has `siteUrl`. `STORE_RANGE_NOT_COVERED` adds `missingDates`
 | `gscdump inspect <url...>` | URL Inspection with Indexing Evidence, saved to the Store |
 | `gscdump sitemaps` | List, submit, delete, and probe sitemaps |
 | `gscdump indexing` | Indexing API notifications and quota; hosted URL Inspection results |
+| `gscdump indexing inspect <url...> --yes` | Hosted: refresh up to 10 URLs through the platform, spending shared URL Inspections. Never retry automatically |
 | `gscdump indexing summary` | Hosted: the coverage ladder per day, with the time gscdump counted the verdicts |
 | `gscdump indexing watch` | Hosted: list, add, and remove Watched URLs and read their Checkpoints |
 | `gscdump dump` | Export Store tables, inspections, sitemaps, and Bing data as Parquet, CSV, JSON, NDJSON, SQLite, or DuckDB |
@@ -484,10 +485,10 @@ Read the 4 ladder states in `counts`, lowest rung first. Name each state with th
 
 | Key | Name | Meaning |
 | --- | --- | --- |
-| `unknown_to_google` | unknown | Google has no record of the URL |
-| `discovered_not_indexed` | discovered | Google queued the URL and has not crawled it |
-| `crawled_not_indexed` | crawled | Google crawled the URL and left it out of the index |
-| `indexed` | indexed | Google indexed the URL |
+| `unknown_to_google` | unknown | URL Inspection reported the URL as unknown at its check time |
+| `discovered_not_indexed` | discovered | URL Inspection reported discovery without a crawl at its check time |
+| `crawled_not_indexed` | crawled | URL Inspection reported a crawl without indexing at its check time |
+| `indexed` | indexed | URL Inspection reported the URL as indexed at its check time |
 
 The other keys in `counts` are exclusions, such as `noindex`, `not_found`, and `redirect`.
 `unrecognized` counts coverage text gscdump cannot map yet. `not_reported` counts results with no coverage text.
@@ -502,11 +503,15 @@ Rules for every answer:
   They are also not the Search Console Page indexing report. The two can differ a lot, and the Page indexing report can list many more URLs.
 - `olderThan7d` and `olderThan30d` count verdicts inspected more than 7 times 24 hours and 30 times 24 hours before `capturedAt`. They are not calendar days.
 - A verdict can be months older than its capture. Unchanged URLs are rechecked less often over time. Say when most verdicts are old.
+- Unknown and discovered verdicts do not show Google's current crawl queue. They do not prove noindex or content rejection.
+- An accepted indexing request does not confirm crawling or indexing. Compare its receipt date with the saved inspection date.
+- If the saved inspection predates a request, it cannot show that request's outcome. A live indexability test also cannot confirm indexing.
 - A move between rungs shows in the trend. Compare two `counted` days and name the dates.
 - `capture.scope` says which URLs the counts cover. `sitemap_members` means every counted URL is in a live sitemap.
   `inspected_urls` means sitemap membership was not available, so the counts can include URLs outside every sitemap.
 - If `unknown_to_google` URLs are already in a sitemap, the sitemap is not the gap. Do not tell the owner to add them to it.
-  Read the sitemap's last download with `gscdump sitemaps current --site SITE --json`. If Google downloaded it, say that Google read the sitemap and did not take the URLs.
+  Read the sitemap's last download with `gscdump sitemaps current --site SITE --json`. Compare that date with each saved inspection date.
+  A sitemap download confirms that Google read the feed. It does not confirm discovery, crawling, or indexing of every URL.
   Check one URL's membership with `gscdump sitemaps membership`.
 - Name no cause beyond what the evidence shows.
 - Cite the command behind each number.
@@ -590,3 +595,16 @@ Include that JSON in your final response. Tool output alone is not a final answe
 Include every returned row. Do not refer the user to results "above".
 
 For a deletion explanation, read metadata only if needed. Explain the scope and ask for consent, then stop.
+
+## Refresh hosted Google URL Inspection results
+
+```sh
+gscdump indexing inspect https://example.com/page --site example.com --yes --json
+```
+
+This asks Google for its current indexed-page verdict. It does not run a live-page test or request indexing.
+Pass 1 to 10 unique URLs, or use `--file` or stdin. The platform enforces its shared daily quota.
+The command sends one request. It never splits batches or retries automatically.
+If the API returns 429, wait for the reported reset before another request.
+If `errors` or `skipped` contains URLs, the command exits 1 and preserves its result on stdout.
+Read `rateLimit.remaining` before deciding whether to inspect more URLs.