@gscdump/cli 3.6.2 → 3.7.0

package/README.md

@@ -20,7 +20,7 @@ npx @gscdump/cli
 ## Quick start
 
 ```bash
-# Set up local Google OAuth
+# Connect Google for free local CLI use
 gscdump init --mode local
 gscdump auth login --mode local
 
@@ -280,16 +280,22 @@ This section covers local Google credentials. See [shared authentication](#hoste
 Credentials are saved under `~/.config/gscdump/` on XDG systems, or the platform equivalent.
 Use `gscdump auth login --mode local` to connect Google and save local mode.
 
-Local Google browser login uses a temporary listener on `127.0.0.1` with a random port.
+If you configure your own Google OAuth client, browser login uses a temporary listener on `127.0.0.1` with a random port.
 Each attempt uses state validation and PKCE S256 to bind the authorization response to that attempt.
 The listener closes after authorization, denial, or a five-minute timeout.
 
-For manual setup:
+By default, login opens gscdump.com. No Google Cloud project is required.
+The platform handles Google login and token refresh. Data queries call Google directly.
+This grants read-only Search Console access. It does not activate hosted sync, storage, or hosted MCP.
+Hosted Pro is free during beta and will require payment after launch.
+For Google write operations, configure your own OAuth client with the required scopes.
+
+For your own OAuth client:
 
 1. Create a Google Cloud project.
 2. Enable **Search Console API**, **Web Search Indexing API**, and **Site Verification API**.
 3. Create OAuth2 credentials (Desktop app).
-4. Run `gscdump init --mode local` to configure credentials and a Store directory.
+4. Set `GSC_CLIENT_ID` and `GSC_CLIENT_SECRET` for your Desktop app.
 5. Run `gscdump auth login --mode local` to save local mode.
 
 ### BYOK (Bring Your Own Key)
@@ -328,8 +334,9 @@ gscdump auth login --mode local --no-browser
 # Open the printed URL in your browser.
 ```
 
-This uses the same Desktop application OAuth client and loopback flow as browser login.
-Google's device flow does not support the required scopes.
+Default login works from a remote terminal without port forwarding. Keep the command running until you approve the browser request.
+
+With your own OAuth client, login uses the Desktop application loopback flow.
 
 If the CLI runs on another host, forward its printed loopback port before opening the URL.
 Keep the login command running on that host.

package/dist/auth-scopes.mjs

