@gscdump/cli 5.0.0 → 5.2.0

package/dist/analysis-local.mjs

@@ -1,5 +1,5 @@
-import { LocalStoreUnsupportedError } from "./error-handler.mjs";
 import { useCliRuntime } from "./runtime.mjs";
+import { LocalStoreUnsupportedError } from "./error-handler.mjs";
 import { logger } from "./utils.mjs";
 import { inferTable } from "./local-store.mjs";
 import { createCommandContext } from "./context.mjs";
@@ -174,7 +174,7 @@ async function resolveAnalysisSource(args) {
 		auth
 	});
 	const route = decideRoute(req, state);
-	if (route.kind === "syncing" || route.kind === "prompt") stopAtRoute(route, req, state.auth, { json: Boolean(args.json) });
+	if (route.kind === "syncing" || route.kind === "prompt") stopAtRoute(route, req, state.auth);
 	if (route.kind === "local") {
 		const source = createEngineQuerySource({
 			engine: store.engine,

package/dist/auth-state.mjs

@@ -1,15 +1,24 @@
-import { HOSTED_KEY_REJECTED } from "./error-handler.mjs";
+import { HOSTED_SESSION_EXPIRED, isSessionExpiredBody } from "./hosted-session.mjs";
 import { useCliRuntime } from "./runtime.mjs";
+import { stopError } from "./stop.mjs";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
 const HOSTED_SESSION_REJECTED = "gscdump.com rejected the CLI session. Run `gscdump auth login --mode hosted` again.";
+const HOSTED_KEY_REJECTED = "gscdump.com rejected the API key. Run `gscdump auth login --mode hosted --api-key KEY` with a valid key.";
 const LOCAL_MODE_REQUIRED = [
 	"This command calls Google, so it needs Local mode.",
 	"Hosted mode reads your gscdump.com record and never calls Google.",
 	"If you want Local mode, run `gscdump auth login --mode local`."
 ].join("\n");
+function localModeRequired(detail) {
+	return stopError({
+		code: "LOCAL_MODE_REQUIRED",
+		message: detail ? `${detail}\n${LOCAL_MODE_REQUIRED}` : LOCAL_MODE_REQUIRED,
+		nextCommand: "gscdump auth login --mode local"
+	});
+}
 const HOSTED_NOT_SET_UP = "Hosted credentials are missing. Run `gscdump auth login --mode hosted`, or set GSCDUMP_API_KEY.";
 const SAVED_STATE_INVALID = "The saved access mode is invalid. Run `gscdump auth login --mode local` or `gscdump auth login --mode hosted`.";
 const apiRootSchema = z.url().transform((value) => value.replace(/\/+$/, "")).refine((value) => {
@@ -129,7 +138,11 @@ async function resolveAuthentication() {
 		if (env.GSCDUMP_API_ROOT && env.GSCDUMP_API_ROOT.replace(/\/+$/, "") !== state.apiRoot) throw new Error("The API root changed. Run `gscdump auth login --mode hosted` for the new API root.");
 		return state;
 	}
-	throw new Error(HOSTED_NOT_SET_UP);
+	throw stopError({
+		code: "HOSTED_CREDENTIALS_MISSING",
+		message: HOSTED_NOT_SET_UP,
+		nextCommand: "gscdump auth login --mode hosted"
+	});
 }
 const hostedSiteSchema = z.object({
 	siteId: z.string(),
@@ -144,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}`, {
@@ -162,18 +181,52 @@ async function hostedRequest(state, route, options = {}) {
 		redirect: "error"
 	});
 	if (!response.ok) {
-		const message = response.status === 401 ? "sessionId" in state ? HOSTED_SESSION_REJECTED : HOSTED_KEY_REJECTED : `Hosted request failed (${response.status}) for ${route.split("?")[0]}. Check \`gscdump auth status\`.`;
-		throw Object.assign(new Error(message), {
+		const details = {
 			statusCode: response.status,
 			retryAfter: response.headers.get("retry-after"),
 			response
-		});
+		};
+		if (response.status === 401) {
+			const session = "sessionId" in state;
+			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
+			}), details);
+		}
+		throw Object.assign(/* @__PURE__ */ new Error(`Hosted request failed (${response.status}) for ${route.split("?")[0]}. Check \`gscdump auth status\`.`), details);
 	}
 	return response.status === 204 ? void 0 : response.json();
 }
 function hostedCredential(state) {
 	return "sessionId" in state ? state.sessionId : state.apiKey;
 }
