@gscdump/cli 5.0.0 → 5.2.0

package/dist/hosted-site.mjs

@@ -1,8 +1,7 @@
-import { getHostedAccount, hostedCredential, parseAuthentication, resolveAuthentication } from "./auth-state.mjs";
+import { stopError } from "./stop.mjs";
+import { connectSiteStep, getHostedAccount, hostedCredential, parseAuthentication, resolveAuthentication, siteManagerOf } from "./auth-state.mjs";
 import { loadConfig } from "./config.mjs";
 import { resolveCliEnvironment } from "./environment.mjs";
-import { logger } from "./utils.mjs";
-import process from "node:process";
 import { createGscdumpV1Client } from "@gscdump/sdk/v1";
 const HOSTED_ARGS = {
 	"site": {
@@ -57,35 +56,59 @@ function matchHostedSite(sites, target) {
 		sites: [...sites]
 	};
 }
-function describeMatchFailure(match) {
-	if (match.kind === "ambiguous") return `Multiple hosted Sites match "${match.target}": ${match.matches.map((site) => site.siteUrl).join(", ")}. Pass the exact Site URL with --site.`;
-	if (match.sites.length === 0) return "Your hosted account has no Sites. Add a Site at https://gscdump.com.";
-	const available = `Hosted Sites: ${match.sites.map((site) => site.siteUrl).join(", ")}.`;
-	return match.target ? `No hosted Site matches "${match.target}". ${available}` : `Pass --site. ${available}`;
+function noSitesStop(manager) {
+	return {
+		code: "NO_SITES",
+		message: `Your hosted record has no Sites. ${connectSiteStep(manager)} Then run the command again.`,
+		nextCommand: null
+	};
 }
-function fail(message) {
-	logger.error(message);
-	process.exit(1);
+function siteMatchStop(match, manager) {
+	const nextCommand = "gscdump sites --json";
+	if (match.kind === "ambiguous") return {
+		code: "SITE_AMBIGUOUS",
+		message: `Multiple hosted Sites match "${match.target}": ${match.matches.map((site) => site.siteUrl).join(", ")}. Pass the exact Site URL with --site.`,
+		nextCommand
+	};
+	if (match.sites.length === 0) return noSitesStop(manager);
+	const available = `Hosted Sites: ${match.sites.map((site) => site.siteUrl).join(", ")}.`;
+	return match.target ? {
+		code: "SITE_NOT_FOUND",
+		message: `No hosted Site matches "${match.target}". ${available}`,
+		nextCommand
+	} : {
+		code: "SITE_REQUIRED",
+		message: `Pass --site. ${available}`,
+		nextCommand
+	};
 }
 async function resolveHostedSite(args, command) {
-	if (args._?.length) fail(`\`gscdump ${command.name}\` does not accept a positional Site ID. Pass --site instead.`);
+	if (args._?.length) throw new Error(`\`gscdump ${command.name}\` does not accept a positional Site ID. Pass --site instead.`);
 	const environment = resolveCliEnvironment().values;
 	const authentication = args["api-key"] ? parseAuthentication({
 		_tag: "Hosted",
 		apiKey: args["api-key"],
 		apiRoot: String(args["api-root"] || environment.GSCDUMP_API_ROOT || "https://gscdump.com/api")
 	}) : await resolveAuthentication();
-	if (authentication._tag !== "Hosted") fail(`\`gscdump ${command.name}\` reads the hosted record, so it needs Hosted mode. Run \`gscdump auth login --mode hosted\`, or pass --api-key. In Local mode, ${command.localAlternative}.`);
-	if (args["api-root"] && String(args["api-root"]).replace(/\/+$/, "") !== authentication.apiRoot) fail("The API root changed. Pass --api-key for the new API root.");
+	if (authentication._tag !== "Hosted") throw stopError({
+		code: "HOSTED_MODE_REQUIRED",
+		message: `\`gscdump ${command.name}\` reads the hosted record, so it needs Hosted mode. Run \`gscdump auth login --mode hosted\`, or pass --api-key. In Local mode, ${command.localAlternative}.`,
+		nextCommand: "gscdump auth login --mode hosted"
+	});
+	if (args["api-root"] && String(args["api-root"]).replace(/\/+$/, "") !== authentication.apiRoot) throw new Error("The API root changed. Pass --api-key for the new API root.");
 	const target = args.site ? String(args.site) : (await loadConfig()).defaultSite;
-	const match = matchHostedSite((await getHostedAccount(authentication)).sites, target);
-	if (match.kind !== "found") fail(describeMatchFailure(match));
+	const account = await getHostedAccount(authentication);
+	const siteManager = siteManagerOf(authentication, account.issuer);
+	const match = matchHostedSite(account.sites, target);
+	if (match.kind !== "found") throw stopError(siteMatchStop(match, siteManager));
 	return {
 		client: createGscdumpV1Client({
 			apiRoot: authentication.apiRoot,
 			credential: hostedCredential(authentication)
 		}),
-		site: match.site
+		site: match.site,
+		authentication,
+		siteManager
 	};
 }
-export { HOSTED_ARGS, matchHostedSite, resolveHostedSite };
+export { HOSTED_ARGS, matchHostedSite, noSitesStop, resolveHostedSite, siteMatchStop };

package/dist/mcp/errors.mjs

@@ -1,9 +1,9 @@
 import { resolveBYOK, resolveServiceAccount } from "../auth.mjs";
 import { COMPARISON_FLAGS, PERIOD_FLAGS } from "../window.mjs";
+import { isQueryError } from "gscdump/query";
 import { isAnalysisError } from "@gscdump/analysis/errors";
 import { isEngineError } from "@gscdump/engine/errors";
 import { classifyError } from "gscdump/errors";
-import { isQueryError } from "gscdump/query";
 const PERIODS = PERIOD_FLAGS;
 const COMPARISONS = COMPARISON_FLAGS;
 const mcpHandlerErrors = {

package/dist/package.mjs

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

package/dist/route.mjs

@@ -1,3 +1,4 @@
+import { stopError } from "./stop.mjs";
 import { probeAuth } from "./auth.mjs";
 import { listStoreSites } from "./store-sites.mjs";
 import { formatSiteResolution, siteArg } from "./context.mjs";
@@ -199,11 +200,8 @@ function stopCode(route) {
 		case "partial": return "STORE_RANGE_NOT_COVERED";
 	}
 }
-function routeStopError(route, message) {
-	return Object.assign(new Error(message), {
-		name: "RouteStopError",
-		routeStop: route
-	});
+function routeStopError(route, details) {
+	return Object.assign(stopError(details, "RouteStopError"), { routeStop: route });
 }
 async function needCoverage(needs, states) {
 	const reader = syncStateCoverageReader(states);
@@ -299,9 +297,7 @@ function describeStop(route, req, auth) {
 		} } : {}
 	};
 }
-function stopAtRoute(route, req, auth, opts) {
-	const details = describeStop(route, req, auth);
-	if (opts.json) console.log(JSON.stringify({ error: details }, null, 2));
-	throw routeStopError(route, details.message);
+function stopAtRoute(route, req, auth) {
+	throw routeStopError(route, describeStop(route, req, auth));
 }
 export { decideRoute, describeStop, liveCommand, liveNote, needCoverage, readRouteState, readSiteStates, resolveReadSite, routeMessage, routeStopError, stopAtRoute, stopCode, syncCommandFor };

package/dist/runtime.d.mts

@@ -7,6 +7,8 @@ export interface CliRuntime {
   configDir: string;
   configDirOverridden: boolean;
   environment: CliEnvironmentSource;
+  /** The command writes JSON to stdout. A stop then prints its JSON form there too. */
+  jsonOutput: boolean;
   logger: ConsolaInstance;
   quiet: boolean;
   rawArgs: string[];

package/dist/runtime.mjs

@@ -21,6 +21,7 @@ function createCliRuntime(opts = {}) {
 		configDir: opts.configDir ?? path.join(os.homedir(), ".config", "gscdump"),
 		configDirOverridden: false,
 		environment: opts.environment ?? process.env,
+		jsonOutput: false,
 		logger: baseLogger.withTag("gscdump"),
 		quiet: false,
 		rawArgs: [...opts.rawArgs ?? process.argv.slice(2)]

package/dist/stop.mjs

@@ -0,0 +1,23 @@
+function stopError(details, name = "StopError") {
+	return Object.assign(new Error(details.message), {
+		name,
+		stopDetails: details
+	});
+}
+function stopDetailsOf(error) {
+	return error instanceof Error ? error.stopDetails : void 0;
+}
+function userStopError(details) {
+	return Object.assign(stopError(details, "UserStopError"), { userStop: true });
+}
+function isUserStop(error) {
+	return error instanceof Error && error.userStop === true;
+}
+function commandLineError(message) {
+	return stopError({
+		code: "USAGE",
+		message,
+		nextCommand: null
+	});
+}
+export { commandLineError, isUserStop, stopDetailsOf, stopError, userStopError };

package/dist/utils.mjs

@@ -1,9 +1,10 @@
 import { useCliRuntime } from "./runtime.mjs";
+import { commandLineError } from "./stop.mjs";
 import { version } from "./package.mjs";
 import process from "node:process";
 import fs from "node:fs/promises";
-import { SearchTypes } from "gscdump/query";
 import os from "node:os";
+import { SearchTypes } from "gscdump/query";
 import { Buffer } from "node:buffer";
 import { MAX_FETCH_BUDGET } from "@gscdump/engine/analysis-types";
 const ALL_SEARCH_TYPES = Object.values(SearchTypes);
@@ -40,10 +41,14 @@ const OUTPUT_ARGS = {
 		description: "Suppress info/success output"
 	}
 };
+function setJsonOutput(json) {
+	useCliRuntime().jsonOutput = json;
+}
 function applyOutputMode(args) {
 	const json = Boolean(args.json);
 	const quiet = json || Boolean(args.quiet);
 	setQuiet(quiet);
+	setJsonOutput(json);
 	return {
 		json,
 		quiet
@@ -52,29 +57,26 @@ function applyOutputMode(args) {
 function parseSearchType(value, flag = "--search-type") {
 	if (!value) return void 0;
 	const v = String(value);
-	if (!ALL_SEARCH_TYPES.includes(v)) {
-		logger.error(`Invalid ${flag}: ${v}. Allowed: ${ALL_SEARCH_TYPES.join(", ")}`);
-		process.exit(1);
-	}
+	if (!ALL_SEARCH_TYPES.includes(v)) throw commandLineError(`Invalid ${flag}: ${v}. Allowed: ${ALL_SEARCH_TYPES.join(", ")}`);
 	return v;
 }
 function parseNameList(value, known, flag) {
 	const names = String(value ?? "").split(",").map((name) => name.trim()).filter(Boolean);
 	const unknown = names.filter((name) => !known.includes(name));
-	if (unknown.length > 0) throw new Error(`Unknown ${flag} name: ${unknown.join(", ")}. Valid names: ${known.join(", ")}.`);
-	if (names.length === 0) throw new Error(`${flag} needs at least one name. Valid names: ${known.join(", ")}.`);
+	if (unknown.length > 0) throw commandLineError(`Unknown ${flag} name: ${unknown.join(", ")}. Valid names: ${known.join(", ")}.`);
+	if (names.length === 0) throw commandLineError(`${flag} needs at least one name. Valid names: ${known.join(", ")}.`);
 	return names;
 }
 function parseIntegerOption(value, flag, minimum = 1) {
 	if (value === void 0 || value === null) return void 0;
 	const text = typeof value === "number" || typeof value === "string" ? String(value).trim() : "";
 	const parsed = Number(text);
-	if (!/^\d+$/.test(text) || !Number.isSafeInteger(parsed) || parsed < minimum) throw new Error(`${flag} must be ${minimum === 0 ? "a non-negative integer" : "a positive integer"}.`);
+	if (!/^\d+$/.test(text) || !Number.isSafeInteger(parsed) || parsed < minimum) throw commandLineError(`${flag} must be ${minimum === 0 ? "a non-negative integer" : "a positive integer"}.`);
 	return parsed;
 }
 function parseFetchBudget(value) {
 	const budget = parseIntegerOption(value, "--fetch-budget");
-	if (budget !== void 0 && budget > MAX_FETCH_BUDGET) throw new Error(`--fetch-budget must be at most ${MAX_FETCH_BUDGET}. Larger fetches use up the GSC quota.`);
+	if (budget !== void 0 && budget > MAX_FETCH_BUDGET) throw commandLineError(`--fetch-budget must be at most ${MAX_FETCH_BUDGET}. Larger fetches use up the GSC quota.`);
 	return budget;
 }
 const ANSI_RE = /\x1B\[[0-9;]*m/g;
@@ -141,17 +143,14 @@ function applyGradient(text) {
 }
 function showSplash() {
 	console.log();
-	console.log(`  ${applyGradient("GSC Dump")} v${VERSION}`);
+	console.log(`  ${applyGradient("gscdump")} v${VERSION}`);
 	console.log();
 }
 function clearLine() {
 	process.stdout.write("\r\x1B[K");
 }
 function displayPath(absPath) {
-	const cwd = process.cwd();
 	const home = os.homedir();
-	if (absPath === cwd) return ".";
-	if (absPath.startsWith(`${cwd}/`)) return absPath.slice(cwd.length + 1);
 	if (absPath === home) return "~";
 	if (absPath.startsWith(`${home}/`)) return `~/${absPath.slice(home.length + 1)}`;
 	return absPath;
@@ -196,4 +195,4 @@ async function readUrlList(input) {
 	for await (const chunk of process.stdin) chunks.push(chunk);
 	return parseUrlLines(Buffer.concat(chunks).toString("utf-8"));
 }
-export { ALL_SEARCH_TYPES, OUTPUT_ARGS, VERSION, applyOutputMode, clearLine, color, cyan, dim, displayPath, formatAge, isColorEnabled, logger, parseFetchBudget, parseIntegerOption, parseNameList, parseSearchType, plural, progressBar, readUrlList, red, runWithConcurrency, setNoColor, setQuiet, showSplash, toCSV, withConfiguredOutput };
+export { ALL_SEARCH_TYPES, OUTPUT_ARGS, VERSION, applyOutputMode, clearLine, color, cyan, dim, displayPath, formatAge, isColorEnabled, logger, parseFetchBudget, parseIntegerOption, parseNameList, parseSearchType, plural, progressBar, readUrlList, red, runWithConcurrency, setJsonOutput, setNoColor, setQuiet, showSplash, toCSV, withConfiguredOutput };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "5.0.0",
+  "version": "5.2.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.0.0",
-    "@gscdump/contracts": "^5.0.0",
-    "@gscdump/engine": "^5.0.0",
-    "@gscdump/engine-gsc-api": "^5.0.0",
-    "@gscdump/sdk": "^5.0.0",
+    "@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",
     "@modelcontextprotocol/sdk": "^1.30.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.1.0",
-    "gscdump": "^5.0.0",
+    "gscdump": "^5.2.0",
     "ofetch": "^1.5.1",
     "open": "^11.0.4",
     "proper-lockfile": "^4.1.2",

package/skills/gscdump/SKILL.md

@@ -11,7 +11,7 @@ For `query`, `-s` means `--site`, `-d` means `--dimensions`, and `-f` means `--f
 Use `--start` and `--end` for dates. `--site=SITE` also works.
 Use each option once, with either its short or long spelling.
 Put options after the subcommand name: `gscdump store stats --json`, not `gscdump store --json stats`.
-A failed command prints one `Error:` line to stderr and exits 1.
+A failed command prints one `Error:` line to stderr and exits 1. With JSON output it also prints `{ "error" }` on stdout. See [Stops](#stops).
 Example: `gscdump query --site=SITE --start=DATE --end=DATE -d page -f json`.
 
 ## Start each task
@@ -43,6 +43,11 @@ gscdump has 2 access modes. Check `gscdump auth status --json` before queries. R
 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.
 `gscdump sites` shows the same Sites and progress.
+An empty `sites` list means the hosted record has no Sites. Commands that need a Site then stop with `NO_SITES`.
+Tell the user to connect a Site in the place the `NO_SITES` message names.
+A browser login connects Sites on gscdump.com.
+An API key connects Sites in the app that issued the key. That app can be a partner app, not gscdump.com.
+When gscdump.com names the app, the message names it too, for example `Connect a Site in Request Indexing.`
 
 `--mode local|hosted` overrides one invocation. `GSCDUMP_AUTH_MODE` also overrides the saved mode.
 A successful login saves the mode per profile.
@@ -128,8 +133,7 @@ mixes Store rows and live rows.
 - `--live` always asks Search Console. It needs Local mode with Google credentials.
 - `query --sql` reads the Store only. It stops when no table it names has data.
 - JSON output carries `meta.source`: `local`, `live`, or `hosted`.
-- A stop with `--format json` or `--json` prints `{ "error": { "code", "message", "nextCommand" } }` on stdout and exits 1.
-  Codes: `NOT_CONNECTED`, `STORE_RANGE_NOT_COVERED` (with `missingDates`), `SYNC_RUNNING` (with `sync.done` and `sync.total`), `NO_SYNCED_DATA`, `STORE_ONLY`, `LIVE_ONLY`.
+- A failure with JSON output prints `{ "error" }` on stdout and exits 1. See [Stops](#stops).
   Partial coverage and a running sync are normal progress. Run `nextCommand`, or tell the user to.
 - A sync is running only while its heartbeat is recent. A killed sync does not block reads.
 - Every Search Analytics, URL Inspection, and Indexing API call spends the shared quota ledger in the data dir.
@@ -153,7 +157,8 @@ gscdump skill install --agent claude    # Codex: --agent codex
 ```
 
 After upgrading the CLI, run this command again to update the installed skill.
-The command prints where it wrote the skill. Clients without a skill
+The command prints where it wrote the skill, as a path that works from any directory, such as `~/.claude/skills/gscdump`.
+With `--json`, `destination` is the absolute path. Clients without a skill
 directory can read `gscdump --help` and `gscdump <command> --help` instead.
 
 ## Local mode setup
@@ -220,6 +225,40 @@ Parse JSON. Never scrape human output.
 If the user requests JSON, return the CLI JSON unchanged. Do not replace it with a table.
 Do not rewrite rows, estimate metrics, or add manually calculated totals.
 
+## Stops
+
+A stop ends a command at a known condition and exits 1. stderr gets the message.
+If the command writes JSON, every failure prints `{ "error": { "code", "message", "nextCommand" } }` on stdout. A stop has a code from the table below.
+Any other failure has the code `FAILED`, such as a network or API error, or `UNEXPECTED`, a defect in the CLI.
+A command writes JSON with `--json`, with `--format json`, and for `query` with its default format.
+If a command printed its JSON result before it failed, such as `inspect` after a quota stop, stdout holds only that result.
+Read `code`, not the message. If `nextCommand` is not null, run it, or tell the user to run it.
+A `gscdump auth login` command needs the user. Tell the user to run it. If `nextCommand` is null, tell the user the `message`.
+A routing stop also has `siteUrl`. `STORE_RANGE_NOT_COVERED` adds `missingDates`, and `SYNC_RUNNING` adds `sync.done` and `sync.total`.
+
+| Code | Meaning |
+| --- | --- |
+| `USAGE` | The command line is wrong: an unknown command or option, or a value the option does not accept. Fix it with the command's `--help` |
+| `NOT_CONNECTED` | The Store cannot answer, and Google is not connected |
+| `STORE_RANGE_NOT_COVERED` | The Store does not have `missingDates` |
+| `SYNC_RUNNING` | A sync is still filling the dates |
+| `NO_SYNCED_DATA` | A Store-only read found no synced data |
+| `STORE_ONLY` | The read needs the Store, so `--live` cannot run it |
+| `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_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 |
+| `SITE_NOT_FOUND` | No hosted Site matches `--site` |
+| `SITE_AMBIGUOUS` | More than one hosted Site matches `--site` |
+| `SITE_REQUIRED` | The hosted record has more than one Site. Pass `--site` |
+| `BING_NOT_CONNECTED` | The Site has no hosted Bing connection |
+| `RECORD_NOT_READY` | gscdump has not prepared the Site's record for reads yet |
+| `RANGE_NOT_SYNCED` | The hosted record does not hold the requested dates |
+| `QUOTA_USED_UP` | A Google API quota is used up. The message says when it resets |
+
 ## Commands
 
 | Command | Use it for |