@@ -1,9 +1,9 @@
-import { GSC_INDEXING_SCOPE, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, hasGoogleScope } from "gscdump/client";
-function missingRequiredScopes(scopes) {
-	return [
+import { GSC_INDEXING_SCOPE, GSC_READ_SCOPE, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, hasGoogleScope } from "gscdump/client";
+function missingRequiredScopes(scopes, provider) {
+	return (provider === "gscdump" ? [GSC_READ_SCOPE] : [
 		GSC_WRITE_SCOPE,
 		GSC_INDEXING_SCOPE,
 		GSC_SITE_VERIFICATION_SCOPE
-	].filter((scope) => !hasGoogleScope(scopes, scope));
+	]).filter((scope) => !hasGoogleScope(scopes, scope));
 }
 export { missingRequiredScopes };

package/dist/auth.mjs

@@ -2,6 +2,7 @@ import { getConfigDir, loadConfig } from "./config.mjs";
 import { pickCliEnvironmentValue, resolveCliEnvironment } from "./environment.mjs";
 import { getAppliedEnvKeys, getLoadedEnvPath } from "./env-file.mjs";
 import { displayPath, logger } from "./utils.mjs";
+import { loginWithPlatform, refreshWithPlatform } from "./hosted-auth.mjs";
 import process from "node:process";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import fs from "node:fs/promises";
@@ -11,6 +12,7 @@ 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 { CodeChallengeMethod, JWT, OAuth2Client } from "google-auth-library";
 import open from "open";
 function authErrorToException(error) {
@@ -261,7 +263,8 @@ async function authenticate(credentials, interactive, opts = {}) {
 		}
 		return oauth2Client;
 	}
-	const existingTokens = !opts.force ? await loadTokens() : null;
+	const savedTokens = !opts.force ? await loadTokens() : null;
+	const existingTokens = savedTokens?.provider === "gscdump" ? null : savedTokens;
 	let refreshFailed = false;
 	let refreshError = null;
 	if (existingTokens) {
@@ -321,10 +324,44 @@ async function authenticate(credentials, interactive, opts = {}) {
 }
 async function getAuth(opts = {}) {
 	const { interactive = true, noBrowser = false, force = false } = opts;
-	return authenticate(await getAuthCredentials(interactive), interactive, {
+	const env = resolveCliEnvironment();
+	const config = opts.config ?? await loadConfig();
+	if (env.clientId && env.clientSecret || config.clientId && config.clientSecret) return authenticate(await getAuthCredentials(interactive), interactive, {
 		noBrowser,
 		force
 	});
+	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.");
+		tokens = await loginWithPlatform({
+			force,
+			request: fetch,
+			now: Date.now,
+			wait: setTimeout$1,
+			authorize: async (url) => {
+				logger.info(`Open this URL to connect Google:\n${url}`);
+				if (!noBrowser) await open(url).catch((error) => logger.warn(`Browser could not open: ${error.message}. Open the URL above.`));
+			}
+		});
+		await saveTokens(tokens);
+	}
+	const refreshToken = tokens.refresh_token;
+	const client = new OAuth2Client();
+	client.refreshHandler = async () => {
+		const refreshed = await refreshWithPlatform(refreshToken);
+		await saveTokens({
+			provider: "gscdump",
+			refresh_token: refreshToken,
+			...refreshed
+		});
+		return refreshed;
+	};
+	client.setCredentials({
+		access_token: tokens.access_token,
+		expiry_date: tokens.expiry_date
+	});
+	await client.getAccessToken();
+	return client;
 }
 async function resolveAuth(opts = {}) {
 	const sa = await resolveServiceAccount({ path: opts.serviceAccount });

package/dist/cli-args.mjs

@@ -0,0 +1,63 @@
+import { parseArgs } from "node:util";
+async function resolve(value) {
+	return typeof value === "function" ? value() : value;
+}
+async function checkCliArgs(command, rawArgs, path = "gscdump") {
+	const definitions = await resolve(command.args ?? {});
+	const options = {
+		"help": { type: "boolean" },
+		"h": { type: "boolean" },
+		"version": { type: "boolean" },
+		"no-color": { type: "boolean" }
+	};
+	for (const [name, definition] of Object.entries(definitions)) {
+		if (definition.type === "positional") continue;
+		const type = definition.type === "boolean" ? "boolean" : "string";
+		const alias = "alias" in definition ? definition.alias : void 0;
+		const names = [
+			name,
+			...typeof alias === "string" ? [alias] : alias ?? [],
+			name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()),
+			name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+		];
+		for (const key of names) {
+			options[key] = { type };
+			if (type === "boolean" && !key.startsWith("no-")) options[`no-${key}`] = { type };
+		}
+	}
+	const { tokens } = parseArgs({
+		args: rawArgs,
+		options,
+		strict: false,
+		allowPositionals: true,
+		tokens: true
+	});
+	const subCommands = await resolve(command.subCommands ?? {});
+	const positional = tokens.find((token) => token.kind === "positional");
+	const hasSubCommands = Object.keys(subCommands).length > 0;
+	const boundary = hasSubCommands && positional ? positional.index : rawArgs.length;
+	for (const token of tokens) {
+		if (token.index >= boundary || token.kind !== "option") continue;
+		const option = options[token.name];
+		if (!option) {
+			const matches = Object.keys(definitions).filter((name) => definitions[name]?.type !== "positional" && name.startsWith(token.name) && name.length - token.name.length <= 2);
+			const suggestion = matches.length === 1 ? ` Use --${matches[0]}.` : "";
+			return `Unknown option ${token.rawName}.${suggestion} Run ${path} --help.`;
+		}
+		if (option.type === "string" && (token.value === void 0 || !token.inlineValue && token.value.startsWith("-"))) return `${token.rawName} requires a value. Use ${token.rawName}=VALUE.`;
+	}
+	if (hasSubCommands && positional?.kind === "positional") {
+		let selected = subCommands[positional.value];
+		if (!selected) for (const candidate of Object.values(subCommands)) {
+			const meta = await resolve((await resolve(candidate))?.meta ?? {});
+			if ((typeof meta.alias === "string" ? [meta.alias] : meta.alias ?? []).includes(positional.value)) {
+				selected = candidate;
+				break;
+			}
+		}
+		if (!selected) return `Unknown command ${positional.value}. Run ${path} --help.`;
+		const child = await resolve(selected);
+		if (child) return checkCliArgs(child, rawArgs.slice(boundary + 1), `${path} ${positional.value}`);
+	}
+}
+export { checkCliArgs };

package/dist/cli.mjs

@@ -1,5 +1,6 @@
 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";
@@ -78,6 +79,8 @@ async function runCli(opts = {}) {
 		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 }));
 	});
 }

package/dist/commands/auth.mjs

