@gscdump/cli 5.1.0 → 5.3.0

package/dist/auth-state.mjs

@@ -1,3 +1,4 @@
+import { HOSTED_SESSION_EXPIRED, isSessionExpiredBody } from "./hosted-session.mjs";
 import { useCliRuntime } from "./runtime.mjs";
 import { stopError } from "./stop.mjs";
 import { randomUUID } from "node:crypto";
@@ -156,12 +157,18 @@ const hostedSiteSchema = z.object({
 	newestDateSynced: z.string().nullable().optional(),
 	oldestDateSynced: z.string().nullable().optional()
 }).passthrough();
+const partnerNameSchema = z.string().trim().min(1).max(80).regex(/^\P{Cc}+$/u);
+const keyIssuerSchema = z.discriminatedUnion("_tag", [z.object({ _tag: z.literal("gscdump") }), z.object({
+	_tag: z.literal("partner"),
+	name: partnerNameSchema
+})]);
 const accountSchema = z.object({
 	user: z.object({
 		publicId: z.string(),
 		email: z.string()
 	}),
-	sites: z.array(hostedSiteSchema)
+	sites: z.array(hostedSiteSchema),
+	issuer: keyIssuerSchema.optional().catch(void 0)
 });
 async function hostedRequest(state, route, options = {}) {
 	const response = await fetch(`${state.apiRoot}${route}`, {
@@ -181,7 +188,8 @@ async function hostedRequest(state, route, options = {}) {
 		};
 		if (response.status === 401) {
 			const session = "sessionId" in state;
-			throw Object.assign(stopError({
+			const expired = session && isSessionExpiredBody(await response.json().catch(() => null));
+			throw Object.assign(stopError(expired ? HOSTED_SESSION_EXPIRED : {
 				code: "HOSTED_CREDENTIALS_REJECTED",
 				message: session ? HOSTED_SESSION_REJECTED : HOSTED_KEY_REJECTED,
 				nextCommand: session ? "gscdump auth login --mode hosted" : null
@@ -194,18 +202,28 @@ async function hostedRequest(state, route, options = {}) {
 function hostedCredential(state) {
 	return "sessionId" in state ? state.sessionId : state.apiKey;
 }
-function siteManagerOf(state) {
-	return "sessionId" in state ? { _tag: "gscdump" } : { _tag: "key_issuer" };
+function siteManagerOf(state, issuer) {
+	if ("sessionId" in state) return { _tag: "gscdump" };
+	return issuer ?? { _tag: "key_issuer" };
 }
-function connectSiteStep(manager) {
+function connectSitePlace(manager) {
 	switch (manager._tag) {
-		case "gscdump": return "Connect a Site at https://gscdump.com/app/onboarding?step=connect-sites.";
-		case "key_issuer": return "Connect a Site in the app that issued this API key.";
+		case "gscdump": return "at https://gscdump.com/app/onboarding?step=connect-sites";
+		case "partner": return `in ${manager.name}`;
+		case "key_issuer": return "in the app that issued this API key";
 	}
 }
+function connectSiteStep(manager) {
+	return `Connect a Site ${connectSitePlace(manager)}.`;
+}
+function noSitesNextStep(manager) {
+	const next = `Next: connect a Site ${connectSitePlace(manager)}.`;
+	return manager._tag === "gscdump" ? `${next} If Hosted access is not active, gscdump.com asks you to activate it first.` : next;
+}
 function siteSettingsPlace(manager) {
 	switch (manager._tag) {
 		case "gscdump": return "in the Site settings on gscdump.com";
+		case "partner": return `in the Site settings of ${manager.name}`;
 		case "key_issuer": return "in the Site settings of the app that issued this API key";
 	}
 }
@@ -218,4 +236,4 @@ function formatHostedSync(site) {
 	const status = site.syncStatus ?? "pending";
 	return `${status}${site.syncProgress && site.syncProgress.total > 0 && status !== "synced" ? `: ${site.syncProgress.completed.toLocaleString("en-US")} of ${site.syncProgress.total.toLocaleString("en-US")} days (${Math.round(site.syncProgress.percent)}%)` : ""}${status === "synced" && site.oldestDateSynced && site.newestDateSynced ? `: ${site.oldestDateSynced} to ${site.newestDateSynced}` : ""}`;
 }
-export { HOSTED_KEY_REJECTED, HOSTED_NOT_SET_UP, HOSTED_SESSION_REJECTED, LOCAL_MODE_REQUIRED, clearAuthentication, connectSiteStep, formatHostedSync, getHostedAccount, hostedCredential, hostedRequest, localModeRequired, parseAuthMode, parseAuthentication, resolveAccessMode, resolveAuthentication, revokeHostedSession, saveAuthentication, siteManagerOf, siteSettingsPlace };
+export { HOSTED_KEY_REJECTED, HOSTED_NOT_SET_UP, HOSTED_SESSION_REJECTED, LOCAL_MODE_REQUIRED, clearAuthentication, connectSiteStep, formatHostedSync, getHostedAccount, hostedCredential, hostedRequest, localModeRequired, noSitesNextStep, parseAuthMode, parseAuthentication, resolveAccessMode, resolveAuthentication, revokeHostedSession, saveAuthentication, siteManagerOf, siteSettingsPlace };

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/bing-hosted.mjs

@@ -33,7 +33,7 @@ async function loadHostedBingConnections(state, sites, options = {}) {
 async function resolveHostedBingSites(state, input) {
 	if (Boolean(input.site) === Boolean(input.allSites)) throw new Error("Choose --site or --all-sites.");
 	const account = await getHostedAccount(state);
-	if (account.sites.length === 0) throw stopError(noSitesStop(siteManagerOf(state)));
+	if (account.sites.length === 0) throw stopError(noSitesStop(siteManagerOf(state, account.issuer)));
 	const exact = account.sites.filter((site) => site.siteId === input.site || site.siteUrl === input.site);
 	const normalize = (value) => URL.parse(value.startsWith("sc-domain:") ? `https://${value.slice(10)}/` : value)?.toString();
 	const requested = input.allSites ? account.sites : exact.length ? exact : account.sites.filter((site) => normalize(site.siteUrl) === normalize(input.site) && normalize(input.site) !== void 0);

package/dist/cli.d.mts

@@ -1,4 +1,10 @@
 import { CliRuntime, CreateCliRuntimeOptions, createCliRuntime } from "./runtime.mjs";
+/**
+ * The command line asks for JSON output: `--json`, `--format json`, or `query`
+ * with no `--format`, since JSON is its default. The command sets the final
+ * mode when it runs. This covers failures before that.
+ */
+export declare function asksForJson(rawArgs: readonly string[]): boolean;
 export declare const main: import("citty").CommandDef<import("citty").ArgsDef>;
 export interface RunCliOptions {
   rawArgs?: string[];

package/dist/cli.mjs

@@ -1,4 +1,5 @@
 import { createCliRuntime, runWithCliRuntime, useCliRuntime } from "./runtime.mjs";
+import { commandLineError } from "./stop.mjs";
 import { parseAuthMode } from "./auth-state.mjs";
 import { checkCliArgs } from "./cli-args.mjs";
 import { CLI_SUBCOMMANDS, resolveUsageTarget } from "./command-registry.mjs";
@@ -23,9 +24,22 @@ function shouldShowSplash(rawArgs) {
 	]) if (rawArgs.includes(flag)) return false;
 	return true;
 }
+function formatFlag(rawArgs) {
+	for (const [index, arg] of rawArgs.entries()) {
+		if (arg === "--format" || arg === "-f") return rawArgs[index + 1];
+		const inline = /^(?:--format=|-f=?)(.+)$/.exec(arg);
+		if (inline) return inline[1];
+	}
+}
+function asksForJson(rawArgs) {
+	const format = formatFlag(rawArgs);
+	return rawArgs.includes("--json") || format === "json" || rawArgs[0] === "query" && format === void 0;
+}
 function prepareCliArgs(input) {
 	const rawArgs = [...input];
-	useCliRuntime().authModeOverride = parseAuthMode(pluckArgValue(rawArgs, "--mode") ?? void 0);
+	const mode = pluckArgValue(rawArgs, "--mode");
+	if (mode !== null && mode !== "local" && mode !== "hosted") throw commandLineError("Access mode must be local or hosted.");
+	useCliRuntime().authModeOverride = parseAuthMode(mode ?? void 0);
 	const env = resolveCliEnvironment();
 	setNoColor(!terminalOutputOptions().color);
 	const profile = pluckArgValue(rawArgs, "--profile", true);
@@ -50,7 +64,7 @@ function pluckArgValue(argv, flag, allowQueryTiming = false) {
 		const inline = a !== flag;
 		const next = inline ? a.slice(flag.length + 1) : argv[i + 1];
 		if (!inline && allowQueryTiming && argv.includes("query") && argv.indexOf("query") < i && (next === void 0 || next.startsWith("-"))) continue;
-		if (!next || !inline && next.startsWith("-")) throw new Error(`${flag} requires a value. Use ${flag}=VALUE.`);
+		if (!next || !inline && next.startsWith("-")) throw commandLineError(`${flag} requires a value. Use ${flag}=VALUE.`);
 		value = next;
 		argv.splice(i, inline ? 1 : 2);
 		i--;
@@ -80,6 +94,26 @@ async function runMainCommand(rawArgs) {
 	}
 	await runCommand(main, { rawArgs });
 }
+function watchStdout() {
+	let wrote = false;
+	const write = process.stdout.write;
+	const log = console.log;
+	process.stdout.write = ((...args) => {
+		wrote = true;
+		return write.apply(process.stdout, args);
+	});
+	console.log = (...args) => {
+		wrote = true;
+		log(...args);
+	};
+	return {
+		wrote: () => wrote,
+		restore: () => {
+			process.stdout.write = write;
+			console.log = log;
+		}
+	};
+}
 function stderrColor(runtime, rawArgs) {
 	return resolveOutputOptions({
 		isTTY: process.stderr.isTTY,
@@ -97,22 +131,27 @@ async function runCli(opts = {}) {
 	return runWithCliRuntime(runtime, async () => {
 		let rawArgs = [...input];
 		runtime.jsonOutput = false;
+		const stdout = watchStdout();
 		try {
+			runtime.jsonOutput = asksForJson(input);
 			rawArgs = prepareCliArgs(input);
 			runtime.rawArgs = [...rawArgs];
+			runtime.jsonOutput = asksForJson(rawArgs);
 			const argumentError = await checkCliArgs(main, rawArgs);
-			if (argumentError) throw new Error(argumentError);
+			if (argumentError) throw commandLineError(argumentError);
 			await withConfiguredOutput(() => runMainCommand(rawArgs));
 			return 0;
 		} catch (error) {
 			await reportCliError(error, {
 				color: stderrColor(runtime, rawArgs),
-				json: runtime.jsonOutput,
+				json: runtime.jsonOutput && !stdout.wrote(),
 				usage: async () => renderUsage(...await resolveUsageTarget(main, rawArgs)),
 				authSources: async () => (await import("./auth.mjs")).formatAuthProvenance()
 			});
 			return 1;
+		} finally {
+			stdout.restore();
 		}
 	});
 }
-export { createCliRuntime, main, runCli };
+export { asksForJson, createCliRuntime, main, runCli };

package/dist/command-meta.mjs

@@ -1,6 +1,6 @@
 const initCommandMeta = {
 	name: "init",
-	description: "Set up GSCDump authentication"
+	description: "Set up gscdump authentication"
 };
 const dumpCommandMeta = {
 	name: "dump",
@@ -40,7 +40,7 @@ const entitiesCommandMeta = {
 };
 const analyzeCommandMeta = {
 	name: "analyze",
-	description: "SEO analysis tools"
+	description: "Run an Analyzer over Search Console rows"
 };
 const reportCommandMeta = {
 	name: "report",

package/dist/commands/auth.mjs

@@ -1,5 +1,5 @@
 import { useCliRuntime } from "../runtime.mjs";
-import { clearAuthentication, formatHostedSync, getHostedAccount, parseAuthMode, parseAuthentication, resolveAuthentication, revokeHostedSession, saveAuthentication } from "../auth-state.mjs";
+import { clearAuthentication, formatHostedSync, getHostedAccount, noSitesNextStep, parseAuthMode, parseAuthentication, resolveAuthentication, revokeHostedSession, saveAuthentication, siteManagerOf } from "../auth-state.mjs";
 import { authCommandMeta } from "../command-meta.mjs";
 import { loadConfig, saveConfig } from "../config.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
@@ -28,6 +28,9 @@ async function requireLocalAuth(args) {
 	if ((await resolveAuthentication())._tag === "Hosted") throw new Error("Google scopes and token refresh apply to Local mode only. Hosted mode uses a gscdump.com CLI session.");
 }
 const HOSTED_MODE_NOTE = "Hosted mode reads your gscdump.com record. Commands that call Google need Local mode.";
+function loginNextStep(state, siteCount, issuer) {
+	return siteCount > 0 ? "Next: run `gscdump sites` to see each Site and its sync state." : noSitesNextStep(siteManagerOf(state, issuer));
+}
 const HOSTED_COMMANDS = [
 	"sites",
 	"query",
@@ -71,6 +74,7 @@ async function loginHosted(args) {
 		await saveAuthentication(state);
 		logger.success(`Hosted mode saved for ${account.user.email}`);
 		logger.info(HOSTED_MODE_NOTE);
+		logger.info(loginNextStep(state, account.sites.length, account.issuer));
 		return;
 	}
 	const state = parseAuthentication({
@@ -83,6 +87,7 @@ async function loginHosted(args) {
 	await saveAuthentication(state);
 	logger.success(`Hosted mode saved for ${account.user.email}`);
 	logger.info(HOSTED_MODE_NOTE);
+	logger.info(loginNextStep(state, account.sites.length, account.issuer));
 }
 async function resolveLiveAuthState() {
 	const tokens = await loadTokens();
@@ -158,6 +163,7 @@ async function runStatus(args) {
 			console.log(`  API: ${authentication.apiRoot}`);
 			console.log(`  Sites: ${sites.length}`);
 			for (const site of sites) console.log(`    ${site.siteUrl}  ${formatHostedSync(site)}`);
+			if (sites.length === 0) console.log(`  ${noSitesNextStep(siteManagerOf(authentication, account.value.issuer))}`);
 			console.log(`  ${HOSTED_MODE_NOTE}`);
 			console.log(`  Hosted commands: ${HOSTED_COMMANDS.join(", ")}`);
 		}
@@ -263,17 +269,13 @@ const refreshCommand = defineCommand({
 			return;
 		}
 		const tokens = await loadTokens();
-		if (!tokens?.refresh_token) {
-			logger.error("No saved refresh token. Run `gscdump auth login`.");
-			process.exit(1);
-		}
+		if (!tokens?.refresh_token) throw new Error("No saved refresh token. Run `gscdump auth login`.");
 		await saveTokens({
 			...tokens,
 			expiry_date: 1
 		});
 		if ((await getAuth({ interactive: false }).catch((e) => {
-			logger.error(`Refresh failed: ${e.message}`);
-			process.exit(1);
+			throw new Error(`Refresh failed: ${e.message}`, { cause: e });
 		})).credentials?.access_token) logger.success("Token refreshed");
 		else logger.warn("Refresh completed but no new access token returned");
 	}
@@ -323,12 +325,10 @@ const loginCommand = defineCommand({
 		if (args["service-account"]) {
 			const saPath = path.resolve(String(args["service-account"]));
 			const jwt = await loadServiceAccount(saPath).catch((e) => {
-				logger.error(`Service-account load failed: ${e.message}`);
-				process.exit(1);
+				throw new Error(`Service-account load failed: ${e.message}`, { cause: e });
 			});
 			await jwt.authorize().catch((e) => {
-				logger.error(`Service-account auth failed: ${e.message}`);
-				process.exit(1);
+				throw new Error(`Service-account auth failed: ${e.message}`, { cause: e });
 			});
 			const config = await loadConfig();
 			config.serviceAccountPath = saPath;
@@ -343,8 +343,7 @@ const loginCommand = defineCommand({
 			noBrowser: args.browser === false,
 			force: Boolean(args.force)
 		}).catch((e) => {
-			logger.error(`Login failed: ${e.message}`);
-			process.exit(1);
+			throw new Error(`Login failed: ${e.message}`, { cause: e });
 		});
 		logger.success("Logged in");
 		await runSmokeTest(oauth);

package/dist/commands/config.mjs

@@ -1,3 +1,4 @@
+import { commandLineError } from "../stop.mjs";
 import { configCommandMeta } from "../command-meta.mjs";
 import { getConfigPath, loadConfig, resolveDataDir, saveConfig } from "../config.mjs";
 import { OUTPUT_ARGS, applyOutputMode, displayPath, logger } from "../utils.mjs";
@@ -71,18 +72,11 @@ const setCommand = defineCommand({
 	},
 	async run({ args }) {
 		applyOutputMode(args);
-		if (!VALID_KEYS.includes(args.key)) {
-			logger.error(`Invalid key: ${args.key}`);
-			logger.info(`Valid keys: ${VALID_KEYS.join(", ")}`);
-			process.exit(1);
-		}
+		if (!VALID_KEYS.includes(args.key)) throw commandLineError(`Invalid key: ${args.key}. Valid keys: ${VALID_KEYS.join(", ")}`);
 		const config = await loadConfig();
 		const value = NUMERIC_KEYS.has(args.key) ? Number(args.value) : args.key === "defaultSite" ? await canonicalSite(args.value) : args.value;
-		if (NUMERIC_KEYS.has(args.key) && !Number.isFinite(value)) {
-			logger.error(`Invalid numeric value for ${args.key}: ${args.value}`);
-			process.exit(1);
-		}
-		config[args.key] = value;
+		if (NUMERIC_KEYS.has(args.key) && !Number.isFinite(value)) throw commandLineError(`Invalid numeric value for ${args.key}: ${args.value}`);
+		Object.assign(config, { [args.key]: value });
 		await saveConfig(config);
 		logger.success(`Set ${args.key} = ${value}`);
 	}
@@ -102,11 +96,7 @@ const unsetCommand = defineCommand({
 	},
 	async run({ args }) {
 		applyOutputMode(args);
-		if (!VALID_KEYS.includes(args.key)) {
-			logger.error(`Invalid key: ${args.key}`);
-			logger.info(`Valid keys: ${VALID_KEYS.join(", ")}`);
-			process.exit(1);
-		}
+		if (!VALID_KEYS.includes(args.key)) throw commandLineError(`Invalid key: ${args.key}. Valid keys: ${VALID_KEYS.join(", ")}`);
 		const config = await loadConfig();
 		delete config[args.key];
 		await saveConfig(config);

package/dist/commands/doctor.mjs

@@ -339,7 +339,7 @@ async function checkHostedConnection(authentication) {
 	} : {
 		name: "hosted.sites",
 		status: "warn",
-		detail: `no hosted Sites. ${connectSiteStep(siteManagerOf(authentication))}`
+		detail: `no hosted Sites. ${connectSiteStep(siteManagerOf(authentication, account.value.issuer))}`
 	}];
 	return [
 		{

package/dist/commands/dump.mjs

@@ -1,3 +1,4 @@
+import { commandLineError } from "../stop.mjs";
 import { dumpCommandMeta } from "../command-meta.mjs";
 import { ALL_SEARCH_TYPES, OUTPUT_ARGS, applyOutputMode, displayPath, logger, parseNameList, parseSearchType } from "../utils.mjs";
 import { allTables } from "../local-store.mjs";
@@ -70,10 +71,7 @@ const dumpCommand = defineCommand({
 	async run({ args }) {
 		const { json, quiet } = applyOutputMode(args);
 		const format = String(args.format);
-		if (!isDumpFormat(format)) {
-			logger.error(`Invalid --format: ${format}. Allowed: ${DUMP_FORMATS.join(", ")}`);
-			process.exit(1);
-		}
+		if (!isDumpFormat(format)) throw commandLineError(`Invalid --format: ${format}. Allowed: ${DUMP_FORMATS.join(", ")}`);
 		const tablesFilter = args.tables ? new Set(parseNameList(args.tables, [
 			...allTables(),
 			...ENTITY_DATASETS,

package/dist/commands/entities.mjs

@@ -55,10 +55,7 @@ const showSubCommand = defineCommand({
 			userId: store.userId,
 			siteId: store.siteIdFor(siteUrl)
 		}, String(args.url));
-		if (!record) {
-			logger.warn(`No inspection record for ${args.url}`);
-			process.exit(1);
-		}
+		if (!record) throw new Error(`No inspection record for ${args.url}`);
 		if (json) {
 			console.log(JSON.stringify(record, null, 2));
 			return;
@@ -114,10 +111,7 @@ const indexingSnapshotSubCommand = defineCommand({
 			return;
 		}
 		const claim = await recordStoreSite(store.dataDir, siteUrl, { userId: store.userId });
-		if (!claim.ok) {
-			logger.error(formatSiteIdCollision(claim.error));
-			process.exit(1);
-		}
+		if (!claim.ok) throw new Error(formatSiteIdCollision(claim.error));
 		const records = [];
 		const failures = [];
 		let completed = 0;
@@ -155,7 +149,7 @@ const indexingSnapshotSubCommand = defineCommand({
 				if (failures.length > 5) console.log(`  ... and ${failures.length - 5} more`);
 			}
 		}
-		if (failures.length > 0) process.exit(1);
+		if (failures.length > 0) throw new Error(`${failures.length} of ${urls.length} URL(s) failed. First: ${failures[0].url}: ${failures[0].error}`);
 	}
 });
 const indexingSubCommand = defineCommand({

package/dist/commands/indexing-watch.mjs

@@ -1,4 +1,4 @@
-import { siteManagerOf, siteSettingsPlace } from "../auth-state.mjs";
+import { siteSettingsPlace } from "../auth-state.mjs";
 import { terminalOutputOptions } from "../render/terminal.mjs";
 import { applyOutputMode, logger, readUrlList } from "../utils.mjs";
 import { renderTable } from "../render/layout.mjs";
@@ -136,7 +136,7 @@ const addCommand = defineCommand({
 	async run({ args }) {
 		const { json } = applyOutputMode(args);
 		const urls = await readUrls(args);
-		const { client, site, authentication } = await resolveHostedSite({
+		const { client, site, siteManager } = await resolveHostedSite({
 			...args,
 			_: []
 		}, {
@@ -151,7 +151,7 @@ const addCommand = defineCommand({
 			console.log(JSON.stringify(data, null, 2));
 			return;
 		}
-		printChange("Added", data, site.siteUrl, siteManagerOf(authentication));
+		printChange("Added", data, site.siteUrl, siteManager);
 	}
 });
 const removeCommand = defineCommand({
@@ -167,7 +167,7 @@ const removeCommand = defineCommand({
 	async run({ args }) {
 		const { json } = applyOutputMode(args);
 		const urls = await readUrls(args);
-		const { client, site, authentication } = await resolveHostedSite({
+		const { client, site, siteManager } = await resolveHostedSite({
 			...args,
 			_: []
 		}, {
@@ -182,7 +182,7 @@ const removeCommand = defineCommand({
 			console.log(JSON.stringify(data, null, 2));
 			return;
 		}
-		printChange("Removed", data, site.siteUrl, siteManagerOf(authentication));
+		printChange("Removed", data, site.siteUrl, siteManager);
 	}
 });
 const indexingWatchCommand = defineCommand({

package/dist/commands/indexing.mjs

@@ -1,3 +1,4 @@
+import { commandLineError } from "../stop.mjs";
 import { indexingCommandMeta } from "../command-meta.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, parseIntegerOption, readUrlList } from "../utils.mjs";
 import { createCommandContext } from "../context.mjs";
@@ -5,7 +6,6 @@ import { loadSitemapUrls } from "../sitemap.mjs";
 import { indexingSummaryCommand } from "./indexing-summary.mjs";
 import { indexingUrlsCommand } from "./indexing-urls.mjs";
 import { indexingWatchCommand } from "./indexing-watch.mjs";
-import process from "node:process";
 import { defineCommand } from "citty";
 import { batchRequestIndexing, getIndexingMetadata, requestIndexing, runSequentialBatch } from "gscdump/indexing";
 const RETRIES_ARG = { retries: {
@@ -16,10 +16,7 @@ async function resolveUrlSource(args) {
 	const fromSitemap = args["from-sitemap"];
 	if (fromSitemap) {
 		const result = await loadSitemapUrls(String(fromSitemap));
-		if (result._tag === "error") {
-			logger.error(`Sitemap fetch failed: ${result.message}`);
-			process.exit(1);
-		}
+		if (result._tag === "error") throw new Error(`Sitemap fetch failed: ${result.message}`);
 		if (!result.value.complete) logger.warn("Sitemap walk was incomplete; indexing only the URLs that were read");
 		return result.value.urls;
 	}
@@ -214,20 +211,10 @@ const batchCommand = defineCommand({
 		const delayMs = parseIntegerOption(args["delay-ms"], "--delay-ms", 0) ?? 100;
 		const concurrency = parseIntegerOption(args.concurrency, "--concurrency") ?? 1;
 		const urls = await resolveUrlSource(args);
-		if (urls.length === 0) {
-			logger.error("No URLs provided. Pass URLs as args, --file, --from-sitemap, or stdin.");
-			process.exit(1);
-		}
+		if (urls.length === 0) throw commandLineError("No URLs provided. Pass URLs as args, --file, --from-sitemap, or stdin.");
 		const type = String(args.type);
-		if (type !== "URL_UPDATED" && type !== "URL_DELETED") {
-			logger.error(`Invalid --type: ${type}. Use URL_UPDATED or URL_DELETED.`);
-			process.exit(1);
-		}
-		if (urls.length > INDEXING_DAILY_QUOTA && !args.yes && !args.json) {
-			logger.warn(`Submitting ${urls.length} URLs but the Indexing API daily quota is ${INDEXING_DAILY_QUOTA}/day.`);
-			logger.warn(`Excess submissions will fail with quota errors. Pass --yes to proceed anyway.`);
-			process.exit(1);
-		}
+		if (type !== "URL_UPDATED" && type !== "URL_DELETED") throw commandLineError(`Invalid --type: ${type}. Use URL_UPDATED or URL_DELETED.`);
+		if (urls.length > INDEXING_DAILY_QUOTA && !args.yes && !args.json) throw commandLineError(`Submitting ${urls.length} URLs but the Indexing API daily quota is ${INDEXING_DAILY_QUOTA}/day. Excess submissions will fail with quota errors. Pass --yes to proceed anyway.`);
 		if (urls.length > INDEXING_DAILY_QUOTA && !args.json && !args.quiet) logger.warn(`Proceeding with ${urls.length} URLs (over the ${INDEXING_DAILY_QUOTA}/day quota). Excess will fail.`);
 		const ctx = await createCommandContext({
 			needsAuth: true,
@@ -290,10 +277,7 @@ const batchStatusCommand = defineCommand({
 		const delayMs = parseIntegerOption(args["delay-ms"], "--delay-ms", 0) ?? 100;
 		const concurrency = parseIntegerOption(args.concurrency, "--concurrency") ?? 1;
 		const urls = await resolveUrlSource(args);
-		if (urls.length === 0) {
-			logger.error("No URLs provided. Pass URLs as args, --file, --from-sitemap, or stdin.");
-			process.exit(1);
-		}
+		if (urls.length === 0) throw commandLineError("No URLs provided. Pass URLs as args, --file, --from-sitemap, or stdin.");
 		const ctx = await createCommandContext({
 			needsAuth: true,
 			fetchOptions: { retry }

package/dist/commands/init.mjs

@@ -100,10 +100,7 @@ const initCommand = defineCommand({
 			return;
 		}
 		if (!canPrompt()) {
-			if (!await loadTokens()) {
-				logger.error(`Init cannot prompt without a terminal.\n${ACCESS_NOT_SET_UP}`);
-				process.exit(1);
-			}
+			if (!await loadTokens()) throw new Error(`Init cannot prompt without a terminal.\n${ACCESS_NOT_SET_UP}`);
 			await saveConfig({
 				...config,
 				dataDir: config.dataDir ?? defaultDataDir()
@@ -114,7 +111,7 @@ const initCommand = defineCommand({
 			return;
 		}
 		console.log();
-		console.log("  \x1B[1mWelcome to GSCDump!\x1B[0m");
+		console.log("  \x1B[1mWelcome to gscdump\x1B[0m");
 		console.log("  \x1B[90mGoogle Search Console data extraction CLI\x1B[0m");
 		console.log();
 		const dataDir = args.store ? await promptDataDir(config.dataDir) : void 0;

package/dist/commands/papercut.mjs

@@ -62,10 +62,7 @@ const papercutCommand = defineCommand({
 			fetch: globalThis.fetch,
 			url
 		});
-		if (result._tag === "Err") {
-			logger.error(result.message);
-			process.exit(1);
-		}
+		if (result._tag === "Err") throw new Error(result.message);
 		if (json) {
 			console.log(JSON.stringify(result.receipt));
 			return;

package/dist/commands/profile.mjs

@@ -1,4 +1,5 @@
 import { useCliRuntime } from "../runtime.mjs";
+import { commandLineError } from "../stop.mjs";
 import { profileCommandMeta } from "../command-meta.mjs";
 import { getConfigDir, setConfigDir } from "../config.mjs";
 import { resolveCliEnvironment } from "../environment.mjs";
@@ -100,10 +101,7 @@ const pathCmd = defineCommand({
 	} },
 	async run({ args }) {
 		const name = args.name ? String(args.name) : resolveActiveProfile();
-		if (!name) {
-			logger.error("No profile specified and none active (set --profile, GSCDUMP_PROFILE, or run `gscdump profile use <name>`)");
-			process.exit(1);
-		}
+		if (!name) throw commandLineError("No profile specified and none active (set --profile, GSCDUMP_PROFILE, or run `gscdump profile use <name>`)");
 		console.log(getProfileDir(name));
 	}
 });
@@ -135,11 +133,7 @@ const useCmd = defineCommand({
 		applyOutputMode(args);
 		const name = String(args.name);
 		const dir = getProfileDir(name);
-		if (!await fs.stat(dir).then(() => true).catch(() => false)) {
-			logger.error(`Profile not found: ${name}`);
-			logger.info(`Create it with: gscdump profile create ${name}`);
-			process.exit(1);
-		}
+		if (!await fs.stat(dir).then(() => true).catch(() => false)) throw new Error(`Profile not found: ${name}. Create it with: gscdump profile create ${name}`);
 		await setActiveProfile(name);
 		logger.success(`Active profile: ${name}`);
 	}
@@ -207,10 +201,7 @@ const deleteCmd = defineCommand({
 		applyOutputMode(args);
 		const name = String(args.name);
 		const dir = getProfileDir(name);
-		if (!await fs.stat(dir).then(() => true).catch(() => false)) {
-			logger.error(`Profile not found: ${name}`);
-			process.exit(1);
-		}
+		if (!await fs.stat(dir).then(() => true).catch(() => false)) throw new Error(`Profile not found: ${name}`);
 		if (!args.yes) {
 			const ok = await confirm({
 				message: `Delete profile "${name}" at ${dir}? Tokens and config will be lost.`,

package/dist/commands/query.mjs

@@ -1,4 +1,5 @@
 import { useCliRuntime } from "../runtime.mjs";
+import { commandLineError } from "../stop.mjs";
 import { resolveAuthentication } from "../auth-state.mjs";
 import { queryCommandMeta } from "../command-meta.mjs";
 import { loadConfig } from "../config.mjs";
@@ -211,10 +212,7 @@ const queryCommand = defineCommand({
 	async run({ args }) {
 		const ctxConfig = await loadConfig();
 		const format = args.format ?? ctxConfig.defaultFormat ?? "json";
-		if (format !== "json" && format !== "csv" && format !== "table") {
-			logger.error("Invalid --format. Use table, json, or csv.");
-			process.exit(1);
-		}
+		if (format !== "json" && format !== "csv" && format !== "table") throw commandLineError("Invalid --format. Use table, json, or csv.");
 		setJsonOutput(format === "json");
 		if (args.sql || args.schema) {
 			await runSqlMode({
@@ -234,31 +232,19 @@ const queryCommand = defineCommand({
 		const dimNames = await resolveDimensions(args);
 		const windowFlags = await promptRange(args);
 		const invalidWindow = checkWindowFlags(windowFlags);
-		if (invalidWindow) {
-			logger.error(invalidWindow.message);
-			process.exit(1);
-		}
+		if (invalidWindow) throw commandLineError(invalidWindow.message);
 		await promptFilters(args);
 		const limitArg = String(args.limit ?? ctxConfig.defaultLimit ?? 1e3);
 		const rowLimit = Number(limitArg);
-		if (!POSITIVE_INTEGER_RE.test(limitArg) || !Number.isSafeInteger(rowLimit) || rowLimit < 1) {
-			logger.error("Invalid --limit. Use a positive safe integer, such as --limit 1000.");
-			process.exit(1);
-		}
+		if (!POSITIVE_INTEGER_RE.test(limitArg) || !Number.isSafeInteger(rowLimit) || rowLimit < 1) throw commandLineError("Invalid --limit. Use a positive safe integer, such as --limit 1000.");
 		const filters = parseFilterArgs(args);
 		const searchType = parseSearchType(args.type ?? ctxConfig.defaultSearchType, "--type");
 		const localSearchType = searchType ?? "web";
 		const dataState = args["data-state"] ? String(args["data-state"]) : ctxConfig.defaultDataState;
 		const aggregationType = args["aggregation-type"] ? String(args["aggregation-type"]) : void 0;
 		const filterDims = filterDimensions(filters);
-		if (dataState && !DATA_STATES.includes(dataState)) {
-			logger.error(`Invalid --data-state: ${dataState}. Allowed: ${DATA_STATES.join(", ")}`);
-			process.exit(1);
-		}
-		if (aggregationType && !AGGREGATION_TYPES.includes(aggregationType)) {
-			logger.error(`Invalid --aggregation-type: ${aggregationType}. Allowed: ${AGGREGATION_TYPES.join(", ")}`);
-			process.exit(1);
-		}
+		if (dataState && !DATA_STATES.includes(dataState)) throw commandLineError(`Invalid --data-state: ${dataState}. Allowed: ${DATA_STATES.join(", ")}`);
+		if (aggregationType && !AGGREGATION_TYPES.includes(aggregationType)) throw commandLineError(`Invalid --aggregation-type: ${aggregationType}. Allowed: ${AGGREGATION_TYPES.join(", ")}`);
 		const forceLive = Boolean(args.live);
 		if (!forceLive && (await resolveAuthentication())._tag === "Hosted") {
 			if (dataState || aggregationType) logger.warn("--data-state / --aggregation-type are ignored without --live");
@@ -417,10 +403,7 @@ const queryCommand = defineCommand({
 			table,
 			searchType: localSearchType,
 			...probe ? { profiler: probe.profiler } : {}
-		}, state).catch((e) => {
-			logger.error(`Query failed: ${e.message}`);
-			process.exit(1);
-		});
+		}, state);
 		if (probe) logProfile(probe.spans);
 		await writeOutput({
 			output: {
@@ -443,10 +426,7 @@ const queryCommand = defineCommand({
 async function resolveDimensions(args) {
 	if (args.dimensions != null) {
 		const dimensions = String(args.dimensions).split(",").map((d) => d.trim());
-		if (dimensions.some((d) => !DIMENSIONS.includes(d))) {
-			logger.error(`Invalid --dimensions. Use a comma-separated list from: ${DIMENSIONS.join(", ")}.`);
-			process.exit(1);
-		}
+		if (dimensions.some((d) => !DIMENSIONS.includes(d))) throw commandLineError(`Invalid --dimensions. Use a comma-separated list from: ${DIMENSIONS.join(", ")}.`);
 		return [...new Set(dimensions)];
 	}
 	if (args.interactive) {
@@ -500,10 +480,7 @@ async function promptRange(args) {
 }
 function windowOrExit(flags, anchor) {
 	const window = parseWindowFlags(flags, DEFAULT_WINDOW, anchor);
-	if (!window.ok) {
-		logger.error(window.error.message);
-		process.exit(1);
-	}
+	if (!window.ok) throw commandLineError(window.error.message);
 	return window.value;
 }
 async function promptFilters(args) {
@@ -620,8 +597,7 @@ async function runSql(views, sql) {
 	for (const warning of warnings) logger.warn(warning);
 	return {
 		...await views.run(sql).catch((e) => {
-			logger.error(`SQL failed: ${e.message}`);
-			process.exit(1);
+			throw new Error(`SQL failed: ${e.message}`, { cause: e });
 		}),
 		warnings
 	};

package/dist/commands/sitemaps.mjs

@@ -3,7 +3,6 @@ import { OUTPUT_ARGS, applyOutputMode, logger, parseIntegerOption, plural } from
 import { createCommandContext } from "../context.mjs";
 import { HOSTED_ARGS, resolveHostedSite } from "../hosted-site.mjs";
 import { discoverLiveSitemap, loadSitemapUrls } from "../sitemap.mjs";
-import process from "node:process";
 import { defineCommand } from "citty";
 import { fetchSitemap } from "gscdump/sites";
 const HOSTED_SITEMAP_ALTERNATIVE = "read a live sitemap with `gscdump sitemaps urls <sitemap-url>`";
@@ -207,14 +206,8 @@ const discoverCommand = defineCommand({
 			}, null, 2));
 			return;
 		}
-		if (discovery._tag === "incomplete") {
-			logger.error(`Sitemap discovery was incomplete: ${discovery.failures[0] ?? "unknown failure"}`);
-			process.exit(1);
-		}
-		if (!url) {
-			logger.warn(`No sitemap discovered for ${domain}`);
-			process.exit(1);
-		}
+		if (discovery._tag === "incomplete") throw new Error(`Sitemap discovery was incomplete: ${discovery.failures[0] ?? "unknown failure"}`);
+		if (!url) throw new Error(`No sitemap discovered for ${domain}`);
 		logger.success(`Discovered sitemap: ${url}`);
 	}
 });

package/dist/commands/sites.mjs

@@ -1,3 +1,4 @@
+import { commandLineError } from "../stop.mjs";
 import { connectSiteStep, formatHostedSync, getHostedAccount, localModeRequired, resolveAuthentication, siteManagerOf } from "../auth-state.mjs";
 import { sitesCommandMeta } from "../command-meta.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, plural } from "../utils.mjs";
@@ -20,16 +21,10 @@ function pickDefaultMethod(siteUrl) {
 }
 function validateMethod(siteUrl, method) {
 	const upper = method.toUpperCase();
-	if (!ALL_METHODS.includes(upper)) {
-		logger.error(`Invalid --method: ${method}. Valid: ${ALL_METHODS.join(", ")}`);
-		process.exit(1);
-	}
+	if (!ALL_METHODS.includes(upper)) throw commandLineError(`Invalid --method: ${method}. Valid: ${ALL_METHODS.join(", ")}`);
 	const site = siteUrlToVerificationSite(siteUrl);
 	const allowed = verificationMethodsFor(site);
-	if (!allowed.includes(upper)) {
-		logger.error(`Method ${upper} not valid for ${site.type === "INET_DOMAIN" ? "domain" : "URL-prefix"} property "${siteUrl}". Valid: ${allowed.join(", ")}`);
-		process.exit(1);
-	}
+	if (!allowed.includes(upper)) throw commandLineError(`Method ${upper} not valid for ${site.type === "INET_DOMAIN" ? "domain" : "URL-prefix"} property "${siteUrl}". Valid: ${allowed.join(", ")}`);
 	return upper;
 }
 function printPlacementInstructions(method, siteUrl, token) {
@@ -423,7 +418,7 @@ const LIST_ARGS = {
 };
 async function runListHostedSites(args, authentication) {
 	if (args["with-sitemaps"] || args["owner-only"]) throw localModeRequired("--with-sitemaps and --owner-only read Search Console permissions.");
-	const { sites } = await getHostedAccount(authentication);
+	const { sites, issuer } = await getHostedAccount(authentication);
 	if (args.json) {
 		console.log(JSON.stringify(sites.map((site) => ({
 			siteId: site.siteId,
@@ -438,7 +433,7 @@ async function runListHostedSites(args, authentication) {
 		return;
 	}
 	if (sites.length === 0) {
-		logger.warn(`Your hosted record has no Sites. ${connectSiteStep(siteManagerOf(authentication))}`);
+		logger.warn(`Your hosted record has no Sites. ${connectSiteStep(siteManagerOf(authentication, issuer))}`);
 		return;
 	}
 	logger.success(`Found ${plural(sites.length, "hosted Site", "hosted Sites")}:`);

package/dist/commands/skill.mjs

@@ -33,10 +33,7 @@ const installCommand = defineCommand({
 			homeDirectory: os.homedir(),
 			target: args.target
 		});
-		if (result._tag === "Err") {
-			logger.error(result.message);
-			process.exit(1);
-		}
+		if (result._tag === "Err") throw new Error(result.message);
 		if (json) {
 			console.log(JSON.stringify(result.installation));
 			return;

package/dist/commands/sync.mjs

@@ -395,10 +395,7 @@ const syncCommand = defineCommand({
 				siteUrls.push(siteUrl);
 				continue;
 			}
-			if (!args["all-sites"]) {
-				logger.error(formatSiteIdCollision(claim.error));
-				process.exit(1);
-			}
+			if (!args["all-sites"]) throw new Error(formatSiteIdCollision(claim.error));
 			logger.warn(`Skipped ${siteUrl}. ${formatSiteIdCollision(claim.error)}`);
 		}
 		const latest = getLatestGscDate();
@@ -416,10 +413,7 @@ const syncCommand = defineCommand({
 				now: Date.now(),
 				isAlive: isProcessAlive
 			});
-			if (existing.kind === "running") {
-				logger.error(`Another sync is running (pid ${existing.record.pid}, ${existing.record.done}/${existing.record.planned} days). Wait for it to finish, or run \`gscdump sync --status\`.`);
-				process.exit(1);
-			}
+			if (existing.kind === "running") throw new Error(`Another sync is running (pid ${existing.record.pid}, ${existing.record.done}/${existing.record.planned} days). Wait for it to finish, or run \`gscdump sync --status\`.`);
 		}
 		const ledger = await openQuotaLedger({ dataDir: store.dataDir });
 		const pacer = createRequestPacer({

package/dist/error-handler.mjs

@@ -1,4 +1,5 @@
-import { stopDetailsOf } from "./stop.mjs";
+import { HOSTED_SESSION_EXPIRED, isSessionExpiredError } from "./hosted-session.mjs";
+import { isUserStop, stopDetailsOf } from "./stop.mjs";
 import { isUsageError } from "./command-registry.mjs";
 import { describeRecordReadRefusal } from "./hosted-query.mjs";
 import { quotaStopOf } from "./quota-ledger.mjs";
@@ -128,7 +129,17 @@ function describeCliError(error) {
 	};
 	if (error instanceof Error && quotaStopOf(error)) return {
 		kind: "stop",
-		message: error.message
+		message: error.message,
+		stop: {
+			code: "QUOTA_USED_UP",
+			message: error.message,
+			nextCommand: null
+		}
+	};
+	if (isUserStop(error) && stop) return {
+		kind: "stop",
+		message: stop.message,
+		stop
 	};
 	if (error instanceof Error && stop) return {
 		kind: "expected",
@@ -157,6 +168,13 @@ function describeCliError(error) {
 		hint: error.mode === "local" ? "Pass --live to run against the GSC API." : "",
 		showAuthSources: false
 	};
+	if (isSessionExpiredError(error)) return {
+		kind: "expected",
+		message: HOSTED_SESSION_EXPIRED.message,
+		hint: "",
+		showAuthSources: false,
+		stop: HOSTED_SESSION_EXPIRED
+	};
 	const refusal = recordReadRefusalOf(error);
 	if (refusal) {
 		const text = describeRecordReadRefusal(refusal);
@@ -175,9 +193,33 @@ function describeCliError(error) {
 		showAuthSources: classified.kind === "auth-expired" || classified.kind === "permission-denied" || isAuthError(error)
 	};
 }
+function jsonErrorOf(report) {
+	switch (report.kind) {
+		case "usage": return {
+			code: "USAGE",
+			message: report.message,
+			nextCommand: null
+		};
+		case "stop": return report.stop ?? {
+			code: "FAILED",
+			message: report.message,
+			nextCommand: null
+		};
+		case "expected": return report.stop ?? {
+			code: "FAILED",
+			message: report.hint ? `${report.message} ${report.hint}` : report.message,
+			nextCommand: null
+		};
+		case "defect": return {
+			code: "UNEXPECTED",
+			message: report.message,
+			nextCommand: null
+		};
+	}
+}
 async function reportCliError(error, options) {
 	const report = describeCliError(error);
-	if (options.json && (report.kind === "stop" || report.kind === "expected") && report.stop) (options.writeStdout ?? ((value) => console.log(value)))(JSON.stringify({ error: report.stop }, null, 2));
+	if (options.json) (options.writeStdout ?? ((value) => console.log(value)))(JSON.stringify({ error: jsonErrorOf(report) }, null, 2));
 	const red = (text) => options.color ? `\x1B[31m${text}\x1B[0m` : text;
 	const lines = [];
 	switch (report.kind) {
@@ -198,4 +240,4 @@ async function reportCliError(error, options) {
 	const text = lines.join("\n");
 	(options.write ?? ((value) => console.error(value)))(options.color ? text : text.replace(ANSI_RE, ""));
 }
-export { LocalStoreUnsupportedError, describeCliError, flagForParam, isAuthError, reportCliError };
+export { LocalStoreUnsupportedError, describeCliError, flagForParam, isAuthError, jsonErrorOf, reportCliError };

package/dist/hosted-auth.mjs

@@ -1,3 +1,4 @@
+import { userStopError } from "./stop.mjs";
 import { z } from "zod";
 const ORIGIN = "https://gscdump.com";
 const pollSchema = z.discriminatedUnion("status", [z.object({ status: z.literal("pending") }), z.object({
@@ -5,6 +6,12 @@ const pollSchema = z.discriminatedUnion("status", [z.object({ status: z.literal(
 	sessionId: z.string().regex(/^[a-f0-9]{64}$/)
 })]);
 const HOSTED_LOGIN_FAILURE = "Hosted login failed. Run `gscdump auth login --mode hosted` to try again.";
+const LOGIN_CANCELLED = {
+	code: "LOGIN_CANCELLED",
+	message: "Login cancelled in the browser.",
+	nextCommand: "gscdump auth login --mode hosted"
+};
+const loginCancelledBodySchema = z.object({ data: z.object({ details: z.object({ reason: z.literal("login_cancelled") }) }) });
 async function requestJson(request, route, init = {}) {
 	const response = await request(`${ORIGIN}/api/cli/auth/${route}`, {
 		...init,
@@ -13,6 +20,7 @@ async function requestJson(request, route, init = {}) {
 	});
 	if (!response.ok) {
 		if (response.status === 429 || response.status >= 500) throw new Error("gscdump.com login is temporarily unavailable. Try again later.");
+		if (response.status === 403 && loginCancelledBodySchema.safeParse(await response.json().catch(() => null)).success) throw userStopError(LOGIN_CANCELLED);
 		throw new Error(HOSTED_LOGIN_FAILURE);
 	}
 	return response.json();
@@ -31,4 +39,4 @@ async function loginWithHostedSession(deps) {
 	}
 	throw new Error("Authorization expired. Run `gscdump auth login --mode hosted` to try again.");
 }
-export { loginWithHostedSession };
+export { LOGIN_CANCELLED, loginWithHostedSession };

package/dist/hosted-session.mjs

@@ -0,0 +1,17 @@
+import { z } from "zod";
+const sessionExpiredDetailsSchema = z.object({ reason: z.literal("session_expired") });
+const sessionExpiredBodySchema = z.union([z.object({ data: z.object({ details: sessionExpiredDetailsSchema }) }), z.object({ error: z.object({ details: sessionExpiredDetailsSchema }) })]);
+const HOSTED_SESSION_EXPIRED = {
+	code: "HOSTED_CREDENTIALS_REJECTED",
+	message: "Your gscdump.com session expired. Run `gscdump auth login --mode hosted`.",
+	nextCommand: "gscdump auth login --mode hosted"
+};
+function isSessionExpiredBody(body) {
+	return sessionExpiredBodySchema.safeParse(body).success;
+}
+function isSessionExpiredError(error) {
+	if (!(error instanceof Error) || error.name !== "GscdumpV1Error") return false;
+	const { status, details } = error;
+	return status === 401 && sessionExpiredDetailsSchema.safeParse(details).success;
+}
+export { HOSTED_SESSION_EXPIRED, isSessionExpiredBody, isSessionExpiredError };

package/dist/hosted-site.mjs

@@ -97,15 +97,18 @@ async function resolveHostedSite(args, command) {
 	});
 	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") throw stopError(siteMatchStop(match, siteManagerOf(authentication)));
+	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,
-		authentication
+		authentication,
+		siteManager
 	};
 }
 export { HOSTED_ARGS, matchHostedSite, noSitesStop, resolveHostedSite, siteMatchStop };

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "5.1.0";
+var version = "5.3.0";
 export { version };

package/dist/stop.mjs

@@ -7,4 +7,17 @@ function stopError(details, name = "StopError") {
 function stopDetailsOf(error) {
 	return error instanceof Error ? error.stopDetails : void 0;
 }
-export { stopDetailsOf, stopError };
+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,4 +1,5 @@
 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";
@@ -56,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;
@@ -145,7 +143,7 @@ function applyGradient(text) {
 }
 function showSplash() {
 	console.log();
-	console.log(`  ${applyGradient("GSC Dump")} v${VERSION}`);
+	console.log(`  ${applyGradient("gscdump")} v${VERSION}`);
 	console.log();
 }
 function clearLine() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "5.1.0",
+  "version": "5.3.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.1.0",
-    "@gscdump/contracts": "^5.1.0",
-    "@gscdump/engine": "^5.1.0",
-    "@gscdump/engine-gsc-api": "^5.1.0",
-    "@gscdump/sdk": "^5.1.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.0",
     "@modelcontextprotocol/sdk": "^1.30.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.1.0",
-    "gscdump": "^5.1.0",
+    "gscdump": "^5.3.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 [stop](#stops) with JSON output also prints `{ "error" }` on stdout.
+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
@@ -44,8 +44,10 @@ In Local mode, `googleAuthenticated: true` means Google accepted the credentials
 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. A browser login connects Sites on gscdump.com.
+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.
@@ -131,7 +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 routing stop with JSON output prints `{ "error" }` on stdout and exits 1. See [Stops](#stops).
+- 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.
@@ -226,20 +228,24 @@ 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, stdout gets `{ "error": { "code", "message", "nextCommand" } }`.
+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 |
@@ -251,6 +257,7 @@ A routing stop also has `siteUrl`. `STORE_RANGE_NOT_COVERED` adds `missingDates`
 | `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