@gscdump/cli 4.8.0 → 5.0.0

package/dist/auth.mjs

@@ -1,7 +1,6 @@
 import { resolveAuthentication } from "./auth-state.mjs";
 import { getConfigDir, loadConfig, saveConfig } from "./config.mjs";
 import { pickCliEnvironmentValue, resolveCliEnvironment } from "./environment.mjs";
-import { getAppliedEnvKeys, getLoadedEnvPath } from "./env-file.mjs";
 import { displayPath, logger } from "./utils.mjs";
 import process from "node:process";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
@@ -361,7 +360,7 @@ async function resolveAuth(opts = {}) {
 	return getAuth(opts);
 }
 function envSourceLabel(envVar) {
-	return getAppliedEnvKeys().has(envVar) ? `.env (${envVar})` : `shell env (${envVar})`;
+	return `environment (${envVar})`;
 }
 function pickEnvSource(...envVars) {
 	return pickCliEnvironmentValue(envVars);
@@ -451,11 +450,6 @@ async function describeAuthProvenance() {
 	else if (tokens) effective = "saved-tokens";
 	else effective = "none";
 	if ((effective === "byok-refresh-token" || effective === "byok-access-token") && tokens) warnings.push("Environment credentials take priority over saved tokens. If you just ran `auth login --force`, unset or update the environment tokens.");
-	if (effective === "byok-refresh-token" && clientId && refreshTok) {
-		if (getAppliedEnvKeys().has(clientId.envVar) !== getAppliedEnvKeys().has(refreshTok.envVar)) warnings.push(`client_id and refresh_token come from different sources (${envSourceLabel(clientId.envVar)} vs ${envSourceLabel(refreshTok.envVar)}); they may not match.`);
-	}
-	const envFile = getLoadedEnvPath();
-	if (envFile && getAppliedEnvKeys().size > 0) warnings.push(`Loaded ${getAppliedEnvKeys().size} var(s) from ${displayPath(envFile)}.`);
 	return {
 		rows,
 		effective,

package/dist/cli.d.mts

@@ -2,7 +2,6 @@ import { CliRuntime, CreateCliRuntimeOptions, createCliRuntime } from "./runtime
 export declare const main: import("citty").CommandDef<import("citty").ArgsDef>;
 export interface RunCliOptions {
   rawArgs?: string[];
-  loadEnv?: boolean;
   environment?: Record<string, string | undefined>;
   runtime?: CliRuntime;
 }

package/dist/cli.mjs

@@ -5,7 +5,6 @@ import { parseAuthMode } from "./auth-state.mjs";
 import { checkCliArgs } from "./cli-args.mjs";
 import { resolveCliEnvironment } from "./environment.mjs";
 import { applyProfileFromCli } from "./commands/profile-selection.mjs";
-import { loadEnvFromCwd } from "./env-file.mjs";
 import { resolveOutputOptions, terminalOutputOptions } from "./render/terminal.mjs";
 import { VERSION, setNoColor, showSplash, withConfiguredOutput } from "./utils.mjs";
 import process from "node:process";
@@ -98,7 +97,6 @@ async function runCli(opts = {}) {
 	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);

package/dist/commands/bing.mjs

@@ -1,7 +1,7 @@
 import { bingCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
 import { resolveAuthentication, saveAuthentication } from "../auth-state.mjs";
-import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.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";
 import { dumpHostedBingSite, hostedBingClient, inspectHostedBingUrl, listHostedBingSites, resolveHostedBingSites } from "../bing-hosted.mjs";
@@ -171,7 +171,7 @@ const bingCommand = defineCommand({
 					authenticated: true,
 					verifiedSites: sites.filter((site) => site.isVerified).length
 				}));
-				else logger.success(`Bing authenticated. ${sites.filter((site) => site.isVerified).length} verified sites.`);
+				else logger.success(`Bing authenticated. ${plural(sites.filter((site) => site.isVerified).length, "verified site", "verified sites")}.`);
 			}
 		}),
 		sites: defineCommand({
@@ -250,7 +250,7 @@ const bingCommand = defineCommand({
 					for (const site of sites) {
 						const summary = await dumpHostedBingSite(authentication, site, args.out, options);
 						summaries.push(summary);
-						if (!json) logger.success(`Bing ${site.siteUrl}: ${summary.files.length} files exported to ${args.out}.`);
+						if (!json) logger.success(`Bing ${site.siteUrl}: ${plural(summary.files.length, "file", "files")} exported to ${args.out}.`);
 					}
 					if (json) console.log(JSON.stringify(args["all-sites"] ? {
 						searchEngine: "bing",
@@ -267,7 +267,7 @@ const bingCommand = defineCommand({
 				for (const site of sites) {
 					const summary = await dumpBingSite(client, site, args.out, options);
 					summaries.push(summary);
-					if (!json) logger.success(`Bing ${site}: ${summary.files.length} files exported to ${args.out}.`);
+					if (!json) logger.success(`Bing ${site}: ${plural(summary.files.length, "file", "files")} exported to ${args.out}.`);
 				}
 				if (json) console.log(JSON.stringify(args["all-sites"] ? {
 					searchEngine: "bing",

package/dist/commands/doctor.mjs

@@ -1,8 +1,7 @@
 import { doctorCommandMeta } from "../command-meta.mjs";
 import { getHostedAccount, resolveAuthentication } from "../auth-state.mjs";
 import { loadConfig } from "../config.mjs";
-import { resolveCliEnvironment } from "../environment.mjs";
-import { parseEnvFile } from "../env-file.mjs";
+import { pickCliEnvironmentValue, resolveCliEnvironment } from "../environment.mjs";
 import { OUTPUT_ARGS, applyOutputMode, displayPath, logger } from "../utils.mjs";
 import { getAuth, isStaleServiceAccountPointer, loadTokens, resolveAuth, resolveBYOK, resolveServiceAccount } from "../auth.mjs";
 import { createLocalStore } from "../local-store.mjs";
@@ -12,73 +11,19 @@ import { currentAccessToken, fetchTokenInfo, redactTokens } from "../token-info.
 import process from "node:process";
 import { defineCommand } from "citty";
 import fs from "node:fs/promises";
-import path from "node:path";
 import { googleSearchConsole } from "gscdump/client";
 import { resolveSiteInput } from "gscdump";
 import { ofetch } from "ofetch";
 const FETCH_TIMEOUT_MS = 5e3;
 const TIME_SKEW_WARN_MS = 3e5;
 const WATERMARK_STALE_DAYS_WARN = 7;
-const RELEVANT_ENV_KEYS = [
-	"GSC_ACCESS_TOKEN",
-	"GSC_CLIENT_ID",
-	"GSC_CLIENT_SECRET",
-	"GSC_REFRESH_TOKEN",
-	"GOOGLE_ACCESS_TOKEN",
-	"GOOGLE_CLIENT_ID",
-	"GOOGLE_CLIENT_SECRET",
-	"GOOGLE_REFRESH_TOKEN",
-	"GOOGLE_APPLICATION_CREDENTIALS",
-	"GSC_SERVICE_ACCOUNT_JSON"
-];
-function redact(v) {
-	if (!v) return "<missing>";
-	if (v.length <= 6) return "***";
-	return `***${v.slice(-6)}`;
-}
-async function checkEnv() {
-	const envPath = path.join(process.cwd(), ".env");
-	const parsed = parseEnvFile(envPath);
-	if (!parsed) return {
-		checks: [{
-			name: "env",
-			status: "info",
-			detail: "no .env (using shell env / saved tokens)"
-		}],
-		envKeys: /* @__PURE__ */ new Set()
-	};
-	const relevant = RELEVANT_ENV_KEYS.filter((k) => parsed[k] !== void 0);
-	const envKeys = new Set(relevant);
-	if (relevant.length === 0) return {
-		checks: [{
-			name: "env",
-			status: "info",
-			detail: `${displayPath(envPath)} found, no auth vars`
-		}],
-		envKeys
-	};
-	const inventory = relevant.map((k) => {
-		const v = parsed[k];
-		if (k.endsWith("CLIENT_ID")) return `${k}=${v}`;
-		return `${k}=${redact(v)}`;
-	});
-	return {
-		checks: [{
-			name: "env",
-			status: "info",
-			detail: `${displayPath(envPath)} → ${inventory.join(", ")} (not validated — see auth)`
-		}],
-		envKeys
-	};
-}
-function describeAuthSource(envKeys, byok) {
+function describeAuthSource(byok) {
 	if (!byok) return "saved tokens";
 	const isAccessToken = typeof byok === "string";
-	const driver = isAccessToken ? "GSC_ACCESS_TOKEN" : "GSC_REFRESH_TOKEN";
-	const source = (isAccessToken ? ["GSC_ACCESS_TOKEN", "GOOGLE_ACCESS_TOKEN"] : ["GSC_REFRESH_TOKEN", "GOOGLE_REFRESH_TOKEN"]).some((k) => envKeys.has(k)) ? ".env" : "shell env";
-	return `environment credentials ${isAccessToken ? "(access-token)" : "(refresh-token)"} from ${source} via ${driver}`;
+	const driver = pickCliEnvironmentValue(isAccessToken ? ["GSC_ACCESS_TOKEN", "GOOGLE_ACCESS_TOKEN"] : ["GSC_REFRESH_TOKEN", "GOOGLE_REFRESH_TOKEN"])?.envVar ?? (isAccessToken ? "GSC_ACCESS_TOKEN" : "GSC_REFRESH_TOKEN");
+	return `environment credentials ${isAccessToken ? "(access-token)" : "(refresh-token)"} via ${driver}`;
 }
-async function checkAuth(envKeys) {
+async function checkAuth() {
 	const checks = [];
 	const serviceAccount = await resolveServiceAccount().catch((error) => {
 		if (isStaleServiceAccountPointer(error)) {
@@ -153,7 +98,7 @@ async function checkAuth(envKeys) {
 		checks.push({
 			name: "auth",
 			status: "fail",
-			detail: `${describeAuthSource(envKeys, byok)}: refresh failed: ${current.detail}. Run \`gscdump auth login --force\` and update the source above.`
+			detail: `${describeAuthSource(byok)}: refresh failed: ${current.detail}. Run \`gscdump auth login --force\` and update the source above.`
 		});
 		return {
 			checks,
@@ -177,7 +122,7 @@ async function checkAuth(envKeys) {
 	checks.push({
 		name: "auth",
 		status: "pass",
-		detail: describeAuthSource(envKeys, byok)
+		detail: describeAuthSource(byok)
 	});
 	if (info.email) checks.push({
 		name: "auth.account",
@@ -410,9 +355,9 @@ async function checkHostedConnection(authentication) {
 		...sitesChecks
 	];
 }
-async function checkLocalConnection(envKeys) {
+async function checkLocalConnection() {
 	const [authResult, timeChecks, gscApi, indexingApi, siteVerificationApi] = await Promise.all([
-		checkAuth(envKeys),
+		checkAuth(),
 		checkTimeSkew(),
 		checkApiReachable("gsc.api", "https://searchconsole.googleapis.com/$discovery/rest?version=v1"),
 		checkApiReachable("indexing.api", "https://indexing.googleapis.com/$discovery/rest?version=v3"),
@@ -439,14 +384,12 @@ const doctorCommand = defineCommand({
 		const { json } = applyOutputMode(args);
 		const { dataDir } = await createCommandContext();
 		const authentication = await resolveAuthentication();
-		const envResult = await checkEnv();
 		const [connectionChecks, dataDirChecks, watermarkChecks] = await Promise.all([
-			authentication._tag === "Hosted" ? checkHostedConnection(authentication) : checkLocalConnection(envResult.envKeys),
+			authentication._tag === "Hosted" ? checkHostedConnection(authentication) : checkLocalConnection(),
 			checkDataDir(dataDir),
 			checkStoreWatermarks(dataDir)
 		]);
 		const all = [
-			...envResult.checks,
 			...connectionChecks,
 			...dataDirChecks,
 			...watermarkChecks

package/dist/commands/init.mjs

@@ -2,17 +2,13 @@ import { initCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
 import { saveAuthentication } from "../auth-state.mjs";
 import { defaultDataDir, loadConfig, saveConfig } from "../config.mjs";
-import { applyCliEnvironment } from "../environment.mjs";
-import { OUTPUT_ARGS, applyOutputMode, displayPath, logger } from "../utils.mjs";
-import { ACCESS_NOT_SET_UP, authenticate, getAuth, loadTokens, resolveBYOK, resolveServiceAccount, saveTokens } from "../auth.mjs";
+import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
+import { ACCESS_NOT_SET_UP, getAuth, loadTokens, resolveBYOK, resolveServiceAccount } from "../auth.mjs";
 import { loginHosted } from "./auth.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { confirm, isCancel, text } from "@clack/prompts";
+import { isCancel, text } from "@clack/prompts";
 import { googleSearchConsole } from "gscdump/client";
-const ENV_LINE_RE = /^([^=]+)=(.*)$/;
 function canPrompt() {
 	return process.stdin.isTTY === true;
 }
@@ -27,24 +23,6 @@ async function promptDataDir(existing) {
 	if (isCancel(answer)) process.exit(1);
 	return String(answer) || fallback;
 }
-async function loadEnvFile() {
-	const envPath = path.join(process.cwd(), ".env");
-	const content = await fs.readFile(envPath, "utf-8").catch(() => null);
-	if (!content) return null;
-	const env = {};
-	for (const line of content.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed || trimmed.startsWith("#")) continue;
-		const match = trimmed.match(ENV_LINE_RE);
-		if (match) {
-			const key = match[1].trim();
-			let value = match[2].trim();
-			if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
-			env[key] = value;
-		}
-	}
-	return env;
-}
 const initCommand = defineCommand({
 	meta: initCommandMeta,
 	args: {
@@ -121,40 +99,6 @@ const initCommand = defineCommand({
 			printNextSteps();
 			return;
 		}
-		const envFile = await loadEnvFile();
-		const envCid = envFile?.GSC_CLIENT_ID ?? envFile?.GOOGLE_CLIENT_ID;
-		const envSec = envFile?.GSC_CLIENT_SECRET ?? envFile?.GOOGLE_CLIENT_SECRET;
-		const envRef = envFile?.GSC_REFRESH_TOKEN ?? envFile?.GOOGLE_REFRESH_TOKEN;
-		const envAcc = envFile?.GSC_ACCESS_TOKEN ?? envFile?.GOOGLE_ACCESS_TOKEN;
-		if (envCid && envSec && envRef) {
-			logger.info("Found .env file with credentials");
-			applyCliEnvironment({
-				GOOGLE_ACCESS_TOKEN: envAcc,
-				GOOGLE_CLIENT_ID: envCid,
-				GOOGLE_CLIENT_SECRET: envSec,
-				GOOGLE_REFRESH_TOKEN: envRef
-			});
-			await saveConfig({
-				...config,
-				clientId: envCid,
-				clientSecret: envSec,
-				dataDir: config.dataDir ?? defaultDataDir()
-			});
-			const creds = (await authenticate({
-				clientId: envCid,
-				clientSecret: envSec
-			}, false)).credentials;
-			if (creds.access_token) await saveTokens({
-				access_token: creds.access_token,
-				refresh_token: creds.refresh_token || envRef,
-				expiry_date: creds.expiry_date
-			});
-			await saveAuthentication({ _tag: "Local" });
-			console.log();
-			logger.success("Setup complete using .env credentials.");
-			printNextSteps();
-			return;
-		}
 		if (!canPrompt()) {
 			if (!await loadTokens()) {
 				logger.error(`Init cannot prompt without a terminal.\n${ACCESS_NOT_SET_UP}`);
@@ -180,7 +124,6 @@ const initCommand = defineCommand({
 		});
 		const sites = await runSmokeTest(await getAuth({ interactive: true }));
 		await saveAuthentication({ _tag: "Local" });
-		if (config.clientId && config.clientSecret) await maybeWriteEnvFile(config.clientId, config.clientSecret);
 		console.log();
 		logger.success("Setup complete.");
 		printNextSteps(sites);
@@ -229,32 +172,4 @@ async function runSmokeTest(oauth) {
 	logger.success(`Verified: ${sites.length} GSC site(s) accessible`);
 	return sites.flatMap((site) => site.siteUrl ? [site.siteUrl] : []);
 }
-async function maybeWriteEnvFile(clientId, clientSecret) {
-	const tokens = await loadTokens();
-	if (!tokens?.refresh_token) return;
-	const wants = await confirm({
-		message: "Write a `.env` file with these credentials? (handy for CI / other machines)",
-		initialValue: false
-	});
-	if (isCancel(wants) || !wants) return;
-	const envPath = path.join(process.cwd(), ".env");
-	if (await fs.stat(envPath).then(() => true).catch(() => false)) {
-		const overwrite = await confirm({
-			message: `${displayPath(envPath)} exists. Overwrite?`,
-			initialValue: false
-		});
-		if (isCancel(overwrite) || !overwrite) {
-			logger.info(`Skipped — keep credentials at ${displayPath(envPath)} manually if needed`);
-			return;
-		}
-	}
-	const content = [
-		`GSC_CLIENT_ID=${clientId}`,
-		`GSC_CLIENT_SECRET=${clientSecret}`,
-		`GSC_REFRESH_TOKEN=${tokens.refresh_token}`,
-		""
-	].join("\n");
-	await fs.writeFile(envPath, content, { mode: 384 });
-	logger.success(`Wrote ${displayPath(envPath)}`);
-}
 export { initCommand, printHostedNextSteps, printNextSteps, runSmokeTest };

package/dist/commands/query.mjs

@@ -1,4 +1,5 @@
 import { queryCommandMeta } from "../command-meta.mjs";
+import { queryHostedRows } from "../hosted-query.mjs";
 import { useCliRuntime } from "../runtime.mjs";
 import { resolveAuthentication } from "../auth-state.mjs";
 import { loadConfig } from "../config.mjs";
@@ -12,14 +13,13 @@ import { renderTable } from "../render/layout.mjs";
 import { asRecord, columnsFor } from "../render/analysis.mjs";
 import { resolveHostedSite } from "../hosted-site.mjs";
 import { FILTER_DIMS, filterDimensions, parseFilterArgs, toLiveFilter, toLocalFilter } from "../filters.mjs";
-import { queryHostedRows } from "../hosted-query.mjs";
 import { renderQuery } from "../render/query.mjs";
 import { openSqlViews, referencedTables } from "../sql-views.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import fs from "node:fs/promises";
 import { and, between, country, date, device, gsc, hour, page, query, searchAppearance } from "gscdump/query";
-import { getLatestGscDate } from "gscdump/dates";
+import { getLatestGscDate, toIsoDate } from "gscdump/dates";
 import { cancel, isCancel, multiselect, text } from "@clack/prompts";
 import { collectSpans } from "@gscdump/engine/profile";
 import { inferDataset, isDatasetResolvable } from "gscdump/query/plan";
@@ -431,7 +431,7 @@ const queryCommand = defineCommand({
 					end: endDate
 				},
 				total: result.rows.length,
-				data: result.rows,
+				data: result.rows.map(withIsoDate),
 				meta: { source: "local" }
 			},
 			format,
@@ -547,7 +547,14 @@ 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);
 	const filter = dimensionFilter ? and(dateFilter, dimensionFilter) : dateFilter;
-	return gsc.select(...dims).where(filter).limit(rowLimit).getState();
+	const builder = gsc.select(...dims).where(filter);
+	return (dimNames.includes("date") ? builder.orderBy(date, "asc") : builder).limit(rowLimit).getState();
+}
+function withIsoDate(row) {
+	return typeof row.date === "number" ? {
+		...row,
+		date: toIsoDate(new Date(row.date))
+	} : row;
 }
 async function runSqlMode(opts) {
 	const ctx = await createCommandContext({ needsStore: true });

package/dist/commands/sitemaps.mjs

@@ -1,5 +1,5 @@
 import { sitemapsCommandMeta } from "../command-meta.mjs";
-import { OUTPUT_ARGS, applyOutputMode, logger, parseIntegerOption } from "../utils.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";
@@ -59,12 +59,12 @@ const listCommand = defineCommand({
 			logger.warn("No sitemaps found");
 			return;
 		}
-		logger.success(`Found ${sitemaps.length} sitemaps:`);
+		logger.success(`Found ${plural(sitemaps.length, "sitemap", "sitemaps")}:`);
 		console.log();
 		for (const sm of sitemaps) {
 			const pending = sm.isPending ? " \x1B[33m(pending)\x1B[0m" : "";
-			const errors = sm.errors ? ` \x1B[31m${sm.errors} errors\x1B[0m` : "";
-			const warnings = sm.warnings ? ` \x1B[33m${sm.warnings} warnings\x1B[0m` : "";
+			const errors = sm.errors ? ` \x1B[31m${plural(sm.errors, "error", "errors")}\x1B[0m` : "";
+			const warnings = sm.warnings ? ` \x1B[33m${plural(sm.warnings, "warning", "warnings")}\x1B[0m` : "";
 			const submitted = sm.lastSubmitted ? ` \x1B[90msubmitted ${sm.lastSubmitted}\x1B[0m` : "";
 			console.log(`  ${sm.path}${pending}${errors}${warnings}${submitted}`);
 		}

package/dist/commands/sites.mjs

@@ -1,6 +1,6 @@
 import { sitesCommandMeta } from "../command-meta.mjs";
 import { LOCAL_MODE_REQUIRED, formatHostedSync, getHostedAccount, resolveAuthentication } from "../auth-state.mjs";
-import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
+import { OUTPUT_ARGS, applyOutputMode, logger, plural } from "../utils.mjs";
 import { createCommandContext, formatSiteResolution } from "../context.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
@@ -362,7 +362,7 @@ const verifyListCommand = defineCommand({
 			logger.warn("No verified WebResources found");
 			return;
 		}
-		logger.success(`${resources.length} verified WebResources:`);
+		logger.success(`${plural(resources.length, "verified WebResource", "verified WebResources")}:`);
 		console.log();
 		for (const r of resources) {
 			const id = r.id ?? "?";
@@ -441,7 +441,7 @@ async function runListHostedSites(args, authentication) {
 		logger.warn("Your hosted record has no Sites. Connect a Site at https://gscdump.com/app/onboarding?step=connect-sites.");
 		return;
 	}
-	logger.success(`Found ${sites.length} hosted sites:`);
+	logger.success(`Found ${plural(sites.length, "hosted Site", "hosted Sites")}:`);
 	console.log();
 	for (const site of sites) console.log(`  ${site.siteUrl} \x1B[90m(${site.siteId})\x1B[0m  hosted sync ${formatHostedSync(site)}`);
 }
@@ -470,10 +470,10 @@ async function runListSites(args) {
 			return;
 		}
 		if (sites.length === 0) {
-			logger.warn(ownerOnly ? "No owned sites found" : "No verified sites found");
+			logger.warn(ownerOnly ? "No owned Sites found" : "No verified Sites found");
 			return;
 		}
-		logger.success(`Found ${sites.length} ${ownerOnly ? "owned" : "verified"} sites:`);
+		logger.success(`Found ${ownerOnly ? plural(sites.length, "owned Site", "owned Sites") : plural(sites.length, "verified Site", "verified Sites")}:`);
 		console.log();
 		for (const site of sites) {
 			const perm = site.permissionLevel === "siteOwner" ? "\x1B[32m" : "\x1B[90m";
@@ -492,10 +492,10 @@ async function runListSites(args) {
 		return;
 	}
 	if (sites.length === 0) {
-		logger.warn(ownerOnly ? "No owned sites found" : "No verified sites found");
+		logger.warn(ownerOnly ? "No owned Sites found" : "No verified Sites found");
 		return;
 	}
-	logger.success(`Found ${sites.length} ${ownerOnly ? "owned " : ""}sites:`);
+	logger.success(`Found ${ownerOnly ? plural(sites.length, "owned Site", "owned Sites") : plural(sites.length, "Site", "Sites")}:`);
 	console.log();
 	for (const site of sites) {
 		const perm = site.permissionLevel === "siteOwner" ? "\x1B[32m" : "\x1B[90m";

package/dist/coverage.mjs

@@ -1,4 +1,5 @@
 import { quotaLedgerPath, quotaStatus, readLedgerState } from "./quota-ledger.mjs";
+import { plural } from "./utils.mjs";
 import { INSPECTION_QPD_PER_PROPERTY } from "./inspection-record.mjs";
 import { inspectionCandidates, loadInspectionState } from "./local-entities.mjs";
 import { datesForJob, jobWindowStart } from "./sync-plan.mjs";
@@ -117,9 +118,6 @@ function hasSyncedDays(states, table, searchType) {
 function n(value) {
 	return value.toLocaleString("en-US");
 }
-function plural(count, one, many) {
-	return `${n(count)} ${count === 1 ? one : many}`;
-}
 function clock(at) {
 	return new Date(at).toLocaleString("en-US", {
 		hour: "numeric",

package/dist/environment.mjs

@@ -23,8 +23,4 @@ function pickCliEnvironmentValue(names, values = useCliRuntime().environment) {
 	}
 	return null;
 }
-function applyCliEnvironment(updates, values = useCliRuntime().environment) {
-	for (const [key, value] of Object.entries(updates)) if (value === void 0) delete values[key];
-	else values[key] = value;
-}
-export { applyCliEnvironment, pickCliEnvironmentValue, resolveCliEnvironment };
+export { pickCliEnvironmentValue, resolveCliEnvironment };

package/dist/error-handler.mjs

@@ -1,6 +1,8 @@
 import { isUsageError } from "./command-registry.mjs";
+import { describeRecordReadRefusal } from "./hosted-query.mjs";
 import { quotaStopOf } from "./quota-ledger.mjs";
 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";
@@ -103,6 +105,10 @@ const DEFECT_ERRORS = /* @__PURE__ */ new Set([
 	"EvalError",
 	"URIError"
 ]);
+function recordReadRefusalOf(error) {
+	if (!(error instanceof Error) || error.name !== "GscdumpV1Error") return null;
+	return parseRecordReadRefusal(error.details);
+}
 function describeCliError(error) {
 	if (isUsageError(error)) return {
 		kind: "usage",
@@ -136,6 +142,12 @@ function describeCliError(error) {
 		hint: error.mode === "local" ? "Pass --live to run against the GSC API." : "",
 		showAuthSources: false
 	};
+	const refusal = recordReadRefusalOf(error);
+	if (refusal) return {
+		kind: "expected",
+		...describeRecordReadRefusal(refusal),
+		showAuthSources: false
+	};
 	const classified = classifyError(error);
 	if (classified.message === HOSTED_KEY_REJECTED) return {
 		kind: "expected",

package/dist/hosted-query.mjs

@@ -28,4 +28,26 @@ async function queryHostedRows(client, siteId, state) {
 	}
 	return rows;
 }
-export { queryHostedRows };
+function describeRecordReadRefusal(refusal) {
+	const running = refusal.syncStatus === "syncing" || refusal.syncStatus === "pending";
+	if (refusal.reason === "record_not_ready") return {
+		message: "The Site's record is not readable yet.",
+		hint: refusal.syncStatus === "synced" && refusal.lastSyncAt !== void 0 ? `Sync finished at ${utcMinute(refusal.lastSyncAt)}. gscdump prepares the record for reads after Sync. Try again in a few minutes.` : running ? "Sync is still running. Run `gscdump sites` to see its progress, then try again when it finishes." : "Try again in a few minutes. Run `gscdump sites` to see the Sync state."
+	};
+	return {
+		message: `The Site's record does not hold ${refusal.missingStart === refusal.missingEnd ? refusal.missingStart : `${refusal.missingStart} to ${refusal.missingEnd}`}.`,
+		hint: rangeHint(refusal, running)
+	};
+}
+function rangeHint(refusal, running) {
+	const { oldestDateSynced: oldest, newestDateSynced: newest } = refusal;
+	const synced = oldest !== void 0 && newest !== void 0;
+	if (synced && refusal.missingStart >= oldest && refusal.missingEnd <= newest) return "Sync covers these days, but the record does not hold them yet. Pick an earlier end date with --end, or try again later.";
+	const covers = synced ? `Sync covers ${oldest} to ${newest}. ` : "";
+	if (running) return `${covers}Sync is still running. Try again when it finishes.`;
+	return synced ? `${covers}Pick dates in that range with --start and --end.` : "Run `gscdump sites` to see the Sync state.";
+}
+function utcMinute(unixSeconds) {
+	return `${(/* @__PURE__ */ new Date(unixSeconds * 1e3)).toISOString().slice(0, 16).replace("T", " ")} UTC`;
+}
+export { describeRecordReadRefusal, queryHostedRows };

package/dist/mcp/types.mjs

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { SearchTypes } from "gscdump/query";
+import "gscdump/dates";
 const periodSchema = z.object({
 	start: z.string().describe("Start date (YYYY-MM-DD)"),
 	end: z.string().describe("End date (YYYY-MM-DD)")

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "4.8.0";
+var version = "5.0.0";
 export { version };

package/dist/render/query.mjs

@@ -21,7 +21,7 @@ function renderQuery(input, options) {
 		if (clicks !== -1) columns[clicks] = barColumn(input.rows, "clicks", options);
 	}
 	return [
-		...textLines(`${parseGscSiteUrl(input.site).hostname} / query`, options, "accent"),
+		...textLines(`${parseGscSiteUrl(input.site).hostname} / ${input.dimensions.join(", ")}`, options, "accent"),
 		...textLines(`${input.start} to ${input.end}`, options, "muted"),
 		"",
 		...renderTable(input.rows, columns, options)

package/dist/sync-plan.mjs

@@ -1,5 +1,5 @@
-import { addDays, getDateRange } from "gscdump/dates";
 import { searchTypeSupportsDimensions, searchTypeSupportsQueries } from "@gscdump/contracts";
+import { addDays, getDateRange } from "gscdump/dates";
 const TABLE_NEEDS = {
 	pages: {
 		queries: false,

package/dist/utils.mjs

@@ -156,6 +156,9 @@ function displayPath(absPath) {
 	if (absPath.startsWith(`${home}/`)) return `~/${absPath.slice(home.length + 1)}`;
 	return absPath;
 }
+function plural(count, one, many) {
+	return `${count.toLocaleString("en-US")} ${count === 1 ? one : many}`;
+}
 function formatAge(ms) {
 	const delta = Date.now() - ms;
 	if (delta < 6e4) return "just now";
@@ -193,4 +196,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, 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, setNoColor, setQuiet, showSplash, toCSV, withConfiguredOutput };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "4.8.0",
+  "version": "5.0.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": "^4.8.0",
-    "@gscdump/contracts": "^4.8.0",
-    "@gscdump/engine": "^4.8.0",
-    "@gscdump/engine-gsc-api": "^4.8.0",
-    "@gscdump/sdk": "^4.8.0",
+    "@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",
     "@modelcontextprotocol/sdk": "^1.30.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.1.0",
-    "gscdump": "^4.8.0",
+    "gscdump": "^5.0.0",
     "ofetch": "^1.5.1",
     "open": "^11.0.4",
     "proper-lockfile": "^4.1.2",

package/dist/env-file.mjs

@@ -1,53 +0,0 @@
-import { useCliRuntime } from "./runtime.mjs";
-import process from "node:process";
-import path from "node:path";
-import fs from "node:fs";
-const ENV_LINE_RE = /^([^=]+)=(.*)$/;
-function parseEnvFile(envPath) {
-	let content;
-	try {
-		content = fs.readFileSync(envPath, "utf-8");
-	} catch {
-		return null;
-	}
-	const env = {};
-	for (const line of content.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed || trimmed.startsWith("#")) continue;
-		const match = trimmed.match(ENV_LINE_RE);
-		if (!match) continue;
-		const key = match[1].trim();
-		let value = match[2].trim();
-		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
-		env[key] = value;
-	}
-	return env;
-}
-const appliedEnvKeys = /* @__PURE__ */ new Set();
-let loadedEnvPath = null;
-function getAppliedEnvKeys() {
-	return appliedEnvKeys;
-}
-function getLoadedEnvPath() {
-	return loadedEnvPath;
-}
-function loadEnvFromCwd() {
-	return loadEnvFile({
-		cwd: process.cwd(),
-		env: useCliRuntime().environment
-	});
-}
-function loadEnvFile(opts) {
-	const envPath = path.join(opts.cwd, ".env");
-	const parsed = parseEnvFile(envPath);
-	if (!parsed) return [];
-	loadedEnvPath = envPath;
-	const applied = [];
-	for (const [key, value] of Object.entries(parsed)) if (opts.env[key] === void 0) {
-		opts.env[key] = value;
-		applied.push(key);
-		appliedEnvKeys.add(key);
-	}
-	return applied;
-}
-export { getAppliedEnvKeys, getLoadedEnvPath, loadEnvFile, loadEnvFromCwd, parseEnvFile };