@gscdump/cli 3.8.0 → 4.0.1

package/dist/auth.mjs

@@ -1,3 +1,4 @@
+import { resolveAuthentication } from "./auth-state.mjs";
 import { getConfigDir, loadConfig } from "./config.mjs";
 import { pickCliEnvironmentValue, resolveCliEnvironment } from "./environment.mjs";
 import { getAppliedEnvKeys, getLoadedEnvPath } from "./env-file.mjs";
@@ -8,12 +9,12 @@ import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { Buffer } from "node:buffer";
-import { err, ok, unwrapResult } from "gscdump/result";
-import { text } from "@clack/prompts";
-import { createAuth } from "gscdump/client";
 import { createServer } from "node:http";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { text } from "@clack/prompts";
 import { CodeChallengeMethod, JWT, OAuth2Client } from "google-auth-library";
+import { createAuth } from "gscdump/client";
+import { err, ok, unwrapResult } from "gscdump/result";
 import open from "open";
 function authErrorToException(error) {
 	const exception = new Error(error.message);
@@ -66,6 +67,12 @@ function resolveBYOK(opts = {}) {
 function getTokensPath() {
 	return path.join(getConfigDir(), "tokens.json");
 }
+const GOOGLE_NOT_CONNECTED = [
+	"Google is not connected. Use one of these:",
+	"  Local:  gscdump auth login",
+	"  Hosted: gscdump auth login --mode cloud --api-key KEY (a gscdump.com API key)",
+	"  BYOK:   set GSC_ACCESS_TOKEN, or GSC_CLIENT_ID, GSC_CLIENT_SECRET and GSC_REFRESH_TOKEN"
+].join("\n");
 async function loadTokens() {
 	return fs.readFile(getTokensPath(), "utf-8").then((data) => JSON.parse(data)).catch(() => null);
 }
@@ -291,14 +298,8 @@ async function authenticate(credentials, interactive, opts = {}) {
 		}
 	}
 	if (!interactive) {
-		if (refreshFailed) {
-			logger.error(`Token refresh failed${refreshError ? `: ${refreshError.message}` : ""}`);
-			logger.info("Refresh token may be revoked or expired. Run `gscdump auth login` to re-authenticate.");
-		} else {
-			logger.error("Not authenticated");
-			logger.info("Run `gscdump auth login` (or `gscdump init` for full setup).");
-		}
-		process.exit(1);
+		if (refreshFailed) throw new Error(`Token refresh failed${refreshError ? `: ${refreshError.message}` : ""}. The refresh token may be revoked or expired. Run \`gscdump auth login\` to sign in again.`);
+		throw new Error(GOOGLE_NOT_CONNECTED);
 	}
 	const state = randomBytes(32).toString("base64url");
 	const codeVerifier = randomBytes(32).toString("base64url");
@@ -332,7 +333,7 @@ async function getAuth(opts = {}) {
 	});
 	let tokens = force ? null : await loadTokens();
 	if (tokens?.provider !== "gscdump" || !tokens.refresh_token) {
-		if (!interactive) throw new Error("Run `gscdump auth login` to connect Google.");
+		if (!interactive) throw new Error(GOOGLE_NOT_CONNECTED);
 		tokens = await loginWithPlatform({
 			force,
 			request: fetch,
@@ -363,8 +364,15 @@ async function getAuth(opts = {}) {
 	await client.getAccessToken();
 	return client;
 }
+function isStaleServiceAccountPointer(error) {
+	if (error instanceof SyntaxError) return true;
+	return error?.code === "ENOENT";
+}
 async function resolveAuth(opts = {}) {
-	const sa = await resolveServiceAccount({ path: opts.serviceAccount });
+	const sa = await resolveServiceAccount({ path: opts.serviceAccount }).catch((error) => {
+		if (isStaleServiceAccountPointer(error)) return null;
+		throw error;
+	});
 	if (sa) {
 		logger.success("Using service-account credentials");
 		return sa;
@@ -492,9 +500,10 @@ async function formatAuthProvenance() {
 	}
 	return lines.join("\n");
 }
-function isAuthError(err) {
-	const msg = (err instanceof Error ? err.message : String(err ?? "")).toLowerCase();
-	if (!msg) return false;
-	return /\b(?:401|403|unauthorized|forbidden|invalid_grant|invalid_token|insufficient.*scope|invalid_client|token has been expired|token has been revoked)\b/.test(msg) || msg.includes("oauth2.googleapis.com/token");
+async function probeAuth() {
+	if ((await resolveAuthentication())._tag === "Cloud") return "hosted";
+	if (resolveBYOK()) return "google";
+	if (await resolveServiceAccount().then(Boolean, (error) => !isStaleServiceAccountPointer(error))) return "google";
+	return await loadTokens() !== null ? "google" : "none";
 }
-export { authenticate, clearTokens, describeAuthProvenance, formatAuthProvenance, getAuth, getAuthCredentials, isAuthError, loadServiceAccount, loadServiceAccountResult, loadTokens, resolveAuth, resolveBYOK, resolveServiceAccount, saveTokens };
+export { GOOGLE_NOT_CONNECTED, authenticate, clearTokens, describeAuthProvenance, formatAuthProvenance, getAuth, getAuthCredentials, loadServiceAccount, loadServiceAccountResult, loadTokens, probeAuth, resolveAuth, resolveBYOK, resolveServiceAccount, saveTokens };

package/dist/bing-data.mjs

@@ -22,13 +22,17 @@ const dumpSchema = z.object({
 	end: dateSchema.optional()
 }).refine((value) => !value.start || !value.end || value.start <= value.end, { message: "--start must precede --end" });
 function parseBingDumpOptions(args) {
+	const defaults = args.start || args.end ? datedDatasets : [...BING_DATASETS];
 	const parsed = dumpSchema.safeParse({
 		...args,
-		datasets: args.datasets ? [...new Set(args.datasets.split(",").map((value) => value.trim()))] : datedDatasets
+		datasets: args.datasets ? [...new Set(args.datasets.split(",").map((value) => value.trim()))] : defaults
 	});
 	if (!parsed.success) throw new Error(`Invalid Bing dump options: ${parsed.error.issues.map((issue) => issue.message).join("; ")}.`);
 	if (parsed.data.datasets.includes("crawl-issues") && (parsed.data.start || parsed.data.end)) throw new Error("Bing crawl issues have no dates. Export them without --start or --end.");
-	return parsed.data;
+	return {
+		...parsed.data,
+		datasetsExplicit: Boolean(args.datasets)
+	};
 }
 function unwrapBing(result) {
 	if (result.ok) return result.value;

package/dist/bing-hosted.mjs

@@ -42,7 +42,7 @@ async function resolveHostedBingSites(state, input) {
 	return selected;
 }
 async function dumpHostedBingSite(state, site, outDir, options) {
-	if (options.datasets.includes("crawl-issues")) throw new Error("Bing crawl issues require local authentication. Use --mode local.");
+	if (options.datasetsExplicit && options.datasets.includes("crawl-issues")) throw new Error("Bing crawl issues require local authentication. Use --mode local.");
 	const endDate = options.end ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 	const startDate = options.start ?? (/* @__PURE__ */ new Date(Date.parse(endDate) - 316224e5)).toISOString().slice(0, 10);
 	if (Date.parse(endDate) - Date.parse(startDate) > 316224e5) throw new Error("Hosted Bing exports support at most 366 days. Use a shorter --start and --end range.");

package/dist/cli-args.mjs

@@ -2,6 +2,12 @@ import { parseArgs } from "node:util";
 async function resolve(value) {
 	return typeof value === "function" ? value() : value;
 }
+const GLOBAL_OPTIONS = /* @__PURE__ */ new Set([
+	"help",
+	"h",
+	"version",
+	"no-color"
+]);
 async function checkCliArgs(command, rawArgs, path = "gscdump") {
 	const definitions = await resolve(command.args ?? {});
 	const options = {
@@ -56,6 +62,8 @@ async function checkCliArgs(command, rawArgs, path = "gscdump") {
 			}
 		}
 		if (!selected) return `Unknown command ${positional.value}. Run ${path} --help.`;
+		const early = tokens.find((token) => token.index < boundary && token.kind === "option" && !GLOBAL_OPTIONS.has(token.name));
+		if (early?.kind === "option") return `Put ${early.rawName} after the subcommand: ${path} ${positional.value} ${early.rawName}.`;
 		const child = await resolve(selected);
 		if (child) return checkCliArgs(child, rawArgs.slice(boundary + 1), `${path} ${positional.value}`);
 	}

package/dist/cli.d.mts

@@ -6,5 +6,9 @@ export interface RunCliOptions {
   environment?: Record<string, string | undefined>;
   runtime?: CliRuntime;
 }
-export declare function runCli(opts?: RunCliOptions): Promise<void>;
+/**
+ * Run one CLI invocation. Every failure ends here: the shell prints it once
+ * and returns exit code 1. The caller owns `process.exit`.
+ */
+export declare function runCli(opts?: RunCliOptions): Promise<number>;
 export { type CliRuntime, type CreateCliRuntimeOptions, createCliRuntime };

package/dist/cli.mjs

@@ -1,14 +1,15 @@
+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 } from "./command-registry.mjs";
 import { resolveCliEnvironment } from "./environment.mjs";
 import { applyProfileFromCli } from "./commands/profile-selection.mjs";
 import { loadEnvFromCwd } from "./env-file.mjs";
-import { terminalOutputOptions } from "./render/terminal.mjs";
+import { resolveOutputOptions, terminalOutputOptions } from "./render/terminal.mjs";
 import { VERSION, setNoColor, showSplash, withConfiguredOutput } from "./utils.mjs";
 import process from "node:process";
-import { defineCommand, runMain } from "citty";
+import { defineCommand, renderUsage, runCommand } from "citty";
 function shouldShowSplash(rawArgs) {
 	if (!process.stdout.isTTY) return false;
 	if (rawArgs[0] !== "init" && rawArgs[0] !== "auth") return false;
@@ -68,6 +69,25 @@ const main = defineCommand({
 		if (shouldShowSplash(rawArgs)) showSplash();
 	}
 });
+const HELP_FLAGS = /* @__PURE__ */ new Set(["--help", "-h"]);
+async function runMainCommand(rawArgs) {
+	if (rawArgs.some((arg) => HELP_FLAGS.has(arg))) {
+		console.log(`${await renderUsage(...await resolveUsageTarget(main, rawArgs))}\n`);
+		return;
+	}
+	if (rawArgs.length === 1 && rawArgs[0] === "--version") {
+		console.log(VERSION);
+		return;
+	}
+	await runCommand(main, { rawArgs });
+}
+function stderrColor(runtime, rawArgs) {
+	return resolveOutputOptions({
+		isTTY: process.stderr.isTTY,
+		environment: runtime.environment,
+		noColor: rawArgs.includes("--no-color")
+	}).color;
+}
 async function runCli(opts = {}) {
 	const input = opts.rawArgs ?? process.argv.slice(2);
 	const runtime = opts.runtime ?? createCliRuntime({
@@ -75,13 +95,24 @@ async function runCli(opts = {}) {
 		rawArgs: input
 	});
 	runtime.rawArgs = [...input];
-	await runWithCliRuntime(runtime, async () => {
-		if (opts.loadEnv !== false) loadEnvFromCwd();
-		const rawArgs = prepareCliArgs(input);
-		runtime.rawArgs = [...rawArgs];
-		const argumentError = await checkCliArgs(main, rawArgs);
-		if (argumentError) throw new Error(argumentError);
-		await withConfiguredOutput(() => runMain(main, { rawArgs }));
+	return runWithCliRuntime(runtime, async () => {
+		let rawArgs = [...input];
+		try {
+			if (opts.loadEnv !== false) loadEnvFromCwd();
+			rawArgs = prepareCliArgs(input);
+			runtime.rawArgs = [...rawArgs];
+			const argumentError = await checkCliArgs(main, rawArgs);
+			if (argumentError) throw new Error(argumentError);
+			await withConfiguredOutput(() => runMainCommand(rawArgs));
+			return 0;
+		} catch (error) {
+			await reportCliError(error, {
+				color: stderrColor(runtime, rawArgs),
+				usage: async () => renderUsage(...await resolveUsageTarget(main, rawArgs)),
+				authSources: async () => (await import("./auth.mjs")).formatAuthProvenance()
+			});
+			return 1;
+		}
 	});
 }
 export { createCliRuntime, main, runCli };

package/dist/cloud-google.mjs

@@ -1,3 +1,4 @@
+import { HOSTED_KEY_REJECTED } from "./error-handler.mjs";
 import { cloudRequest } from "./auth-state.mjs";
 import { googleSearchConsole } from "gscdump/client";
 import { ofetch } from "ofetch";
@@ -65,7 +66,13 @@ function createCloudGoogleClient(state, fetchOptions) {
 		return result === void 0 ? new Response(null, { status: 204 }) : Response.json(result);
 	};
 	const fetchHosted = (input, init) => request(input, init).catch((error) => {
-		if (error && typeof error === "object" && "response" in error && error.response instanceof Response) return error.response;
+		if (error && typeof error === "object" && "response" in error && error.response instanceof Response) {
+			if (error.response.status === 401) return Response.json({ error: {
+				code: 401,
+				message: HOSTED_KEY_REJECTED
+			} }, { status: 401 });
+			return error.response;
+		}
 		throw error;
 	});
 	return googleSearchConsole("", { fetch: ofetch.create({

package/dist/command-meta.mjs

@@ -4,7 +4,7 @@ const initCommandMeta = {
 };
 const dumpCommandMeta = {
 	name: "dump",
-	description: "Export live Parquet files from the local store to a directory"
+	description: "Export the local Store, inspections, sitemaps, and Bing data to a directory"
 };
 const queryCommandMeta = {
 	name: "query",
@@ -20,7 +20,7 @@ const sitemapsCommandMeta = {
 };
 const syncCommandMeta = {
 	name: "sync",
-	description: "Sync GSC data to local Parquet store"
+	description: "Sync GSC data, sitemaps, and URL Inspection results to the local Store"
 };
 const storeCommandMeta = {
 	name: "store",
@@ -28,11 +28,11 @@ const storeCommandMeta = {
 };
 const inspectCommandMeta = {
 	name: "inspect",
-	description: "Inspect URL indexing status (single URL; use `inspect batch` for many)"
+	description: "Inspect the indexing status of one or more URLs and save the results to the Store"
 };
 const indexingCommandMeta = {
 	name: "indexing",
-	description: "Notify Google about URL updates/removals (Indexing API)"
+	description: "Notify Google about URL changes (Indexing API); list hosted URL Inspection results"
 };
 const entitiesCommandMeta = {
 	name: "entities",

package/dist/command-registry.mjs

@@ -2,12 +2,74 @@ import { analyzeCommandMeta, authCommandMeta, bingCommandMeta, configCommandMeta
 function resolveValue(value) {
 	return typeof value === "function" ? value() : value;
 }
+const KEBAB_RE = /-([a-z])/g;
+function camelCase(name) {
+	return name.replace(KEBAB_RE, (_, letter) => letter.toUpperCase());
+}
+function isValueFlag(flag, argsDef) {
+	const name = flag.replace(/^-{1,2}/, "");
+	for (const [key, def] of Object.entries(argsDef)) {
+		if (def.type !== "string" && def.type !== "enum") continue;
+		const aliases = "alias" in def && def.alias ? [def.alias].flat() : [];
+		if (camelCase(name) === camelCase(key) || aliases.includes(name)) return true;
+	}
+	return false;
+}
+function findSubCommandIndex(rawArgs, argsDef) {
+	for (let i = 0; i < rawArgs.length; i++) {
+		const arg = rawArgs[i];
+		if (arg === "--") return -1;
+		if (arg.startsWith("-")) {
+			if (!arg.includes("=") && isValueFlag(arg, argsDef)) i++;
+			continue;
+		}
+		return i;
+	}
+	return -1;
+}
+function usageError(message, code) {
+	return Object.assign(new Error(message), {
+		name: "CLIError",
+		code
+	});
+}
+function isUsageError(error) {
+	return error instanceof Error && error.name === "CLIError";
+}
+function guardedRun(load) {
+	return async (context) => {
+		const command = await load();
+		const subCommands = await resolveValue(command.subCommands) ?? {};
+		if (Object.keys(subCommands).length > 0) {
+			const argsDef = await resolveValue(command.args) ?? {};
+			if (findSubCommandIndex(context.rawArgs, argsDef) >= 0) return;
+			if (!command.run) throw usageError("No command specified.", "E_NO_COMMAND");
+		}
+		return command.run?.({
+			...context,
+			cmd: command
+		});
+	};
+}
+function guardedSubCommands(load) {
+	return async () => {
+		const subCommands = await resolveValue((await load()).subCommands) ?? {};
+		return Object.fromEntries(Object.entries(subCommands).map(([name, sub]) => [name, async () => guardCommand(await resolveValue(sub))]));
+	};
+}
+function guardCommand(command) {
+	const load = async () => command;
+	return {
+		...command,
+		subCommands: guardedSubCommands(load),
+		run: guardedRun(load)
+	};
+}
 function shallowCommand(meta, load) {
 	return {
 		meta,
 		args: async () => await resolveValue((await load()).args) ?? {},
-		default: async () => await resolveValue((await load()).default) ?? "",
-		subCommands: async () => await resolveValue((await load()).subCommands) ?? {},
+		subCommands: guardedSubCommands(load),
 		async setup(context) {
 			const command = await load();
 			await command.setup?.({
@@ -22,15 +84,29 @@ function shallowCommand(meta, load) {
 				cmd: command
 			});
 		},
-		async run(context) {
-			const command = await load();
-			return command.run?.({
-				...context,
-				cmd: command
-			});
-		}
+		run: guardedRun(load)
 	};
 }
+async function resolveUsageTarget(command, rawArgs, parent) {
+	const subCommands = await resolveValue(command.subCommands) ?? {};
+	if (Object.keys(subCommands).length > 0) {
+		const index = findSubCommandIndex(rawArgs, await resolveValue(command.args) ?? {});
+		const name = rawArgs[index];
+		if (name !== void 0) {
+			const selected = await findSubCommand(subCommands, name);
+			if (selected) return resolveUsageTarget(selected, rawArgs.slice(index + 1), command);
+		}
+	}
+	return [command, parent];
+}
+async function findSubCommand(subCommands, name) {
+	if (name in subCommands) return await resolveValue(subCommands[name]);
+	for (const candidate of Object.values(subCommands)) {
+		const resolved = await resolveValue(candidate);
+		const meta = await resolveValue(resolved?.meta);
+		if (meta?.alias && [meta.alias].flat().includes(name)) return resolved;
+	}
+}
 const CLI_SUBCOMMANDS = {
 	bing: shallowCommand(bingCommandMeta, () => import("./commands/bing.mjs").then((module) => module.bingCommand)),
 	init: shallowCommand(initCommandMeta, () => import("./commands/init.mjs").then((module) => module.initCommand)),
@@ -56,4 +132,4 @@ const CLI_SUBCOMMANDS = {
 	skill: shallowCommand(skillCommandMeta, () => import("./commands/skill.mjs").then((module) => module.skillCommand)),
 	papercut: shallowCommand(papercutCommandMeta, () => import("./commands/papercut.mjs").then((module) => module.papercutCommand))
 };
-export { CLI_SUBCOMMANDS };
+export { CLI_SUBCOMMANDS, findSubCommandIndex, isUsageError, resolveUsageTarget, usageError };

package/dist/commands/analyze.mjs

@@ -1,38 +1,39 @@
 import { analyzeCommandMeta } from "../command-meta.mjs";
 import { terminalOutputOptions } from "../render/terminal.mjs";
-import { logger, parseIntegerOption, toCSV } from "../utils.mjs";
-import { gscErrorHandler } from "../error-handler.mjs";
-import { resolveAnalysisSource } from "../analysis-local.mjs";
-import { renderAnalysis } from "../render/analysis.mjs";
+import { logger, parseFetchBudget, parseIntegerOption, 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";
 import { defineCommand } from "citty";
+import { DEFAULT_FETCH_BUDGET, MAX_FETCH_BUDGET } from "@gscdump/engine/analysis-types";
+import { unwrapResult } from "gscdump/result";
+import { MOVERS_SORT_METRICS } from "@gscdump/analysis";
 import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
-import { periodOf } from "@gscdump/engine/period";
 const ANALYSIS_TOOLS = defaultAnalyzerRegistry.listAnalyzerIds();
+const COMPARISON_ARGS = {
+	"prev-start": {
+		type: "string",
+		description: "Previous period start date (default: the period before the window)"
+	},
+	"prev-end": {
+		type: "string",
+		description: "Previous period end date (pass with --prev-start)"
+	}
+};
+const COMPARISON_TOOLS = /* @__PURE__ */ new Set(["movers", "decay"]);
 const TOOL_EXTRA_ARGS = {
 	brand: { "brand-terms": {
 		type: "string",
 		description: "Comma-separated brand terms (required)"
 	} },
 	movers: {
-		"prev-start": {
+		...COMPARISON_ARGS,
+		"sort-by": {
 			type: "string",
-			description: "Previous period start date (required)"
-		},
-		"prev-end": {
-			type: "string",
-			description: "Previous period end date (required)"
-		}
-	},
-	decay: {
-		"prev-start": {
-			type: "string",
-			description: "Previous period start date (required)"
-		},
-		"prev-end": {
-			type: "string",
-			description: "Previous period end date (required)"
+			description: `Sort: ${MOVERS_SORT_METRICS.join(", ")} (default: clicksDelta)`
 		}
 	},
+	decay: COMPARISON_ARGS,
 	concentration: { dimension: {
 		type: "string",
 		description: "Dimension: pages or keywords (default: pages)"
@@ -63,22 +64,47 @@ const TOOL_EXTRA_ARGS = {
 function buildParams(tool, args) {
 	const params = {
 		type: tool,
-		startDate: args.start ? String(args.start) : void 0,
-		endDate: args.end ? String(args.end) : void 0,
 		limit: parseIntegerOption(args.limit, "--limit")
 	};
+	const fetchBudget = parseFetchBudget(args["fetch-budget"]);
+	if (fetchBudget !== void 0) params.fetchBudget = fetchBudget;
 	if (args["brand-terms"]) params.brandTerms = String(args["brand-terms"]).split(",").map((t) => t.trim()).filter(Boolean);
-	if (args["prev-start"]) params.prevStartDate = String(args["prev-start"]);
-	if (args["prev-end"]) params.prevEndDate = String(args["prev-end"]);
 	if (args.dimension) params.dimension = String(args.dimension);
 	if (args.metric) params.metric = String(args.metric);
 	if (args["cluster-by"]) params.clusterBy = String(args["cluster-by"]);
+	if (args["sort-by"]) {
+		const sortBy = String(args["sort-by"]);
+		if (!MOVERS_SORT_METRICS.includes(sortBy)) throw new Error(`Invalid --sort-by "${sortBy}". Use one of: ${MOVERS_SORT_METRICS.join(", ")}.`);
+		params.sortBy = sortBy;
+	}
 	const weeks = parseIntegerOption(args.weeks, "--weeks");
 	const minWeeks = parseIntegerOption(args["min-weeks"], "--min-weeks");
 	if (weeks !== void 0) params.weeks = weeks;
 	if (minWeeks !== void 0) params.minWeeksWithData = minWeeks;
 	return params;
 }
+function withWindow(tool, params, args, anchor) {
+	const optional = (key) => args[key] ? String(args[key]) : void 0;
+	const window = unwrapResult(parseWindowFlags({
+		period: optional("period"),
+		start: optional("start"),
+		end: optional("end"),
+		prevStart: optional("prev-start"),
+		prevEnd: optional("prev-end")
+	}, {
+		...DEFAULT_WINDOW,
+		comparison: COMPARISON_TOOLS.has(tool) ? "prev-period" : "none"
+	}, anchor), windowFlagErrorToException);
+	return {
+		...params,
+		startDate: window.start,
+		endDate: window.end,
+		...window.comparison ? {
+			prevStartDate: window.comparison.start,
+			prevEndDate: window.comparison.end
+		} : {}
+	};
+}
 function makeToolCommand(tool) {
 	const extraArgs = TOOL_EXTRA_ARGS[tool] || {};
 	return defineCommand({
@@ -87,37 +113,45 @@ function makeToolCommand(tool) {
 			description: `Run ${tool} analysis`
 		},
 		args: {
-			site: {
+			"site": {
 				type: "string",
 				alias: "s",
 				description: "Site URL"
 			},
-			start: {
+			"period": {
 				type: "string",
-				description: "Start date (YYYY-MM-DD)"
+				description: `Window: ${PERIOD_FLAGS.join("|")} (default: 28d, ending on the newest synced day)`
 			},
-			end: {
+			"start": {
 				type: "string",
-				description: "End date (YYYY-MM-DD)"
+				description: "Start date (YYYY-MM-DD). Implies --period custom"
 			},
-			limit: {
+			"end": {
+				type: "string",
+				description: "End date (YYYY-MM-DD). Implies --period custom"
+			},
+			"limit": {
 				type: "string",
 				alias: "l",
 				default: "100",
-				description: "Max results"
+				description: "Max results to return"
+			},
+			"fetch-budget": {
+				type: "string",
+				description: `Max rows each live fetch reads (default: ${DEFAULT_FETCH_BUDGET}, max: ${MAX_FETCH_BUDGET})`
 			},
-			format: {
+			"format": {
 				type: "string",
 				alias: "f",
 				default: "table",
 				description: "Output: table, json, csv"
 			},
-			json: {
+			"json": {
 				type: "boolean",
 				default: false,
 				description: "Output as JSON"
 			},
-			live: {
+			"live": {
 				type: "boolean",
 				default: false,
 				description: "Force live GSC API; bypass local Parquet store"
@@ -130,29 +164,36 @@ function makeToolCommand(tool) {
 				"json",
 				"csv"
 			].includes(args.format ?? "table")) throw new Error("Invalid --format. Use table, json, or csv.");
-			const params = buildParams(tool, args);
-			const { format, runAnalysis, siteUrl } = await resolveAnalysisSource({
+			const baseParams = buildParams(tool, args);
+			const format = args.json ? "json" : String(args.format ?? "table");
+			const { runAnalysis, siteUrl, anchor } = await resolveAnalysisSource({
 				site: args.site,
 				live: !!args.live,
-				json: !!args.json,
-				format: args.format
+				json: format === "json",
+				label: `analyze ${tool}`,
+				types: [tool],
+				anchorTables: analyzerTables(baseParams),
+				needs: (anchor) => analysisNeeds(withWindow(tool, baseParams, args, anchor))
 			});
+			const params = withWindow(tool, baseParams, args, anchor);
 			logger.debug(`Running ${tool} analysis...`);
-			const result = await runAnalysis(params).catch(gscErrorHandler);
+			const result = await runAnalysis(params);
+			const warning = coverageWarning(result.meta.coverage);
 			if (format === "json") {
 				console.log(JSON.stringify(result, null, 2));
+				if (warning) logger.warn(warning);
 				return;
 			}
 			if (format === "csv") {
 				console.log(toCSV(result.results, Object.keys(result.results[0] ?? {})));
+				if (warning) logger.warn(warning);
 				return;
 			}
-			const period = periodOf(params);
 			console.log(renderAnalysis(result, {
 				id: tool,
 				site: siteUrl,
-				start: period.startDate,
-				end: period.endDate,
+				start: params.startDate,
+				end: params.endDate,
 				...params.prevStartDate && params.prevEndDate ? { previous: {
 					start: params.prevStartDate,
 					end: params.prevEndDate