@gscdump/cli 5.0.0 → 5.1.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,23 @@
-import { HOSTED_KEY_REJECTED } from "./error-handler.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 +137,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(),
@@ -162,18 +174,41 @@ 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;
+			throw Object.assign(stopError({
+				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) {
+	return "sessionId" in state ? { _tag: "gscdump" } : { _tag: "key_issuer" };
+}
+function connectSiteStep(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.";
+	}
+}
+function siteSettingsPlace(manager) {
+	switch (manager._tag) {
+		case "gscdump": return "in the Site settings on gscdump.com";
+		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 +218,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, 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)));
 	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.mjs

@@ -1,10 +1,10 @@
-import { CLI_SUBCOMMANDS, resolveUsageTarget } from "./command-registry.mjs";
-import { reportCliError } from "./error-handler.mjs";
 import { createCliRuntime, runWithCliRuntime, useCliRuntime } from "./runtime.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";
@@ -96,6 +96,7 @@ async function runCli(opts = {}) {
 	runtime.rawArgs = [...input];
 	return runWithCliRuntime(runtime, async () => {
 		let rawArgs = [...input];
+		runtime.jsonOutput = false;
 		try {
 			rawArgs = prepareCliArgs(input);
 			runtime.rawArgs = [...rawArgs];
@@ -106,6 +107,7 @@ async function runCli(opts = {}) {
 		} catch (error) {
 			await reportCliError(error, {
 				color: stderrColor(runtime, rawArgs),
+				json: runtime.jsonOutput,
 				usage: async () => renderUsage(...await resolveUsageTarget(main, rawArgs)),
 				authSources: async () => (await import("./auth.mjs")).formatAuthProvenance()
 			});

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 { 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";

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/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))}`
 	}];
 	return [
 		{

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 { siteManagerOf, 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, authentication } = 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, siteManagerOf(authentication));
 	}
 });
 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, authentication } = 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, siteManagerOf(authentication));
 	}
 });
 const indexingWatchCommand = defineCommand({

package/dist/commands/init.mjs

@@ -1,6 +1,6 @@
-import { initCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
 import { saveAuthentication } from "../auth-state.mjs";
+import { initCommandMeta } from "../command-meta.mjs";
 import { defaultDataDir, loadConfig, saveConfig } from "../config.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
 import { ACCESS_NOT_SET_UP, getAuth, loadTokens, resolveBYOK, resolveServiceAccount } from "../auth.mjs";

package/dist/commands/mcp.mjs

@@ -1,5 +1,5 @@
-import { mcpCommandMeta } from "../command-meta.mjs";
 import { runWithCliRuntime, useCliRuntime } from "../runtime.mjs";
+import { mcpCommandMeta } from "../command-meta.mjs";
 import { VERSION } from "../utils.mjs";
 import { probeAuth } from "../auth.mjs";
 import { createCommandContext } from "../context.mjs";

package/dist/commands/papercut.mjs

@@ -1,5 +1,5 @@
-import { papercutCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
+import { papercutCommandMeta } from "../command-meta.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
 import { buildPapercutBody, resolvePapercutUrl, submitPapercut } from "../papercut.mjs";
 import process from "node:process";

package/dist/commands/profile.mjs

@@ -1,5 +1,5 @@
-import { profileCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
+import { profileCommandMeta } from "../command-meta.mjs";
 import { getConfigDir, setConfigDir } from "../config.mjs";
 import { resolveCliEnvironment } from "../environment.mjs";
 import { ACTIVE_MARKER, PROFILES_DIR, ROOT_DIR, getProfileDir, readActiveMarkerSync } from "./profile-selection.mjs";

package/dist/commands/query.mjs

@@ -1,10 +1,10 @@
-import { queryCommandMeta } from "../command-meta.mjs";
-import { queryHostedRows } from "../hosted-query.mjs";
 import { useCliRuntime } from "../runtime.mjs";
 import { resolveAuthentication } from "../auth-state.mjs";
+import { queryCommandMeta } from "../command-meta.mjs";
 import { loadConfig } from "../config.mjs";
+import { queryHostedRows } from "../hosted-query.mjs";
 import { terminalOutputOptions } from "../render/terminal.mjs";
-import { ALL_SEARCH_TYPES, logger, parseSearchType, toCSV } from "../utils.mjs";
+import { ALL_SEARCH_TYPES, logger, parseSearchType, setJsonOutput, toCSV } from "../utils.mjs";
 import { allTables } from "../local-store.mjs";
 import { createCommandContext, formatSiteResolution } from "../context.mjs";
 import { decideRoute, describeStop, liveNote, readRouteState, readSiteStates, resolveReadSite, stopAtRoute } from "../route.mjs";
@@ -215,6 +215,7 @@ const queryCommand = defineCommand({
 			logger.error("Invalid --format. Use table, json, or csv.");
 			process.exit(1);
 		}
+		setJsonOutput(format === "json");
 		if (args.sql || args.schema) {
 			await runSqlMode({
 				mode: args.schema ? { kind: "schema" } : {
@@ -341,7 +342,6 @@ const queryCommand = defineCommand({
 			auth
 		});
 		const route = decideRoute(req, routeState);
-		const json = format === "json";
 		if (route.kind === "live") {
 			const live = await connect();
 			const siteUrl = site ?? await live.resolveSite(void 0);
@@ -406,7 +406,7 @@ const queryCommand = defineCommand({
 			}, null, 2));
 			return;
 		}
-		if (route.kind === "syncing" || route.kind === "prompt") stopAtRoute(route, req, routeState.auth, { json });
+		if (route.kind === "syncing" || route.kind === "prompt") stopAtRoute(route, req, routeState.auth);
 		if (dataState || aggregationType) logger.warn("--data-state / --aggregation-type are ignored without --live");
 		const siteUrl = site;
 		if (!args.quiet) logger.debug(`Querying ${siteUrl} from local Parquet store...`);
@@ -595,7 +595,7 @@ async function runSqlMode(opts) {
 			});
 			if (route.kind === "syncing" || route.kind === "prompt") {
 				views.close();
-				stopAtRoute(route, req, routeState.auth, { json: opts.format === "json" });
+				stopAtRoute(route, req, routeState.auth);
 			}
 		}
 	}

package/dist/commands/report.mjs

@@ -1,6 +1,6 @@
 import { reportCommandMeta } from "../command-meta.mjs";
 import { terminalOutputOptions } from "../render/terminal.mjs";
-import { logger, parseFetchBudget } from "../utils.mjs";
+import { logger, parseFetchBudget, setJsonOutput } from "../utils.mjs";
 import { COMPARISON_FLAGS, PERIOD_FLAGS, parseWindowFlags, windowFlagErrorToException } from "../window.mjs";
 import { analysisNeeds, analyzerSources, analyzerTables, resolveAnalysisSource } from "../analysis-local.mjs";
 import { renderCliReport } from "../render/report.mjs";
@@ -127,6 +127,7 @@ function makeReportCommand(report) {
 			...reportArgs
 		},
 		async run({ args }) {
+			setJsonOutput(Boolean(args.json));
 			const flags = windowFlags(args);
 			const params = buildReportParams(report, args);
 			const fetchBudget = parseFetchBudget(args["fetch-budget"]);
@@ -158,7 +159,6 @@ function makeReportCommand(report) {
 			const { source, siteUrl, anchor, isLive } = await resolveAnalysisSource({
 				site: args.site,
 				live: !!args.live,
-				json: !!args.json,
 				label: `report ${report.id}`,
 				types: provisional.map((step) => step.type),
 				sources: reportSources(provisional),

package/dist/commands/sitemaps.mjs

@@ -1,8 +1,8 @@
 import { sitemapsCommandMeta } from "../command-meta.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, parseIntegerOption, plural } from "../utils.mjs";
 import { createCommandContext } from "../context.mjs";
-import { discoverLiveSitemap, loadSitemapUrls } from "../sitemap.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";

package/dist/commands/sites.mjs

@@ -1,5 +1,5 @@
+import { connectSiteStep, formatHostedSync, getHostedAccount, localModeRequired, resolveAuthentication, siteManagerOf } from "../auth-state.mjs";
 import { sitesCommandMeta } from "../command-meta.mjs";
-import { LOCAL_MODE_REQUIRED, formatHostedSync, getHostedAccount, resolveAuthentication } from "../auth-state.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, plural } from "../utils.mjs";
 import { createCommandContext, formatSiteResolution } from "../context.mjs";
 import process from "node:process";
@@ -422,7 +422,7 @@ const LIST_ARGS = {
 	}
 };
 async function runListHostedSites(args, authentication) {
-	if (args["with-sitemaps"] || args["owner-only"]) throw new Error(`--with-sitemaps and --owner-only read Search Console permissions.\n${LOCAL_MODE_REQUIRED}`);
+	if (args["with-sitemaps"] || args["owner-only"]) throw localModeRequired("--with-sitemaps and --owner-only read Search Console permissions.");
 	const { sites } = await getHostedAccount(authentication);
 	if (args.json) {
 		console.log(JSON.stringify(sites.map((site) => ({
@@ -438,7 +438,7 @@ async function runListHostedSites(args, authentication) {
 		return;
 	}
 	if (sites.length === 0) {
-		logger.warn("Your hosted record has no Sites. Connect a Site at https://gscdump.com/app/onboarding?step=connect-sites.");
+		logger.warn(`Your hosted record has no Sites. ${connectSiteStep(siteManagerOf(authentication))}`);
 		return;
 	}
 	logger.success(`Found ${plural(sites.length, "hosted Site", "hosted Sites")}:`);

package/dist/config.mjs

@@ -2,8 +2,8 @@ import { useCliRuntime } from "./runtime.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { SearchTypes } from "gscdump/query";
 import os from "node:os";
+import { SearchTypes } from "gscdump/query";
 function setConfigDir(dir) {
 	useCliRuntime().configDir = dir;
 }

package/dist/context.mjs

@@ -1,6 +1,6 @@
-import { openQuotaLedger, quotaFetchOptions } from "./quota-ledger.mjs";
-import { LOCAL_MODE_REQUIRED, resolveAuthentication } from "./auth-state.mjs";
+import { localModeRequired, resolveAuthentication } from "./auth-state.mjs";
 import { loadResolvedConfig } from "./config.mjs";
+import { openQuotaLedger, quotaFetchOptions } from "./quota-ledger.mjs";
 import { resolveAuth } from "./auth.mjs";
 import { createLocalStore } from "./local-store.mjs";
 import { listStoreSites } from "./store-sites.mjs";
@@ -12,7 +12,7 @@ const FULL_SITE_URL_RE = /^(?:sc-domain:|https?:\/\/)/i;
 async function createCommandContext(opts = {}) {
 	const { needsAuth = false, needsStore = false, interactive = false, byok, quota = true } = opts;
 	const { config, dataDir } = await loadResolvedConfig();
-	if (needsAuth && (await resolveAuthentication())._tag === "Hosted") throw new Error(LOCAL_MODE_REQUIRED);
+	if (needsAuth && (await resolveAuthentication())._tag === "Hosted") throw localModeRequired();
 	const fetchOptions = needsAuth && quota ? quotaFetchOptions(await openQuotaLedger({ dataDir }), opts.fetchOptions) : opts.fetchOptions;
 	const auth = needsAuth ? await resolveAuth({
 		interactive,

package/dist/error-handler.mjs

@@ -1,13 +1,12 @@
+import { stopDetailsOf } from "./stop.mjs";
 import { isUsageError } from "./command-registry.mjs";
 import { describeRecordReadRefusal } from "./hosted-query.mjs";
 import { quotaStopOf } from "./quota-ledger.mjs";
+import { isQueryError } from "gscdump/query";
 import { isAnalysisError } from "@gscdump/analysis/errors";
 import { parseRecordReadRefusal } from "@gscdump/contracts";
 import { isEngineError } from "@gscdump/engine/errors";
 import { classifyError } from "gscdump/errors";
-import { isQueryError } from "gscdump/query";
-const HOSTED_KEY_REJECTED_REASON = "gscdump.com rejected the API key";
-const HOSTED_KEY_REJECTED = `${HOSTED_KEY_REJECTED_REASON}. Run \`gscdump auth login --mode hosted --api-key KEY\` with a valid key.`;
 const QUOTA_MESSAGE_RE = /quota|rate\s*limit/i;
 const ANSI_RE = /\x1B\[[0-9;]*m/g;
 function suggestionForGscError(error) {
@@ -109,19 +108,35 @@ function recordReadRefusalOf(error) {
 	if (!(error instanceof Error) || error.name !== "GscdumpV1Error") return null;
 	return parseRecordReadRefusal(error.details);
 }
+function recordReadStop(refusal, text) {
+	return {
+		code: refusal.reason === "record_not_ready" ? "RECORD_NOT_READY" : "RANGE_NOT_SYNCED",
+		message: text.hint ? `${text.message} ${text.hint}` : text.message,
+		nextCommand: null
+	};
+}
 function describeCliError(error) {
 	if (isUsageError(error)) return {
 		kind: "usage",
 		message: error.message
 	};
+	const stop = stopDetailsOf(error);
 	if (error instanceof Error && error.routeStop !== void 0) return {
 		kind: "stop",
-		message: error.message
+		message: error.message,
+		...stop ? { stop } : {}
 	};
 	if (error instanceof Error && quotaStopOf(error)) return {
 		kind: "stop",
 		message: error.message
 	};
+	if (error instanceof Error && stop) return {
+		kind: "expected",
+		message: error.message,
+		hint: "",
+		showAuthSources: false,
+		stop
+	};
 	if (error instanceof TypeError && error.message === "fetch failed") {
 		const cause = error.cause;
 		return {
@@ -143,18 +158,16 @@ function describeCliError(error) {
 		showAuthSources: false
 	};
 	const refusal = recordReadRefusalOf(error);
-	if (refusal) return {
-		kind: "expected",
-		...describeRecordReadRefusal(refusal),
-		showAuthSources: false
-	};
+	if (refusal) {
+		const text = describeRecordReadRefusal(refusal);
+		return {
+			kind: "expected",
+			...text,
+			showAuthSources: false,
+			stop: recordReadStop(refusal, text)
+		};
+	}
 	const classified = classifyError(error);
-	if (classified.message === HOSTED_KEY_REJECTED) return {
-		kind: "expected",
-		message: classified.message,
-		hint: "",
-		showAuthSources: false
-	};
 	return {
 		kind: "expected",
 		message: classified.message.replace(PARAM_NAME_RE, (name) => flagForParam(name)),
@@ -164,6 +177,7 @@ function describeCliError(error) {
 }
 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));
 	const red = (text) => options.color ? `\x1B[31m${text}\x1B[0m` : text;
 	const lines = [];
 	switch (report.kind) {
@@ -184,4 +198,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 { HOSTED_KEY_REJECTED, HOSTED_KEY_REJECTED_REASON, LocalStoreUnsupportedError, describeCliError, flagForParam, isAuthError, reportCliError };
+export { LocalStoreUnsupportedError, describeCliError, flagForParam, isAuthError, reportCliError };

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,56 @@ 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));
+	if (match.kind !== "found") throw stopError(siteMatchStop(match, siteManagerOf(authentication)));
 	return {
 		client: createGscdumpV1Client({
 			apiRoot: authentication.apiRoot,
 			credential: hostedCredential(authentication)
 		}),
-		site: match.site
+		site: match.site,
+		authentication
 	};
 }
-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.1.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,10 @@
+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;
+}
+export { stopDetailsOf, stopError };

package/dist/utils.mjs

@@ -2,8 +2,8 @@ import { useCliRuntime } from "./runtime.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 +40,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
@@ -148,10 +152,7 @@ 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 +197,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.1.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.1.0",
+    "@gscdump/contracts": "^5.1.0",
+    "@gscdump/engine": "^5.1.0",
+    "@gscdump/engine-gsc-api": "^5.1.0",
+    "@gscdump/sdk": "^5.1.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.1.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. A [stop](#stops) with JSON output also prints `{ "error" }` on stdout.
 Example: `gscdump query --site=SITE --start=DATE --end=DATE -d page -f json`.
 
 ## Start each task
@@ -43,6 +43,9 @@ 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. 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.
 
 `--mode local|hosted` overrides one invocation. `GSCDUMP_AUTH_MODE` also overrides the saved mode.
 A successful login saves the mode per profile.
@@ -128,8 +131,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 routing stop 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 +155,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 +223,35 @@ 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, stdout gets `{ "error": { "code", "message", "nextCommand" } }`.
+A command writes JSON with `--json`, with `--format json`, and for `query` with its default format.
+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 |
+| --- | --- |
+| `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 |
+| `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 |
+
 ## Commands
 
 | Command | Use it for |