@@ -3,7 +3,7 @@ import { clearAuthentication, getCloudAccount, parseAuthMode, parseAuthenticatio
 import { authCommandMeta } from "../command-meta.mjs";
 import { loadConfig, saveConfig } from "../config.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, noSubcommandSelected } from "../utils.mjs";
-import { authenticate, clearTokens, formatAuthProvenance, getAuth, getAuthCredentials, loadServiceAccount, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
+import { clearTokens, formatAuthProvenance, getAuth, loadServiceAccount, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
 import { missingRequiredScopes } from "../auth-scopes.mjs";
 import { clearBingCredentials, getBingClient, inspectBingCredentials } from "../bing-auth.mjs";
 import { runSmokeTest } from "./init.mjs";
@@ -64,7 +64,7 @@ async function resolveLiveAuthState() {
 	else if (tokens?.access_token) liveToken = tokens.access_token;
 	const tokenInfo = liveToken ? await fetchTokenInfo(liveToken) : null;
 	const scopes = tokenInfo?.scope ? tokenInfo.scope.split(/\s+/).filter(Boolean) : [];
-	const missing = missingRequiredScopes(scopes);
+	const missing = missingRequiredScopes(scopes, byok ? void 0 : tokens?.provider);
 	return {
 		byok,
 		tokens,
@@ -250,15 +250,11 @@ const refreshCommand = defineCommand({
 			logger.error("No saved refresh token. Run `gscdump auth login`.");
 			process.exit(1);
 		}
-		const credentials = await getAuthCredentials(false).catch((e) => {
-			logger.error(`Cannot resolve credentials: ${e.message}`);
-			process.exit(1);
-		});
 		await saveTokens({
 			...tokens,
 			expiry_date: 1
 		});
-		if ((await authenticate(credentials, false).catch((e) => {
+		if ((await getAuth({ interactive: false }).catch((e) => {
 			logger.error(`Refresh failed: ${e.message}`);
 			process.exit(1);
 		})).credentials?.access_token) logger.success("Token refreshed");

package/dist/commands/doctor.mjs

@@ -141,7 +141,7 @@ async function checkAuth(envKeys) {
 		detail: info.email
 	});
 	const scopes = info.scope ? info.scope.split(/\s+/) : [];
-	const missing = missingRequiredScopes(scopes);
+	const missing = missingRequiredScopes(scopes, byok ? void 0 : tokens?.provider);
 	if (missing.length > 0) checks.push({
 		name: "auth.scopes",
 		status: "warn",

package/dist/commands/init.mjs

@@ -2,7 +2,7 @@ import { initCommandMeta } from "../command-meta.mjs";
 import { defaultDataDir, loadConfig, saveConfig } from "../config.mjs";
 import { applyCliEnvironment } from "../environment.mjs";
 import { OUTPUT_ARGS, applyOutputMode, displayPath, logger } from "../utils.mjs";
-import { authenticate, getAuthCredentials, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
+import { authenticate, getAuth, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import fs from "node:fs/promises";
@@ -117,15 +117,12 @@ const initCommand = defineCommand({
 		console.log("  \x1B[90mGoogle Search Console data extraction CLI\x1B[0m");
 		console.log();
 		const dataDir = args["no-store"] ? void 0 : await promptDataDir(config.dataDir);
-		const credentials = await getAuthCredentials(true);
 		await saveConfig({
 			...config,
-			...dataDir ? { dataDir } : {},
-			clientId: credentials.clientId,
-			clientSecret: credentials.clientSecret
+			...dataDir ? { dataDir } : {}
 		});
-		await smokeTest(await authenticate(credentials, true));
-		await maybeWriteEnvFile(credentials.clientId, credentials.clientSecret);
+		await smokeTest(await getAuth({ interactive: true }));
+		if (config.clientId && config.clientSecret) await maybeWriteEnvFile(config.clientId, config.clientSecret);
 		console.log();
 		logger.success("Setup complete! Run gscdump to get started.");
 	}

package/dist/commands/query.mjs

@@ -2,7 +2,7 @@ import { queryCommandMeta } from "../command-meta.mjs";
 import { loadConfig } from "../config.mjs";
 import { terminalOutputOptions } from "../render/terminal.mjs";
 import { ALL_SEARCH_TYPES, logger, parseSearchType, toCSV } from "../utils.mjs";
-import { allTables, inferTable } from "../local-store.mjs";
+import { allTables, inferTable, tableDimensions } from "../local-store.mjs";
 import { createCommandContext } from "../context.mjs";
 import { gscErrorHandler } from "../error-handler.mjs";
 import { renderTable } from "../render/layout.mjs";
@@ -12,6 +12,7 @@ import process from "node:process";
 import { defineCommand } from "citty";
 import fs from "node:fs/promises";
 import { and, between, contains, country, date, device, eq, gsc, hour, notRegex, page, query, regex, searchAppearance } from "gscdump/query";
+import { decodeSiteId } from "gscdump/tenant";
 import { cancel, isCancel, multiselect, text } from "@clack/prompts";
 import { daysAgoUtc } from "gscdump/dates";
 import { collectSpans } from "@gscdump/engine/profile";
@@ -279,7 +280,9 @@ const queryCommand = defineCommand({
 			needsStore: !args.live,
 			interactive: Boolean(args.interactive)
 		});
-		const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+		const hint = args.site ? String(args.site) : ctx.config.defaultSite;
+		const exactHint = !args.live && hint && /^(?:sc-domain:\S+|https?:\/\/\S+)$/.test(hint) ? hint : void 0;
+		const siteUrl = exactHint ? await resolveLocalSite(ctx.store, exactHint) ?? await ctx.resolveSite(hint) : await ctx.resolveSite(hint);
 		if (args.live) {
 			if (args.explain) {
 				const body = {
@@ -339,7 +342,7 @@ const queryCommand = defineCommand({
 			}, null, 2));
 			return;
 		}
-		await assertRangeCovered(store, siteUrl, table, startDate, endDate, searchType);
+		await assertRangeCovered(store, siteUrl, table, startDate, endDate, format === "json", searchType);
 		const probe = Boolean(args.profile) ? collectSpans() : void 0;
 		const result = await store.engine.query({
 			userId: store.userId,
@@ -477,6 +480,14 @@ async function promptFilters(args) {
 		if (ds && String(ds).length > 0) args["data-state"] = String(ds);
 	}
 }
+async function resolveLocalSite(store, hint) {
+	const siteIds = new Set((await store.engine.getWatermarks({ userId: store.userId })).map((w) => w.siteId).filter((siteId) => siteId !== void 0));
+	const exact = store.siteIdFor(hint);
+	if (siteIds.has(exact)) return hint;
+	const lowered = exact.toLowerCase();
+	const matches = [...siteIds].filter((siteId) => siteId.toLowerCase() === lowered);
+	return matches.length === 1 ? decodeSiteId(matches[0]) : void 0;
+}
 function buildLocalState(dimNames, startDate, endDate, rowLimit, dimensionFilter) {
 	const dims = dimNames.map((d) => DIM_COLUMNS[d]).filter((c) => Boolean(c));
 	const dateFilter = between(date, startDate, endDate);
@@ -494,25 +505,70 @@ function buildDimensionFilter(args) {
 	if (leaves.length === 1) return leaves[0];
 	return and(...leaves);
 }
-async function assertRangeCovered(store, siteUrl, table, startDate, endDate, searchType) {
-	const wm = (await store.engine.getWatermarks({
+async function assertRangeCovered(store, siteUrl, table, startDate, endDate, json, searchType) {
+	const watermarks = await store.engine.getWatermarks({
 		userId: store.userId,
 		siteId: store.siteIdFor(siteUrl),
 		table,
 		...searchType !== void 0 ? { searchType } : {}
-	}))[0];
-	if (!wm) {
-		logger.error(`No data synced for ${siteUrl} / ${table}. Run \`gscdump sync\` first, or pass --live.`);
-		process.exit(1);
-	}
-	if (endDate > wm.newestDateSynced) {
-		logger.error(`Requested end=${endDate} is newer than last sync (${wm.newestDateSynced}). Run \`gscdump sync\` first, or pass --live.`);
-		process.exit(1);
+	});
+	const wm = watermarks[0];
+	const states = await store.engine.getSyncStates({
+		userId: store.userId,
+		siteId: store.siteIdFor(siteUrl),
+		table,
+		searchType: searchType ?? "web",
+		state: "done"
+	});
+	const completed = new Set(states.map((state) => state.date));
+	const missingDates = [];
+	for (let date = Date.parse(startDate); date <= Date.parse(endDate); date += 864e5) {
+		const day = new Date(date).toISOString().slice(0, 10);
+		if (!completed.has(day)) missingDates.push(day);
 	}
-	if (startDate < wm.oldestDateSynced) {
-		logger.error(`Requested start=${startDate} is older than first sync (${wm.oldestDateSynced}). Run \`gscdump sync --start=${startDate}\` first, or pass --live.`);
-		process.exit(1);
+	if (missingDates.length === 0) return;
+	const nextArgs = [
+		"sync",
+		"--site",
+		siteUrl,
+		"--start",
+		startDate,
+		"--end",
+		endDate,
+		"--tables",
+		table,
+		"--types",
+		searchType ?? "web",
+		"--json"
+	];
+	const nextCommand = `gscdump ${nextArgs.map((value) => /^[\w:./=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`).join(" ")}`;
+	const message = !wm ? `No data synced for ${siteUrl} / ${table}.` : `Store coverage is incomplete for ${missingDates.length} requested dates.`;
+	if (json) {
+		const available = await store.engine.getWatermarks({
+			userId: store.userId,
+			siteId: store.siteIdFor(siteUrl)
+		});
+		console.log(JSON.stringify({ error: {
+			code: "STORE_RANGE_NOT_COVERED",
+			message,
+			siteUrl,
+			table,
+			range: {
+				start: startDate,
+				end: endDate
+			},
+			missingDates,
+			watermarks: watermarks.filter((w) => w.table === table),
+			availableTables: available.map((w) => ({
+				...w,
+				dimensions: tableDimensions(w.table)
+			})),
+			nextArgs,
+			nextCommand
+		} }, null, 2));
 	}
+	logger.error(`${message} Run ${nextCommand}, or pass --live.`);
+	process.exit(1);
 }
 async function runRawSqlMode(opts) {
 	if (!isKnownTable(opts.table)) {

package/dist/commands/stats.mjs

@@ -1,6 +1,6 @@
 import { terminalOutputOptions } from "../render/terminal.mjs";
 import { OUTPUT_ARGS, applyOutputMode, displayPath, formatAge, logger } from "../utils.mjs";
-import { allTables } from "../local-store.mjs";
+import { allTables, tableDimensions } from "../local-store.mjs";
 import { createCommandContext } from "../context.mjs";
 import { renderTable, textLines } from "../render/layout.mjs";
 import { formatMetric } from "../render/metrics.mjs";
@@ -26,15 +26,11 @@ const statsCommand = defineCommand({
 		const { json } = applyOutputMode(args);
 		const store = (await createCommandContext({ needsStore: true })).store;
 		const allEntries = await store.engine.listAll({ userId: store.userId });
-		let siteId;
-		if (args.site) {
-			const known = new Set(allEntries.filter((entry) => entry.retiredAt === void 0 && entry.siteId !== void 0).map((entry) => entry.siteId));
-			const candidate = store.siteIdFor(args.site);
-			if (!known.has(candidate)) {
-				logger.error(`No local data for --site=${args.site}. Known site IDs: ${known.size === 0 ? "(none — run `gscdump sync` first)" : Array.from(known).join(", ")}`);
-				process.exit(1);
-			}
-			siteId = candidate;
+		const knownSites = [...new Set(allEntries.filter((entry) => entry.retiredAt === void 0 && entry.siteId !== void 0).map((entry) => entry.siteId))];
+		const siteId = args.site ? store.siteIdFor(args.site) : void 0;
+		if (args.site && !json && !knownSites.includes(siteId)) {
+			logger.error(`No local data for --site=${args.site}. Known site IDs: ${knownSites.length === 0 ? "(none — run `gscdump sync` first)" : knownSites.join(", ")}`);
+			process.exit(1);
 		}
 		const selectedEntries = siteId === void 0 ? allEntries : allEntries.filter((entry) => entry.siteId === siteId);
 		const perTable = allTables().map((table) => {
@@ -48,16 +44,17 @@ const statsCommand = defineCommand({
 		const [watermarks, disk] = await Promise.all([store.engine.getWatermarks({
 			userId: store.userId,
 			siteId
-		}), filesystemStats(store.dataDir).catch(() => ({
-			files: 0,
-			bytes: 0
-		}))]);
+		}), filesystemStats(store.dataDir)]);
 		if (json) {
 			const payload = {
 				dataDir: store.dataDir,
+				siteId: siteId ?? null,
+				knownSites,
+				nextCommand: `gscdump sync${args.site ? ` --site '${String(args.site).replaceAll("'", "'\\''")}'` : ""} --status --json`,
 				disk,
 				tables: perTable.map(({ table, live, retired }) => ({
 					table,
+					dimensions: tableDimensions(table),
 					liveFiles: live.length,
 					liveRows: sumRows(live),
 					liveBytes: sumBytes(live),
@@ -65,6 +62,7 @@ const statsCommand = defineCommand({
 					retiredBytes: sumBytes(retired),
 					watermarks: watermarks.filter((w) => w.table === table).map((w) => ({
 						siteId: w.siteId ?? null,
+						searchType: w.searchType ?? "web",
 						newestDateSynced: w.newestDateSynced,
 						oldestDateSynced: w.oldestDateSynced,
 						lastSyncAt: w.lastSyncAt

package/dist/commands/store.mjs

@@ -9,6 +9,7 @@ import { resetCommand, rmSiteCommand } from "./store-purge.mjs";
 import { defineCommand } from "citty";
 const storeCommand = defineCommand({
 	meta: storeCommandMeta,
+	args: statsCommand.args,
 	subCommands: {
 		"stats": statsCommand,
 		"compact": compactCommand,

package/dist/commands/sync.mjs

@@ -276,10 +276,6 @@ const syncCommand = defineCommand({
 			}
 			types.push(t);
 		}
-		if (types.length === 0) {
-			logger.warn(`All requested types (${requestedTypes.join(", ")}) are marked empty for this site. Pass --force-types to re-probe.`);
-			return;
-		}
 		if (skippedTypes.length > 0 && !quiet) logger.info(`Skipping ${skippedTypes.join(", ")} (marked empty for this site; pass --force-types to re-probe).`);
 		const endDate = args.end ? String(args.end) : daysAgoUtc(DEFAULT_PENDING_DAYS);
 		let startDate;
@@ -292,6 +288,32 @@ const syncCommand = defineCommand({
 			logger.error(`No dates to sync (start=${startDate}, end=${endDate})`);
 			process.exit(1);
 		}
+		const printCompletion = async (status, totals, reason, rollupError) => {
+			if (!json) return;
+			console.log(JSON.stringify({
+				status,
+				...reason ? { reason } : {},
+				siteUrl,
+				range: {
+					start: startDate,
+					end: endDate
+				},
+				tables,
+				types,
+				skippedTypes,
+				totals,
+				watermarks: await store.engine.getWatermarks({
+					userId: store.userId,
+					siteId
+				}),
+				...rollupError ? { rollupError } : {}
+			}, null, 2));
+		};
+		if (types.length === 0) {
+			if (!quiet) logger.warn(`All requested types are marked empty. Pass --force-types to check them again.`);
+			await printCompletion("skipped", {}, "empty-types");
+			return;
+		}
 		if (args["retry-failed"]) {
 			const failedSet = /* @__PURE__ */ new Set();
 			const selectedTables = new Set(tables);
@@ -303,7 +325,8 @@ const syncCommand = defineCommand({
 			for (const s of states) if (selectedTables.has(s.table) && selectedTypes.has(s.searchType ?? "web") && s.state === "failed" && s.date >= startDate && s.date <= endDate) failedSet.add(s.date);
 			dates = dates.filter((d) => failedSet.has(d));
 			if (dates.length === 0) {
-				logger.success("No failed dates in range — nothing to retry.");
+				if (!quiet) logger.success("No failed dates in range. Nothing to retry.");
+				await printCompletion("skipped", {}, "no-failed-dates");
 				return;
 			}
 			args.force = true;
@@ -416,6 +439,7 @@ const syncCommand = defineCommand({
 			}
 		}
 		const noRollups = Boolean(args["no-rollups"]);
+		let rollupError;
 		const anyRowsSynced = Object.values(totals).some((t) => t.rows > 0);
 		if (!noRollups && anyRowsSynced) {
 			if (!quiet) logger.info(`Rebuilding rollups for [${siteId}] (${DEFAULT_ROLLUPS.length} rollups)…`);
@@ -442,6 +466,7 @@ const syncCommand = defineCommand({
 				},
 				defs: DEFAULT_ROLLUPS
 			}).catch((err) => {
+				rollupError = err.message;
 				logger.warn(`Rollup rebuild failed: ${err.message}`);
 				return [];
 			});
@@ -451,7 +476,8 @@ const syncCommand = defineCommand({
 				logger.success(`Rebuilt ${results.length} rollup(s) in ${ms}ms — ${kb.toFixed(1)} KB`);
 			}
 		}
-		if (anyFailed) process.exit(1);
+		await printCompletion(anyFailed || rollupError ? "failed" : "completed", totals, void 0, rollupError);
+		if (anyFailed || rollupError) process.exit(1);
 	}
 });
 function isKnownTable(name) {

package/dist/config.mjs

@@ -27,8 +27,13 @@ const configSchema = z.strictObject({
 	]).optional(),
 	serviceAccountPath: z.string().optional()
 });
+const RETIRED_KEYS = ["mode", "cloudUrl"];
+function dropRetiredKeys(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+	return Object.fromEntries(Object.entries(value).filter(([key]) => !RETIRED_KEYS.includes(key)));
+}
 function parseConfig(value) {
-	const parsed = configSchema.safeParse(value);
+	const parsed = configSchema.safeParse(dropRetiredKeys(value));
 	if (!parsed.success) {
 		const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`);
 		throw new Error(`Invalid config at ${getConfigPath()}. ${issues.join("; ")}`);

package/dist/error-handler.mjs

@@ -75,7 +75,7 @@ var LocalStoreUnsupportedError = class extends Error {
 	tool;
 	mode;
 	constructor(tool, mode) {
-		super(`analysis "${tool}" has no implementation for the ${mode} source`);
+		super(mode === "live" ? `The live API cannot run analysis "${tool}". Run gscdump sync, then retry without --live.` : `Local data cannot run analysis "${tool}".`);
 		this.name = "LocalStoreUnsupportedError";
 		this.tool = tool;
 		this.mode = mode;

package/dist/hosted-auth.mjs

@@ -0,0 +1,55 @@
+import { z } from "zod";
+const ORIGIN = "https://gscdump.com";
+const accessSchema = z.object({
+	accessToken: z.string().min(1),
+	expiresAt: z.number().int().positive()
+});
+const pollSchema = z.discriminatedUnion("status", [z.object({ status: z.literal("pending") }), z.object({
+	status: z.literal("complete"),
+	tokens: accessSchema.extend({ refreshToken: z.string().min(1) })
+})]);
+async function requestJson(request, route, init = {}) {
+	const response = await request(`${ORIGIN}/api/cli/auth/${route}`, {
+		...init,
+		redirect: "error",
+		signal: AbortSignal.timeout(3e4)
+	});
+	if (!response.ok) {
+		if (response.status === 429 || response.status >= 500) throw new Error("Google authorization is temporarily unavailable. Try again later.");
+		throw new Error("Google authorization failed. Run `gscdump auth login --mode local --force` to reconnect.");
+	}
+	return response.json();
+}
+async function refreshWithPlatform(refreshToken, request = fetch) {
+	const result = accessSchema.parse(await requestJson(request, "refresh", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ refreshToken })
+	}));
+	return {
+		access_token: result.accessToken,
+		expiry_date: result.expiresAt
+	};
+}
+async function loginWithPlatform(deps) {
+	const init = z.object({
+		code: z.string().regex(/^[A-F0-9]{20}$/),
+		expiresIn: z.number().int().positive().max(600)
+	}).parse(await requestJson(deps.request, "init", { method: "POST" }));
+	const deadline = deps.now() + init.expiresIn * 1e3;
+	const redirect = `/app/cli/auth?code=${init.code}`;
+	const route = deps.force ? `/auth/google?reauth=1&redirect=${encodeURIComponent(redirect)}` : redirect;
+	await deps.authorize(`${ORIGIN}${route}`);
+	while (deps.now() < deadline) {
+		const result = pollSchema.parse(await requestJson(deps.request, `poll?code=${init.code}`));
+		if (result.status === "complete") return {
+			provider: "gscdump",
+			access_token: result.tokens.accessToken,
+			refresh_token: result.tokens.refreshToken,
+			expiry_date: result.tokens.expiresAt
+		};
+		await deps.wait(2e3);
+	}
+	throw new Error("Authorization expired. Run `gscdump auth login` to try again.");
+}
+export { loginWithPlatform, refreshWithPlatform };

package/dist/local-store.mjs

@@ -1,7 +1,18 @@
 import { createNodeHarness } from "@gscdump/engine/node";
+import { SCHEMAS, allTables, inferTable } from "@gscdump/engine/schema";
 import { TABLE_DIMS, assembleDatesRow } from "@gscdump/engine/ingest";
-import { allTables, inferTable } from "@gscdump/engine/schema";
+function tableDimensions(table) {
+	return SCHEMAS[table].columns.map((column) => column.name === "url" ? "page" : column.name === "search_appearance" ? "searchAppearance" : column.name).filter((name) => [
+		"page",
+		"query",
+		"date",
+		"hour",
+		"country",
+		"device",
+		"searchAppearance"
+	].includes(name));
+}
 function createLocalStore(opts) {
 	return createNodeHarness(opts);
 }
-export { TABLE_DIMS, allTables, assembleDatesRow, createLocalStore, inferTable };
+export { TABLE_DIMS, allTables, assembleDatesRow, createLocalStore, inferTable, tableDimensions };

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "3.6.2";
+var version = "3.7.0";
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "3.6.2",
+  "version": "3.7.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,15 +44,15 @@
   "dependencies": {
     "@clack/prompts": "^1.8.0",
     "@duckdb/node-api": "1.5.5-r.4",
-    "@gscdump/analysis": "^3.6.2",
-    "@gscdump/engine": "^3.6.2",
-    "@gscdump/engine-gsc-api": "^3.6.2",
-    "@gscdump/sdk": "^3.6.2",
+    "@gscdump/analysis": "^3.7.0",
+    "@gscdump/engine": "^3.7.0",
+    "@gscdump/engine-gsc-api": "^3.7.0",
+    "@gscdump/sdk": "^3.7.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.0.2",
-    "gscdump": "^3.6.2",
+    "gscdump": "^3.7.0",
     "ofetch": "^1.5.1",
     "open": "^11.0.2",
     "sitemapd": "^0.2.2",

package/skills/gscdump/SKILL.md

@@ -7,6 +7,24 @@ description: Drive the `gscdump` CLI for Google Search Console and Bing with clo
 
 `gscdump` reads Google Search Console and Bing with hosted or local authentication.
 It keeps a local Parquet Store for Google rows. Every command has `--help`.
+For `query`, `-s` means `--site`, `-d` means `--dimensions`, and `-f` means `--format`.
+Use `--start` and `--end` for dates. `--site=SITE` also works.
+Use each option once, with either its short or long spelling.
+Example: `gscdump query --site=SITE --start=DATE --end=DATE -d page -f json`.
+
+## Start each task
+
+1. Before reading traffic, run `gscdump auth status --json`. Do this even when the user says authentication works.
+2. Keep the requested Site, dates, dimensions, and task scope. A request for pages does not need query dimensions.
+3. Before local queries, check coverage with `gscdump store stats --site SITE --json`.
+   Use `gscdump sync --site SITE --status --json` when you need sync-state details.
+4. Read the table dimensions and watermarks. Sync only missing tables and the requested dates, once per task.
+5. Use `sync --json`. Read its completion result before deciding what to do next. Never repeat a successful sync.
+
+If the task only asks about deletion, explain the scope and ask for consent.
+You may read Store metadata with `store stats` and `sync --status`.
+Do not query traffic, sync rows, or delete data to explain deletion.
+Call the local data directory the Store in your answer.
 
 ## Authentication mode
 
@@ -104,10 +122,13 @@ If local Google credentials are missing, use one of these paths:
 | Service account | CI with a service-account key that has Site access | `export GOOGLE_APPLICATION_CREDENTIALS=/abs/path/key.json` |
 | Interactive OAuth | A person is present | `gscdump init --mode local` |
 
-`init` needs a Google Cloud OAuth client of type Desktop app. Ask the user to
-run it; do not guess client credentials. Use `gscdump auth login --mode local --no-browser`
-when a browser cannot open.
-Run `gscdump auth login --mode local` to save local mode after configuring credentials.
+Default local login opens gscdump.com for free Google login and token refresh.
+Data queries call Google directly. No Google Cloud project or hosted activation is required.
+Use `gscdump auth login --mode local --no-browser` when a browser runs on another host.
+The default grant is read-only Search Console access.
+For Google write operations, use your own OAuth client with the required scopes.
+Set `GSC_CLIENT_ID` and `GSC_CLIENT_SECRET` to use a Desktop app OAuth client.
+Cloud mode requires hosted access. Pro is free during beta, then paid after launch.
 
 `--profile <name>` or `GSCDUMP_PROFILE` isolates the selected mode and Google, Bing, and cloud credentials.
 
@@ -130,11 +151,14 @@ gscdump config set defaultSite sc-domain:example.com
 
 ## Output
 
-Pass `--json` on every command that supports it. `query` uses
+Pass `--json` on every command that supports it. `sync --json` includes completion, row counts, skipped dates, and failures.
+`query` uses
 `--format json` and prints rows to stdout. Progress goes to stderr, so stdout
 stays parseable. `--quiet` drops progress lines.
 
 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.
 
 ## Commands
 
@@ -172,9 +196,10 @@ The MCP server does not expose Bing tools. Use `gscdump bing` commands through t
 ## Sync before local analysis
 
 ```sh
+gscdump store stats --site sc-domain:example.com --json
 gscdump sync --site sc-domain:example.com --days 90 \
-  --tables pages,queries,page_queries,countries
-gscdump sync --site sc-domain:example.com --status
+  --tables pages,queries,page_queries,countries --json
+gscdump sync --site sc-domain:example.com --status --json
 ```
 
 - Pass an explicit `--tables` list. The default list has a known daily-totals
@@ -183,6 +208,8 @@ gscdump sync --site sc-domain:example.com --status
 - Sync skips completed dates. `--force` refreshes them. `--retry-failed`
   reruns only failed dates.
 - `--dry-run` prints the planned work without calling Google.
+- Use the user's date range. The 90-day example does not authorize a wider sync.
+- Empty Store metadata is expected before the first sync. It does not prove zero traffic.
 
 ## Query rows
 
@@ -195,8 +222,11 @@ gscdump query --site sc-domain:example.com --dimensions page,query \
 - Filters: `--query`, `--page`, `--country`, `--device`,
   `--search-appearance`. Prefixes: bare equals, `~` contains, `!~` not
   contains, `re:` regex, `!re:` not regex, `!` not equals.
-- `--live` bypasses the Store. `--search-type`, `--data-state`, and
-  `--aggregation-type` apply to live mode only.
+- `--live` bypasses the Store. `--type` selects a search type.
+  `--data-state` and `--aggregation-type` apply to live mode only.
+- Metrics already include clicks, impressions, CTR, and position. There is no `--metrics` option.
+- If Store coverage is missing, read the JSON error and its bounded `nextArgs` before syncing.
+  Do not switch dimensions to make a failed query succeed.
 - `--explain` prints the request body or planned SQL without executing.
 - `--sql` runs raw DuckDB SQL over the Store with `{{FILES}}` as the file list.
 
@@ -270,9 +300,9 @@ the failure and continue. Never retry an uncertain submission.
   delete local data. `--yes` is consent you borrow from the user.
 - **Never loop unattended.** One `sync` per Site per task. Inspection batches
   spend a daily pool. Use `--dry-run` and `--explain` to plan first.
-- **Report the result as the CLI gave it.** An empty result is not a clean
-  Site. Check `sync --status` for the covered date range before reading zero
-  rows as zero traffic.
+- **Report the result as the CLI gave it.** Zero clicks with impressions means rows exist with no clicks.
+  An empty row array means no rows matched. Missing coverage means the Store cannot answer that date range.
+  Check `sync --status --json` before interpreting empty rows. None of these results proves a clean Site.
 - **Do not widen the Site.** A `sc-domain:` property includes every
   subdomain. Filter with `--page` when the user means one host.
 
@@ -285,3 +315,14 @@ Hosted exports follow pagination and reject missing, unavailable, or changing da
 Hosted date ranges span at most 366 days. The default range is the last 366 days.
 Local date filters only narrow data currently returned by Bing.
 Do not treat Bing crawl evidence as proof that a URL is indexed.
+
+## Before the next command
+
+For a traffic task, run `gscdump auth status --json` now, before any `query` command.
+The user saying credentials work does not replace this check. It identifies the selected authentication mode.
+Then check Store metadata, keep the requested dimensions, and read or sync only the requested dates.
+If the user requests JSON, return the command's JSON unchanged, without a table or a separate totals summary.
+Include that JSON in your final response. Tool output alone is not a final answer.
+Include every returned row. Do not refer the user to results "above".
+
+For a deletion explanation, read metadata only if needed. Explain the scope and ask for consent, then stop.