+function siteManagerOf(state, issuer) {
+	if ("sessionId" in state) return { _tag: "gscdump" };
+	return issuer ?? { _tag: "key_issuer" };
+}
+function connectSitePlace(manager) {
+	switch (manager._tag) {
+		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";
+	}
+}
 async function getHostedAccount(state) {
 	const result = accountSchema.safeParse(await hostedRequest(state, "/cli/me"));
 	if (!result.success) throw new Error("gscdump.com returned invalid account data.");
@@ -183,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_NOT_SET_UP, HOSTED_SESSION_REJECTED, LOCAL_MODE_REQUIRED, clearAuthentication, formatHostedSync, getHostedAccount, hostedCredential, hostedRequest, parseAuthMode, parseAuthentication, resolveAccessMode, resolveAuthentication, revokeHostedSession, saveAuthentication };
+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-hosted.mjs

@@ -1,7 +1,10 @@
-import { getHostedAccount, hostedCredential } from "./auth-state.mjs";
+import { stopError } from "./stop.mjs";
+import { getHostedAccount, hostedCredential, siteManagerOf } from "./auth-state.mjs";
 import { logger } from "./utils.mjs";
 import { writeBingDump } from "./bing-data.mjs";
+import { noSitesStop } from "./hosted-site.mjs";
 import { createGscdumpV1Client } from "@gscdump/sdk/v1";
+const BING_SITES_COMMAND = "gscdump bing sites --json";
 function hostedBingClient(state) {
 	return createGscdumpV1Client({
 		apiRoot: state.apiRoot,
@@ -30,15 +33,33 @@ 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, 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);
-	if (requested.length === 0) throw new Error("No matching Bing site. Run `gscdump bing sites`.");
-	if (!input.allSites && requested.length > 1) throw new Error("Multiple Bing sites match. Use a site ID from `gscdump bing sites`.");
+	if (requested.length === 0) throw stopError({
+		code: "SITE_NOT_FOUND",
+		message: "No matching Bing site. Run `gscdump bing sites`.",
+		nextCommand: BING_SITES_COMMAND
+	});
+	if (!input.allSites && requested.length > 1) throw stopError({
+		code: "SITE_AMBIGUOUS",
+		message: "Multiple Bing sites match. Use a site ID from `gscdump bing sites`.",
+		nextCommand: BING_SITES_COMMAND
+	});
 	const connections = await loadHostedBingConnections(state, requested, { tolerateFailures: Boolean(input.allSites) });
 	const selected = input.allSites ? connections.filter((site) => site.connection._tag === "connected") : connections;
-	if (selected.length === 0) throw new Error("No matching Bing site. Run `gscdump bing sites`.");
-	if (input.requireConnected !== false && selected.some((site) => site.connection._tag !== "connected")) throw new Error("Bing is not connected. Run `gscdump bing login --site SITE_ID`.");
+	if (selected.length === 0) throw stopError({
+		code: "SITE_NOT_FOUND",
+		message: "No matching Bing site. Run `gscdump bing sites`.",
+		nextCommand: BING_SITES_COMMAND
+	});
+	const unconnected = input.requireConnected === false ? void 0 : selected.find((site) => site.connection._tag !== "connected");
+	if (unconnected) throw stopError({
+		code: "BING_NOT_CONNECTED",
+		message: `Bing is not connected for ${unconnected.siteUrl}. Run \`gscdump bing login --site ${unconnected.siteId}\`.`,
+		nextCommand: `gscdump bing login --site ${unconnected.siteId}`
+	});
 	return selected;
 }
 async function dumpHostedBingSite(state, site, outDir, options) {

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,10 +1,11 @@
-import { CLI_SUBCOMMANDS, resolveUsageTarget } from "./command-registry.mjs";
-import { reportCliError } from "./error-handler.mjs";
 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";
 import { resolveCliEnvironment } from "./environment.mjs";
 import { applyProfileFromCli } from "./commands/profile-selection.mjs";
+import { reportCliError } from "./error-handler.mjs";
 import { resolveOutputOptions, terminalOutputOptions } from "./render/terminal.mjs";
 import { VERSION, setNoColor, showSplash, withConfiguredOutput } from "./utils.mjs";
 import process from "node:process";
@@ -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,
@@ -96,21 +130,28 @@ async function runCli(opts = {}) {
 	runtime.rawArgs = [...input];
 	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 && !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/analyze.mjs

@@ -1,6 +1,6 @@
 import { analyzeCommandMeta } from "../command-meta.mjs";
 import { terminalOutputOptions } from "../render/terminal.mjs";
-import { logger, parseFetchBudget, parseIntegerOption, toCSV } from "../utils.mjs";
+import { logger, parseFetchBudget, parseIntegerOption, setJsonOutput, toCSV } from "../utils.mjs";
 import { DEFAULT_WINDOW, PERIOD_FLAGS, parseWindowFlags, windowFlagErrorToException } from "../window.mjs";
 import { analysisNeeds, analyzerTables, resolveAnalysisSource } from "../analysis-local.mjs";
 import { coverageWarning, renderAnalysis } from "../render/analysis.mjs";
@@ -176,10 +176,10 @@ function makeToolCommand(tool) {
 			].includes(args.format ?? "table")) throw new Error("Invalid --format. Use table, json, or csv.");
 			const baseParams = buildParams(tool, args);
 			const format = args.json ? "json" : String(args.format ?? "table");
+			setJsonOutput(format === "json");
 			const { runAnalysis, siteUrl, anchor } = await resolveAnalysisSource({
 				site: args.site,
 				live: !!args.live,
-				json: format === "json",
 				label: `analyze ${tool}`,
 				types: [tool],
 				anchorTables: analyzerTables(baseParams),

package/dist/commands/auth.mjs

@@ -1,6 +1,6 @@
-import { authCommandMeta } from "../command-meta.mjs";
 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";
 import { ACCESS_NOT_SET_UP, clearTokens, formatAuthProvenance, getAuth, loadServiceAccount, loadTokens, resolveBYOK, saveTokens } from "../auth.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/bing.mjs

@@ -1,6 +1,7 @@
-import { bingCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
+import { stopError } from "../stop.mjs";
 import { resolveAuthentication, saveAuthentication } from "../auth-state.mjs";
+import { bingCommandMeta } from "../command-meta.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, plural } from "../utils.mjs";
 import { BING_REDIRECT_URI, clearBingCredentials, getBingClient, loginBingOAuth, saveBingCredentials } from "../bing-auth.mjs";
 import { BING_DATASETS, dumpBingSite, parseBingDumpOptions, resolveBingSites, unwrapBing } from "../bing-data.mjs";
@@ -323,7 +324,11 @@ const bingCommand = defineCommand({
 			async run({ args }) {
 				applyOutputMode(args);
 				const authentication = await resolveAuthentication();
-				if (authentication._tag !== "Hosted") throw new Error("Hosted Bing connection verification needs Hosted mode. Pass --mode hosted.");
+				if (authentication._tag !== "Hosted") throw stopError({
+					code: "HOSTED_MODE_REQUIRED",
+					message: "Hosted Bing connection verification needs Hosted mode. Pass --mode hosted.",
+					nextCommand: "gscdump auth login --mode hosted"
+				});
 				const [site] = await resolveHostedBingSites(authentication, {
 					site: args.site,
 					requireConnected: false

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

@@ -1,5 +1,5 @@
+import { connectSiteStep, getHostedAccount, resolveAuthentication, siteManagerOf } from "../auth-state.mjs";
 import { doctorCommandMeta } from "../command-meta.mjs";
-import { getHostedAccount, resolveAuthentication } from "../auth-state.mjs";
 import { loadConfig } from "../config.mjs";
 import { pickCliEnvironmentValue, resolveCliEnvironment } from "../environment.mjs";
 import { OUTPUT_ARGS, applyOutputMode, displayPath, logger } from "../utils.mjs";
@@ -339,7 +339,7 @@ async function checkHostedConnection(authentication) {
 	} : {
 		name: "hosted.sites",
 		status: "warn",
-		detail: "no hosted Sites. Connect a Site at https://gscdump.com/app/onboarding?step=connect-sites"
+		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-urls.mjs

@@ -121,8 +121,8 @@ const indexingUrlsCommand = defineCommand({
 		if (limit > MAX_PAGE_SIZE) throw new Error(`--limit must be ${MAX_PAGE_SIZE} or less. Use --all to read every page.`);
 		const search = args.search ? String(args.search) : void 0;
 		applyOutputMode({
-			json: format !== "table",
-			quiet: args.quiet
+			json: format === "json",
+			quiet: Boolean(args.quiet) || format === "csv"
 		});
 		const filters = {
 			...status ? { status } : {},

package/dist/commands/indexing-watch.mjs

@@ -1,3 +1,4 @@
+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";
@@ -39,12 +40,14 @@ function watchedRow(entry) {
 		dueAt: entry.dueAt.slice(0, 10)
 	};
 }
-const SKIP_HINTS = { inspection_disabled: "gscdump never inspects this Site, so a Watched URL gets no Checkpoint. To use Watched URLs, turn on URL Inspection in the Site settings on gscdump.com." };
-function printChange(verb, result, siteUrl) {
+function skipHint(reason, manager) {
+	return reason === "inspection_disabled" ? `gscdump never inspects this Site, so a Watched URL gets no Checkpoint. To use Watched URLs, turn on URL Inspection ${siteSettingsPlace(manager)}.` : void 0;
+}
+function printChange(verb, result, siteUrl, manager) {
 	for (const url of result.changed) console.log(`${verb}: ${url}`);
 	for (const url of result.unchanged) console.log(`${verb === "Added" ? "Already watched" : "Not watched"}: ${url}`);
 	for (const { url, reason } of result.skipped) console.log(`Skipped (${reason}): ${url}`);
-	for (const hint of new Set(result.skipped.map(({ reason }) => SKIP_HINTS[reason]).filter(Boolean))) console.log(hint);
+	for (const hint of new Set(result.skipped.map(({ reason }) => skipHint(reason, manager)).filter(Boolean))) console.log(hint);
 	logger.info(`${siteUrl} has ${result.total} of ${result.limit} Watched URLs.`);
 }
 async function readUrls(args) {
@@ -133,7 +136,7 @@ const addCommand = defineCommand({
 	async run({ args }) {
 		const { json } = applyOutputMode(args);
 		const urls = await readUrls(args);
-		const { client, site } = await resolveHostedSite({
+		const { client, site, siteManager } = await resolveHostedSite({
 			...args,
 			_: []
 		}, {
@@ -148,7 +151,7 @@ const addCommand = defineCommand({
 			console.log(JSON.stringify(data, null, 2));
 			return;
 		}
-		printChange("Added", data, site.siteUrl);
+		printChange("Added", data, site.siteUrl, siteManager);
 	}
 });
 const removeCommand = defineCommand({
@@ -164,7 +167,7 @@ const removeCommand = defineCommand({
 	async run({ args }) {
 		const { json } = applyOutputMode(args);
 		const urls = await readUrls(args);
-		const { client, site } = await resolveHostedSite({
+		const { client, site, siteManager } = await resolveHostedSite({
 			...args,
 			_: []
 		}, {
@@ -179,7 +182,7 @@ const removeCommand = defineCommand({
 			console.log(JSON.stringify(data, null, 2));
 			return;
 		}
-		printChange("Removed", data, site.siteUrl);
+		printChange("Removed", data, site.siteUrl, siteManager);
 	}
 });
 const indexingWatchCommand = defineCommand({