@gscdump/cli 0.8.0 → 0.8.1

package/dist/index.mjs

@@ -1,27 +1,32 @@
 #!/usr/bin/env node
+import { t as __exportAll } from "./_chunks/rolldown-runtime.mjs";
+import { t as ofetch } from "./_chunks/libs/ofetch.mjs";
+import { a as loadConfig, c as setConfigDir, i as getConfigPath, n as defaultDataDir, o as resolveDataDir, r as getConfigDir, s as saveConfig } from "./_chunks/config.mjs";
+import os from "node:os";
+import path from "node:path";
 import process from "node:process";
 import { defineCommand, runMain } from "citty";
 import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
 import { AnalyzerCapabilityError, analyzeFromSource, createEngineQuerySource } from "@gscdump/analysis";
 import { createGscApiQuerySource } from "@gscdump/engine-gsc-api";
-import { cancel, isCancel, multiselect, select, text } from "@clack/prompts";
-import { daysAgo, fetchSitemap, formatErrorForCli, getDateRange, googleSearchConsole, progressBar } from "gscdump";
+import { cancel, confirm, isCancel, multiselect, select, text } from "@clack/prompts";
+import { addSite, batchInspectUrls, batchRequestIndexing, createAuth, daysAgo, deleteSite, fetchSitemap, fetchSitesWithSitemaps, formatErrorForCli, getDateRange, getIndexingMetadata, getVerificationToken, googleSearchConsole, progressBar, requestIndexing, siteUrlToVerificationSite, verificationMethodsFor, verifySite } from "gscdump";
 import fs, { readFile, rm } from "node:fs/promises";
 import { createServer } from "node:http";
-import path from "node:path";
-import { OAuth2Client } from "google-auth-library";
-import os from "node:os";
-import { consola } from "consola";
+import { JWT, OAuth2Client } from "google-auth-library";
+import { Buffer } from "node:buffer";
+import fs$1 from "node:fs";
+import { createConsola } from "consola";
 import { createNodeHarness } from "@gscdump/engine-duckdb-node";
 import { TABLE_DIMS, transformGscRow } from "@gscdump/engine/ingest";
 import { allTables, inferTable } from "@gscdump/engine/schema";
-import { Buffer } from "node:buffer";
+import { DuckDBInstance } from "@duckdb/node-api";
+import { sqlEscape } from "@gscdump/engine/sql";
 import { createEmptyTypesStore, createIndexingMetadataStore, createInspectionStore, createSitemapStore } from "@gscdump/engine/entities";
 import { createGscMcpServer } from "@gscdump/mcp/server";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { SearchTypes, between, country, date, device, gsc, page, query, searchAppearance } from "gscdump/query";
-import { DuckDBInstance } from "@duckdb/node-api";
-import { sqlEscape } from "@gscdump/engine/sql";
+import { SearchTypes, and, between, contains, country, date, device, eq, gsc, notRegex, page, query, regex, searchAppearance } from "gscdump/query";
+import { inferLegacyTier } from "@gscdump/engine";
 import { DEFAULT_ROLLUPS, rebuildRollups } from "@gscdump/analysis/rollups";
 import { filesystemStats } from "@gscdump/engine/filesystem";
 var LocalStoreUnsupportedError = class extends Error {
@@ -63,42 +68,81 @@ async function runLiveAnalysis(client, siteUrl, params) {
 		throw e;
 	});
 }
-let configDir = path.join(os.homedir(), ".config", "gscdump");
-function getConfigDir() {
-	return configDir;
+const ENV_LINE_RE$1 = /^([^=]+)=(.*)$/;
+function parseEnvFile(envPath) {
+	let content;
+	try {
+		content = fs$1.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$1);
+		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;
 }
-function defaultDataDir() {
-	return path.join(os.homedir(), ".gscdump", "data");
+const appliedEnvKeys = /* @__PURE__ */ new Set();
+let loadedEnvPath = null;
+function getAppliedEnvKeys() {
+	return appliedEnvKeys;
 }
-function resolveDataDir(config) {
-	return expandTilde(config.dataDir ?? defaultDataDir());
+function getLoadedEnvPath() {
+	return loadedEnvPath;
 }
-function expandTilde(p) {
-	if (p === "~") return os.homedir();
-	if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
-	return p;
+function loadEnvFromCwd() {
+	const envPath = path.join(process.cwd(), ".env");
+	const parsed = parseEnvFile(envPath);
+	if (!parsed) return [];
+	loadedEnvPath = envPath;
+	const applied = [];
+	for (const [key, value] of Object.entries(parsed)) if (process.env[key] === void 0) {
+		process.env[key] = value;
+		applied.push(key);
+		appliedEnvKeys.add(key);
+	}
+	return applied;
 }
-async function loadConfig() {
-	return fs.readFile(path.join(configDir, "config.json"), "utf-8").then((data) => JSON.parse(data)).catch(() => ({}));
+const VERSION = "0.8.1";
+const baseLogger = createConsola({
+	stdout: process.stderr,
+	stderr: process.stderr
+});
+const logger = baseLogger.withTag("gscdump");
+function setQuiet(quiet) {
+	if (quiet) baseLogger.level = 1;
 }
-async function saveConfig(config) {
-	await fs.mkdir(configDir, {
-		recursive: true,
-		mode: 448
+let colorEnabled = (() => {
+	if (process.env.NO_COLOR) return false;
+	if (process.argv.includes("--no-color")) return false;
+	return Boolean(process.stderr.isTTY) || Boolean(process.env.FORCE_COLOR);
+})();
+const ANSI_RE = /\x1B\[[0-9;]*m/g;
+let stdoutWrapped = false;
+function wrapStdoutForNoColor() {
+	if (stdoutWrapped) return;
+	stdoutWrapped = true;
+	const original = process.stdout.write.bind(process.stdout);
+	process.stdout.write = ((chunk, ...rest) => {
+		if (typeof chunk === "string") chunk = chunk.replace(ANSI_RE, "");
+		else if (chunk instanceof Uint8Array) chunk = Buffer.from(chunk).toString("utf8").replace(ANSI_RE, "");
+		return original(chunk, ...rest);
 	});
-	await fs.writeFile(path.join(configDir, "config.json"), JSON.stringify(config, null, 2), { mode: 384 });
-}
-function getConfigPath() {
-	return path.join(configDir, "config.json");
 }
-const VERSION = "1.0.0";
-const logger = consola.withTag("gscdump");
-function gscErrorHandler(error) {
-	console.error();
-	console.error(formatErrorForCli(error));
-	console.error();
-	process.exit(1);
+function setNoColor(disable) {
+	if (disable) {
+		colorEnabled = false;
+		wrapStdoutForNoColor();
+	}
 }
+if (!colorEnabled) wrapStdoutForNoColor();
 const gradientColors = [
 	(s) => `\x1B[38;2;52;211;153m${s}\x1B[0m`,
 	(s) => `\x1B[38;2;45;212;191m${s}\x1B[0m`,
@@ -120,6 +164,15 @@ function showSplash() {
 function clearLine() {
 	process.stdout.write("\r\x1B[K");
 }
+function displayPath(absPath) {
+	const cwd = process.cwd();
+	const home = os.homedir();
+	if (absPath === cwd) return ".";
+	if (absPath.startsWith(`${cwd}/`)) return absPath.slice(cwd.length + 1);
+	if (absPath === home) return "~";
+	if (absPath.startsWith(`${home}/`)) return `~/${absPath.slice(home.length + 1)}`;
+	return absPath;
+}
 function formatAge(ms) {
 	const delta = Date.now() - ms;
 	if (delta < 6e4) return "just now";
@@ -146,6 +199,16 @@ function toCSV(data, columns) {
 		return str.includes(",") || str.includes("\"") || str.includes("\n") ? `"${str.replace(/"/g, "\"\"")}"` : str;
 	}).join(","))].join("\n");
 }
+async function readUrlList$1(args) {
+	if (args.file) return (await fs.readFile(String(args.file), "utf-8")).split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+	if (args.urls) return (Array.isArray(args.urls) ? args.urls : [args.urls]).map(String).filter(Boolean);
+	if (!process.stdin.isTTY) {
+		const chunks = [];
+		for await (const chunk of process.stdin) chunks.push(chunk);
+		return Buffer.concat(chunks).toString("utf-8").split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+	}
+	return [];
+}
 function exportToCSV(output) {
 	const sections = [];
 	if (output.pages?.data) sections.push(`# Pages\n${toCSV(output.pages.data, [
@@ -178,6 +241,81 @@ function exportToCSV(output) {
 	])}`);
 	return sections.join("\n\n");
 }
+const SCOPES = [
+	"https://www.googleapis.com/auth/webmasters",
+	"https://www.googleapis.com/auth/indexing",
+	"https://www.googleapis.com/auth/siteverification"
+];
+async function loadServiceAccount(jsonPath) {
+	const raw = await fs.readFile(jsonPath, "utf-8");
+	const key = JSON.parse(raw);
+	if (key.type !== "service_account") throw new Error(`${jsonPath} is not a service-account key (type=${key.type})`);
+	return new JWT({
+		email: key.client_email,
+		key: key.private_key,
+		scopes: SCOPES
+	});
+}
+async function resolveServiceAccount(opts = {}) {
+	const p = opts.path || process.env.GSC_SERVICE_ACCOUNT_JSON || process.env.GOOGLE_APPLICATION_CREDENTIALS;
+	if (!p) return null;
+	return loadServiceAccount(p);
+}
+async function authenticateDeviceCode(credentials) {
+	const init = await ofetch("https://oauth2.googleapis.com/device/code", {
+		method: "POST",
+		body: new URLSearchParams({
+			client_id: credentials.clientId,
+			scope: SCOPES.join(" ")
+		})
+	}).catch((e) => {
+		throw new Error(`Device-code request failed: ${e.message}`);
+	});
+	console.log();
+	console.log(`  \x1B[1mDevice-code OAuth\x1B[0m`);
+	console.log(`  1. On any device, open: \x1B[36m${init.verification_url}\x1B[0m`);
+	console.log(`  2. Enter this code:     \x1B[1m${init.user_code}\x1B[0m`);
+	console.log(`  3. Approve the requested scopes`);
+	console.log();
+	logger.info(`Polling for completion (expires in ${Math.floor(init.expires_in / 60)}m)...`);
+	const intervalMs = init.interval * 1e3;
+	const deadline = Date.now() + init.expires_in * 1e3;
+	while (Date.now() < deadline) {
+		await new Promise((r) => setTimeout(r, intervalMs));
+		const res = await ofetch("https://oauth2.googleapis.com/token", {
+			method: "POST",
+			body: new URLSearchParams({
+				client_id: credentials.clientId,
+				client_secret: credentials.clientSecret,
+				device_code: init.device_code,
+				grant_type: "urn:ietf:params:oauth:grant-type:device_code"
+			})
+		}).catch((e) => e?.data ?? { error: "request_failed" });
+		if (res.access_token) return {
+			access_token: res.access_token,
+			refresh_token: res.refresh_token,
+			expiry_date: res.expires_in ? Date.now() + res.expires_in * 1e3 : void 0
+		};
+		if (res.error === "authorization_pending" || res.error === "slow_down") continue;
+		if (res.error === "access_denied") throw new Error("User denied authorization.");
+		if (res.error === "expired_token") throw new Error("Device code expired. Re-run `gscdump auth login --no-browser`.");
+		if (res.error) throw new Error(`Device-code poll failed: ${res.error_description || res.error}`);
+	}
+	throw new Error("Device-code flow timed out.");
+}
+function resolveBYOK(opts = {}) {
+	const accessToken = opts.accessToken || process.env.GSC_ACCESS_TOKEN || process.env.GOOGLE_ACCESS_TOKEN;
+	const clientId = opts.clientId || process.env.GSC_CLIENT_ID || process.env.GOOGLE_CLIENT_ID;
+	const clientSecret = opts.clientSecret || process.env.GSC_CLIENT_SECRET || process.env.GOOGLE_CLIENT_SECRET;
+	const refreshToken = opts.refreshToken || process.env.GSC_REFRESH_TOKEN || process.env.GOOGLE_REFRESH_TOKEN;
+	if (clientId && clientSecret && refreshToken) return createAuth({
+		clientId,
+		clientSecret,
+		refreshToken
+	});
+	if (accessToken) return accessToken;
+	return null;
+}
 const REDIRECT_URI_RE = /redirect_uri=[^&]+/;
 function getTokensPath() {
 	return path.join(getConfigDir(), "tokens.json");
@@ -200,17 +338,22 @@ async function getAuthCredentials(interactive) {
 	const envClientId = process.env.GOOGLE_CLIENT_ID;
 	const envClientSecret = process.env.GOOGLE_CLIENT_SECRET;
 	if (envClientId && envClientSecret) {
-		logger.success("Using OAuth2 credentials from environment");
+		logger.info("Using OAuth client from env");
+		console.log(`  \x1B[90m${envClientId}\x1B[0m`);
 		return {
 			clientId: envClientId,
 			clientSecret: envClientSecret
 		};
 	}
 	const config = await loadConfig();
-	if (config.clientId && config.clientSecret) return {
-		clientId: config.clientId,
-		clientSecret: config.clientSecret
-	};
+	if (config.clientId && config.clientSecret) {
+		logger.info(`Using OAuth client from ${displayPath(`${getConfigDir()}/config.json`)}`);
+		console.log(`  \x1B[90m${config.clientId}\x1B[0m`);
+		return {
+			clientId: config.clientId,
+			clientSecret: config.clientSecret
+		};
+	}
 	if (!interactive) {
 		logger.error("GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET required for non-interactive mode");
 		process.exit(1);
@@ -246,25 +389,31 @@ async function getAuthCredentials(interactive) {
 async function getAuthCodeViaLoopback(authUrl) {
 	return new Promise((resolve, reject) => {
 		let resolvedRedirectUri = "";
-		const server = createServer((req, res) => {
+		let timeoutId;
+		let server;
+		const settle = (fn) => {
+			if (timeoutId) clearTimeout(timeoutId);
+			server.closeAllConnections?.();
+			server.close();
+			fn();
+		};
+		server = createServer((req, res) => {
 			const url = new URL(req.url || "", `http://127.0.0.1`);
 			const code = url.searchParams.get("code");
 			const error = url.searchParams.get("error");
 			if (error) {
 				res.writeHead(400, { "Content-Type": "text/html" });
 				res.end(`<html><body><h1>Authorization Failed</h1><p>${error}</p><p>You can close this window.</p></body></html>`);
-				server.close();
-				reject(/* @__PURE__ */ new Error(`OAuth error: ${error}`));
+				settle(() => reject(/* @__PURE__ */ new Error(`OAuth error: ${error}`)));
 				return;
 			}
 			if (code) {
 				res.writeHead(200, { "Content-Type": "text/html" });
 				res.end(`<html><body><h1>Authorization Successful</h1><p>You can close this window and return to the terminal.</p></body></html>`);
-				server.close();
-				resolve({
+				settle(() => resolve({
 					code,
 					redirectUri: resolvedRedirectUri
-				});
+				}));
 				return;
 			}
 			res.writeHead(400, { "Content-Type": "text/html" });
@@ -273,7 +422,7 @@ async function getAuthCodeViaLoopback(authUrl) {
 		server.listen(0, "127.0.0.1", () => {
 			const addr = server.address();
 			if (!addr || typeof addr === "string") {
-				reject(/* @__PURE__ */ new Error("Failed to start local server"));
+				settle(() => reject(/* @__PURE__ */ new Error("Failed to start local server")));
 				return;
 			}
 			resolvedRedirectUri = `http://127.0.0.1:${addr.port}`;
@@ -287,17 +436,16 @@ async function getAuthCodeViaLoopback(authUrl) {
 				logger.warn("Could not open browser automatically");
 			});
 		});
-		server.on("error", reject);
-		setTimeout(() => {
-			server.close();
-			reject(/* @__PURE__ */ new Error("Authorization timed out"));
+		server.on("error", (err) => settle(() => reject(err)));
+		timeoutId = setTimeout(() => {
+			settle(() => reject(/* @__PURE__ */ new Error("Authorization timed out")));
 		}, 300 * 1e3);
 	});
 }
-async function authenticate(credentials, interactive) {
+async function authenticate(credentials, interactive, opts = {}) {
 	const oauth2Client = new OAuth2Client(credentials.clientId, credentials.clientSecret, "http://127.0.0.1");
-	const envAccessToken = process.env.GOOGLE_ACCESS_TOKEN;
-	const envRefreshToken = process.env.GOOGLE_REFRESH_TOKEN;
+	const envAccessToken = !opts.force ? process.env.GOOGLE_ACCESS_TOKEN : void 0;
+	const envRefreshToken = !opts.force ? process.env.GOOGLE_REFRESH_TOKEN : void 0;
 	if (envAccessToken || envRefreshToken) {
 		oauth2Client.setCredentials({
 			access_token: envAccessToken,
@@ -309,7 +457,7 @@ async function authenticate(credentials, interactive) {
 		}
 		return oauth2Client;
 	}
-	const existingTokens = await loadTokens();
+	const existingTokens = !opts.force ? await loadTokens() : null;
 	if (existingTokens) {
 		oauth2Client.setCredentials(existingTokens);
 		if (existingTokens.expiry_date && existingTokens.expiry_date < Date.now()) {
@@ -329,9 +477,16 @@ async function authenticate(credentials, interactive) {
 		logger.error("No saved tokens. Run interactively first to authenticate.");
 		process.exit(1);
 	}
+	if (opts.noBrowser) {
+		const tokens = await authenticateDeviceCode(credentials);
+		oauth2Client.setCredentials(tokens);
+		await saveTokens(tokens);
+		logger.success(`Tokens saved to ${displayPath(getTokensPath())}`);
+		return oauth2Client;
+	}
 	const authUrl = oauth2Client.generateAuthUrl({
 		access_type: "offline",
-		scope: ["https://www.googleapis.com/auth/webmasters.readonly", "https://www.googleapis.com/auth/indexing"],
+		scope: SCOPES,
 		prompt: "consent"
 	});
 	logger.info("Waiting for authorization...");
@@ -339,24 +494,163 @@ async function authenticate(credentials, interactive) {
 	const { tokens } = await new OAuth2Client(credentials.clientId, credentials.clientSecret, redirectUri).getToken(code);
 	oauth2Client.setCredentials(tokens);
 	await saveTokens(tokens);
-	logger.success(`Tokens saved to ${getTokensPath()}`);
+	logger.success(`Tokens saved to ${displayPath(getTokensPath())}`);
 	return oauth2Client;
 }
 async function getAuth(opts = {}) {
-	const { interactive = true } = opts;
-	return authenticate(await getAuthCredentials(interactive), interactive);
+	const { interactive = true, noBrowser = false, force = false } = opts;
+	return authenticate(await getAuthCredentials(interactive), interactive, {
+		noBrowser,
+		force
+	});
+}
+async function resolveAuth(opts = {}) {
+	const sa = await resolveServiceAccount({ path: opts.serviceAccount });
+	if (sa) {
+		logger.success("Using service-account credentials");
+		return sa;
+	}
+	const byok = resolveBYOK(opts.byok);
+	if (byok) {
+		if (typeof byok !== "string") logger.success("Using BYOK credentials");
+		return byok;
+	}
+	return getAuth(opts);
+}
+function envSourceLabel(envVar) {
+	return getAppliedEnvKeys().has(envVar) ? `.env (${envVar})` : `shell env (${envVar})`;
+}
+function pickEnvSource(...envVars) {
+	for (const v of envVars) {
+		const value = process.env[v];
+		if (value) return {
+			envVar: v,
+			value
+		};
+	}
+	return null;
+}
+function redactCred(v, keepTail = 6) {
+	if (!v) return "<unset>";
+	if (v.length <= keepTail) return "***";
+	return `***${v.slice(-keepTail)}`;
+}
+async function describeAuthProvenance() {
+	const rows = [];
+	const warnings = [];
+	const saPath = process.env.GSC_SERVICE_ACCOUNT_JSON || process.env.GOOGLE_APPLICATION_CREDENTIALS;
+	if (saPath) {
+		const saEnv = process.env.GSC_SERVICE_ACCOUNT_JSON ? "GSC_SERVICE_ACCOUNT_JSON" : "GOOGLE_APPLICATION_CREDENTIALS";
+		rows.push({
+			field: "service_account",
+			source: envSourceLabel(saEnv),
+			value: displayPath(saPath)
+		});
+	}
+	const clientId = pickEnvSource("GSC_CLIENT_ID", "GOOGLE_CLIENT_ID");
+	const clientSecret = pickEnvSource("GSC_CLIENT_SECRET", "GOOGLE_CLIENT_SECRET");
+	const config = await loadConfig().catch(() => null);
+	if (clientId) rows.push({
+		field: "client_id",
+		source: envSourceLabel(clientId.envVar),
+		value: clientId.value
+	});
+	else if (config?.clientId) rows.push({
+		field: "client_id",
+		source: `${displayPath(`${getConfigDir()}/config.json`)}`,
+		value: config.clientId
+	});
+	else rows.push({
+		field: "client_id",
+		source: "<none>",
+		value: null
+	});
+	if (clientSecret) rows.push({
+		field: "client_secret",
+		source: envSourceLabel(clientSecret.envVar),
+		value: redactCred(clientSecret.value)
+	});
+	else if (config?.clientSecret) rows.push({
+		field: "client_secret",
+		source: `${displayPath(`${getConfigDir()}/config.json`)}`,
+		value: redactCred(config.clientSecret)
+	});
+	else rows.push({
+		field: "client_secret",
+		source: "<none>",
+		value: null
+	});
+	const accessTok = pickEnvSource("GSC_ACCESS_TOKEN", "GOOGLE_ACCESS_TOKEN");
+	const refreshTok = pickEnvSource("GSC_REFRESH_TOKEN", "GOOGLE_REFRESH_TOKEN");
+	if (accessTok) rows.push({
+		field: "access_token",
+		source: envSourceLabel(accessTok.envVar),
+		value: redactCred(accessTok.value)
+	});
+	if (refreshTok) rows.push({
+		field: "refresh_token",
+		source: envSourceLabel(refreshTok.envVar),
+		value: redactCred(refreshTok.value)
+	});
+	const tokens = await loadTokens();
+	if (tokens) {
+		const expiry = tokens.expiry_date ? new Date(tokens.expiry_date).toISOString() : "no expiry";
+		rows.push({
+			field: "saved_tokens",
+			source: displayPath(getTokensPath()),
+			value: `access=${tokens.access_token ? "present" : "missing"}, refresh=${tokens.refresh_token ? "present" : "missing"}, expiry=${expiry}`
+		});
+	}
+	let effective;
+	if (saPath) effective = "service-account";
+	else if (clientId && clientSecret && refreshTok) effective = "byok-refresh-token";
+	else if (accessTok) effective = "byok-access-token";
+	else if (tokens) effective = "saved-tokens";
+	else effective = "none";
+	if ((effective === "byok-refresh-token" || effective === "byok-access-token") && tokens) warnings.push("BYOK env vars shadow saved tokens. If you just ran `auth login --force`, the env tokens are stale; unset them or update them.");
+	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,
+		warnings
+	};
+}
+async function formatAuthProvenance() {
+	const { rows, effective, warnings } = await describeAuthProvenance();
+	const lines = [];
+	lines.push(`  \x1B[1mAuth config sources\x1B[0m \x1B[90m(effective: ${effective})\x1B[0m`);
+	for (const r of rows) {
+		const val = r.value ? ` \x1B[90m${r.value}\x1B[0m` : "";
+		lines.push(`    ${r.field.padEnd(16)} \x1B[36m${r.source}\x1B[0m${val}`);
+	}
+	if (warnings.length > 0) {
+		lines.push("");
+		for (const w of warnings) lines.push(`  \x1B[33m!\x1B[0m ${w}`);
+	}
+	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");
 }
 function createLocalStore(opts) {
 	return createNodeHarness(opts);
 }
+var context_exports = /* @__PURE__ */ __exportAll({ createCommandContext: () => createCommandContext });
 async function createCommandContext(opts = {}) {
-	const { needsAuth = false, needsStore = false, interactive = false } = opts;
+	const { needsAuth = false, needsStore = false, interactive = false, byok, fetchOptions } = opts;
 	const config = await loadConfig();
-	const auth = needsAuth ? await getAuth({
+	const auth = needsAuth ? await resolveAuth({
 		interactive,
-		config
+		config,
+		byok
 	}) : null;
-	const client = auth ? googleSearchConsole(auth) : null;
+	const client = auth ? googleSearchConsole(auth, { fetchOptions }) : null;
 	const store = needsStore ? createLocalStore({ dataDir: resolveDataDir(config) }) : null;
 	const loadSites = async () => {
 		if (!client) throw new Error("loadSites requires needsAuth: true");
@@ -402,6 +696,16 @@ async function createCommandContext(opts = {}) {
 		resolveSite
 	};
 }
+async function gscErrorHandler(error) {
+	console.error();
+	console.error(formatErrorForCli(error));
+	if (isAuthError(error)) {
+		console.error();
+		console.error(await formatAuthProvenance());
+	}
+	console.error();
+	process.exit(1);
+}
 const ANALYSIS_TOOLS = defaultAnalyzerRegistry.listAnalyzerIds();
 const TOOL_EXTRA_ARGS = {
 	brand: { "brand-terms": {
@@ -551,10 +855,7 @@ function makeToolCommand(tool) {
 				renderResults(localResult.results, localResult.results.length, format);
 				return;
 			}
-			const result = await runLiveAnalysis(ctx.client, siteUrl, params).catch((e) => {
-				logger.error(`Analysis failed: ${e.message}`);
-				process.exit(1);
-			});
+			const result = await runLiveAnalysis(ctx.client, siteUrl, params).catch(gscErrorHandler);
 			if (format === "json") {
 				console.log(JSON.stringify(result, null, 2));
 				return;
@@ -737,35 +1038,203 @@ const analyzeCommand = defineCommand({
 	},
 	subCommands: Object.fromEntries(ANALYSIS_TOOLS.map((tool) => [tool, makeToolCommand(tool)]))
 });
+async function fetchTokenInfo(accessToken) {
+	return ofetch("https://oauth2.googleapis.com/tokeninfo", { query: { access_token: accessToken } }).catch(() => null);
+}
+const statusCommand$1 = defineCommand({
+	meta: {
+		name: "status",
+		description: "Show current authentication status"
+	},
+	args: {
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Output as JSON"
+		},
+		quiet: {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info/success output"
+		}
+	},
+	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
+		const tokens = await loadTokens();
+		const byok = resolveBYOK();
+		const byokKind = byok ? typeof byok === "string" ? "access-token" : "refresh-token" : null;
+		let liveToken = null;
+		if (typeof byok === "string") liveToken = byok;
+		else if (byok && "getAccessToken" in byok) liveToken = await byok.getAccessToken().then((r) => r.token ?? null).catch(() => null);
+		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) : [];
+		if (args.json) {
+			console.log(JSON.stringify({
+				authenticated: !!tokens || !!byok,
+				source: byok ? "byok" : tokens ? "saved-tokens" : null,
+				byokKind,
+				scopes,
+				tokenAccount: tokenInfo?.email ?? null,
+				tokens: tokens ? {
+					hasAccessToken: !!tokens.access_token,
+					hasRefreshToken: !!tokens.refresh_token,
+					expiry: tokens.expiry_date ? new Date(tokens.expiry_date).toISOString() : null,
+					expired: tokens.expiry_date ? tokens.expiry_date < Date.now() : null
+				} : null
+			}, null, 2));
+			return;
+		}
+		const reportScopes = () => {
+			if (scopes.length === 0) return;
+			console.log(`  Scopes:`);
+			const required = [
+				"https://www.googleapis.com/auth/webmasters",
+				"https://www.googleapis.com/auth/indexing",
+				"https://www.googleapis.com/auth/siteverification"
+			];
+			const has = (s) => scopes.includes(s) || scopes.includes(s.replace(".readonly", ""));
+			for (const s of scopes) console.log(`    \x1B[90m└─\x1B[0m ${s}`);
+			const missing = required.filter((s) => !has(s));
+			if (missing.length > 0) {
+				console.log(`  \x1B[33mMissing scopes:\x1B[0m`);
+				for (const s of missing) console.log(`    \x1B[90m└─\x1B[0m ${s}`);
+				console.log(`  \x1B[90mRun \`gscdump auth login --force\` to re-consent.\x1B[0m`);
+			}
+		};
+		if (byok) {
+			logger.success(`Authenticated via BYOK (${byokKind})`);
+			if (tokenInfo?.email) console.log(`  Account:       ${tokenInfo.email}`);
+			reportScopes();
+			return;
+		}
+		if (!tokens) {
+			logger.warn("Not authenticated");
+			logger.info("Run `gscdump init` (full setup) or `gscdump auth login` (OAuth only)");
+			logger.info("Or set GSC_ACCESS_TOKEN / GSC_CLIENT_ID + GSC_CLIENT_SECRET + GSC_REFRESH_TOKEN env vars");
+			return;
+		}
+		const hasAccess = !!tokens.access_token;
+		const hasRefresh = !!tokens.refresh_token;
+		const expiry = tokens.expiry_date ? new Date(tokens.expiry_date) : null;
+		const isExpired = expiry && expiry < /* @__PURE__ */ new Date();
+		logger.success("Authenticated (saved tokens)");
+		console.log();
+		console.log(`  Access token:  ${hasAccess ? "\x1B[32mpresent\x1B[0m" : "\x1B[31mmissing\x1B[0m"}`);
+		console.log(`  Refresh token: ${hasRefresh ? "\x1B[32mpresent\x1B[0m" : "\x1B[31mmissing\x1B[0m"}`);
+		if (expiry) {
+			const status = isExpired ? "\x1B[33mexpired\x1B[0m" : "\x1B[32mvalid\x1B[0m";
+			console.log(`  Expires:       ${expiry.toISOString()} (${status})`);
+		}
+		if (tokenInfo?.email) console.log(`  Account:       ${tokenInfo.email}`);
+		reportScopes();
+	}
+});
+const refreshCommand = defineCommand({
+	meta: {
+		name: "refresh",
+		description: "Force-refresh saved OAuth tokens (no-op for BYOK)"
+	},
+	args: { quiet: {
+		type: "boolean",
+		alias: "q",
+		default: false,
+		description: "Suppress info/success output"
+	} },
+	async run({ args }) {
+		setQuiet(Boolean(args.quiet));
+		if (resolveBYOK()) {
+			logger.info("BYOK detected; refresh handled per-call by the SDK");
+			return;
+		}
+		const tokens = await loadTokens();
+		if (!tokens?.refresh_token) {
+			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) => {
+			logger.error(`Refresh failed: ${e.message}`);
+			process.exit(1);
+		})).credentials?.access_token) logger.success("Token refreshed");
+		else logger.warn("Refresh completed but no new access token returned");
+	}
+});
 const authCommand = defineCommand({
 	meta: {
 		name: "auth",
 		description: "Manage authentication"
 	},
 	subCommands: {
-		status: defineCommand({
+		status: statusCommand$1,
+		login: defineCommand({
 			meta: {
-				name: "status",
-				description: "Show current authentication status"
+				name: "login",
+				description: "Run OAuth flow and persist tokens (skip if BYOK env vars set)"
 			},
-			async run() {
-				const tokens = await loadTokens();
-				if (!tokens) {
-					logger.warn("Not authenticated");
-					logger.info("Run gscdump init to authenticate");
+			args: {
+				"force": {
+					type: "boolean",
+					alias: "f",
+					default: false,
+					description: "Re-run OAuth even if tokens already exist"
+				},
+				"browser": {
+					type: "boolean",
+					default: true,
+					description: "Use loopback browser flow. Pass --no-browser for device-code (headless)."
+				},
+				"service-account": {
+					type: "string",
+					description: "Path to a service-account JSON key (skips OAuth)"
+				},
+				"quiet": {
+					type: "boolean",
+					alias: "q",
+					default: false,
+					description: "Suppress info/success output"
+				}
+			},
+			async run({ args }) {
+				setQuiet(Boolean(args.quiet));
+				if (resolveBYOK() && !args.force) {
+					logger.info("BYOK env vars detected, no login needed (--force to override)");
 					return;
 				}
-				const hasAccess = !!tokens.access_token;
-				const hasRefresh = !!tokens.refresh_token;
-				const expiry = tokens.expiry_date ? new Date(tokens.expiry_date) : null;
-				const isExpired = expiry && expiry < /* @__PURE__ */ new Date();
-				logger.success("Authenticated");
-				console.log();
-				console.log(`  Access token:  ${hasAccess ? "\x1B[32mpresent\x1B[0m" : "\x1B[31mmissing\x1B[0m"}`);
-				console.log(`  Refresh token: ${hasRefresh ? "\x1B[32mpresent\x1B[0m" : "\x1B[31mmissing\x1B[0m"}`);
-				if (expiry) {
-					const status = isExpired ? "\x1B[33mexpired\x1B[0m" : "\x1B[32mvalid\x1B[0m";
-					console.log(`  Expires:       ${expiry.toISOString()} (${status})`);
+				if (args["service-account"]) {
+					const jwt = await loadServiceAccount(String(args["service-account"])).catch((e) => {
+						logger.error(`Service-account load failed: ${e.message}`);
+						process.exit(1);
+					});
+					await jwt.authorize().catch((e) => {
+						logger.error(`Service-account auth failed: ${e.message}`);
+						process.exit(1);
+					});
+					logger.success(`Service-account verified: ${jwt.email ?? "OK"}`);
+					logger.info(`Set GOOGLE_APPLICATION_CREDENTIALS=${args["service-account"]} to use it across sessions.`);
+					return;
+				}
+				if (args.force) await clearTokens();
+				await getAuth({
+					interactive: true,
+					noBrowser: args.browser === false,
+					force: Boolean(args.force)
+				}).catch((e) => {
+					logger.error(`Login failed: ${e.message}`);
+					process.exit(1);
+				});
+				logger.success("Logged in");
+				if (resolveBYOK()) {
+					console.log();
+					console.log(await formatAuthProvenance());
 				}
 			}
 		}),
@@ -774,35 +1243,76 @@ const authCommand = defineCommand({
 				name: "logout",
 				description: "Clear stored OAuth tokens"
 			},
-			async run() {
+			args: { quiet: {
+				type: "boolean",
+				alias: "q",
+				default: false,
+				description: "Suppress info/success output"
+			} },
+			async run({ args }) {
+				setQuiet(Boolean(args.quiet));
 				await clearTokens();
 			}
-		})
+		}),
+		refresh: refreshCommand
+	}
+});
+const showCommand = defineCommand({
+	meta: {
+		name: "show",
+		description: "Show current config"
+	},
+	args: {
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Output config as a single JSON object (suppresses path header)"
+		},
+		quiet: {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info/success output"
+		}
+	},
+	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
+		const config = await loadConfig();
+		const configPath = getConfigPath();
+		if (args.json) {
+			console.log(JSON.stringify({
+				path: configPath,
+				config
+			}, null, 2));
+			return;
+		}
+		logger.info(`Config: ${displayPath(configPath)}`);
+		console.log();
+		if (Object.keys(config).length === 0) {
+			logger.warn("No config set");
+			return;
+		}
+		console.log(JSON.stringify(config, null, 2));
 	}
 });
+const VALID_KEYS = [
+	"defaultSite",
+	"defaultPeriod",
+	"defaultFormat",
+	"defaultDb",
+	"dataDir",
+	"defaultLimit",
+	"defaultSearchType",
+	"defaultDataState"
+];
+const NUMERIC_KEYS = new Set(["defaultLimit"]);
 const configCommand = defineCommand({
 	meta: {
 		name: "config",
 		description: "Manage configuration"
 	},
 	subCommands: {
-		show: defineCommand({
-			meta: {
-				name: "show",
-				description: "Show current config"
-			},
-			async run() {
-				const config = await loadConfig();
-				const configPath = getConfigPath();
-				logger.info(`Config: ${configPath}`);
-				console.log();
-				if (Object.keys(config).length === 0) {
-					logger.warn("No config set");
-					return;
-				}
-				console.log(JSON.stringify(config, null, 2));
-			}
-		}),
+		show: showCommand,
 		set: defineCommand({
 			meta: {
 				name: "set",
@@ -811,31 +1321,37 @@ const configCommand = defineCommand({
 			args: {
 				key: {
 					type: "positional",
-					description: "Config key (defaultSite, defaultPeriod, defaultFormat, defaultDb)",
+					description: `Config key (${VALID_KEYS.join(", ")})`,
 					required: true
 				},
 				value: {
 					type: "positional",
 					description: "Value to set",
 					required: true
+				},
+				quiet: {
+					type: "boolean",
+					alias: "q",
+					default: false,
+					description: "Suppress info/success output"
 				}
 			},
 			async run({ args }) {
-				const validKeys = [
-					"defaultSite",
-					"defaultPeriod",
-					"defaultFormat",
-					"defaultDb"
-				];
-				if (!validKeys.includes(args.key)) {
+				setQuiet(Boolean(args.quiet));
+				if (!VALID_KEYS.includes(args.key)) {
 					logger.error(`Invalid key: ${args.key}`);
-					logger.info(`Valid keys: ${validKeys.join(", ")}`);
+					logger.info(`Valid keys: ${VALID_KEYS.join(", ")}`);
 					process.exit(1);
 				}
 				const config = await loadConfig();
-				config[args.key] = args.value;
+				const value = NUMERIC_KEYS.has(args.key) ? Number(args.value) : args.value;
+				if (NUMERIC_KEYS.has(args.key) && !Number.isFinite(value)) {
+					logger.error(`Invalid numeric value for ${args.key}: ${args.value}`);
+					process.exit(1);
+				}
+				config[args.key] = value;
 				await saveConfig(config);
-				logger.success(`Set ${args.key} = ${args.value}`);
+				logger.success(`Set ${args.key} = ${value}`);
 			}
 		}),
 		unset: defineCommand({
@@ -843,12 +1359,26 @@ const configCommand = defineCommand({
 				name: "unset",
 				description: "Remove a config value"
 			},
-			args: { key: {
-				type: "positional",
-				description: "Config key to remove",
-				required: true
-			} },
+			args: {
+				key: {
+					type: "positional",
+					description: `Config key to remove (${VALID_KEYS.join(", ")})`,
+					required: true
+				},
+				quiet: {
+					type: "boolean",
+					alias: "q",
+					default: false,
+					description: "Suppress info/success output"
+				}
+			},
 			async run({ args }) {
+				setQuiet(Boolean(args.quiet));
+				if (!VALID_KEYS.includes(args.key)) {
+					logger.error(`Invalid key: ${args.key}`);
+					logger.info(`Valid keys: ${VALID_KEYS.join(", ")}`);
+					process.exit(1);
+				}
 				const config = await loadConfig();
 				delete config[args.key];
 				await saveConfig(config);
@@ -863,33 +1393,523 @@ const configCommand = defineCommand({
 			run() {
 				console.log(getConfigPath());
 			}
+		}),
+		validate: defineCommand({
+			meta: {
+				name: "validate",
+				description: "Validate the saved config (defaultSite is verified, dataDir exists/writable)"
+			},
+			args: {
+				json: {
+					type: "boolean",
+					default: false,
+					description: "Output as JSON"
+				},
+				quiet: {
+					type: "boolean",
+					alias: "q",
+					default: false,
+					description: "Suppress info/success output"
+				}
+			},
+			async run({ args }) {
+				setQuiet(Boolean(args.quiet) || Boolean(args.json));
+				const { resolveDataDir } = await import("./_chunks/config.mjs").then((n) => n.t);
+				const fs = await import("node:fs/promises");
+				const config = await loadConfig();
+				const issues = [];
+				const dataDir = resolveDataDir(config);
+				const dataDirDisplay = displayPath(dataDir);
+				const stat = await fs.stat(dataDir).catch(() => null);
+				if (stat && !stat.isDirectory()) issues.push({
+					key: "dataDir",
+					level: "fail",
+					message: `${dataDirDisplay} is not a directory`
+				});
+				else if (stat) {
+					const probe = `${dataDir}/.gscdump-config-probe`;
+					if (!await fs.writeFile(probe, "").then(() => fs.rm(probe)).then(() => true).catch(() => false)) issues.push({
+						key: "dataDir",
+						level: "fail",
+						message: `${dataDirDisplay} not writable`
+					});
+				} else issues.push({
+					key: "dataDir",
+					level: "warn",
+					message: `${dataDirDisplay} does not exist (will be created on first sync)`
+				});
+				if (config.defaultSite) if (!!config.clientId && !!config.clientSecret) {
+					const { createCommandContext } = await Promise.resolve().then(() => context_exports);
+					const ctx = await createCommandContext({ needsAuth: true }).catch(() => null);
+					if (ctx) {
+						const sites = await ctx.loadSites().catch(() => null);
+						if (sites && !sites.some((s) => s.siteUrl === config.defaultSite || s.siteUrl.includes(String(config.defaultSite)))) issues.push({
+							key: "defaultSite",
+							level: "fail",
+							message: `${config.defaultSite} is not in the verified site list`
+						});
+					}
+				} else issues.push({
+					key: "defaultSite",
+					level: "warn",
+					message: "set, but auth not configured — skipping verification"
+				});
+				if (config.defaultFormat && !["json", "csv"].includes(config.defaultFormat)) issues.push({
+					key: "defaultFormat",
+					level: "fail",
+					message: `unknown format: ${config.defaultFormat}`
+				});
+				if (args.json) {
+					console.log(JSON.stringify({
+						ok: !issues.some((i) => i.level === "fail"),
+						issues
+					}, null, 2));
+					return;
+				}
+				if (issues.length === 0) {
+					logger.success("Config OK");
+					return;
+				}
+				for (const i of issues) {
+					const prefix = i.level === "fail" ? "\x1B[31m✗\x1B[0m" : "\x1B[33m!\x1B[0m";
+					console.log(`  ${prefix} ${i.key}: ${i.message}`);
+				}
+				if (issues.some((i) => i.level === "fail")) process.exit(1);
+			}
 		})
 	}
 });
-const DEFAULT_OUT = "./gscdump-export";
-const dumpCommand = defineCommand({
-	meta: {
+const REQUIRED_SCOPES = [
+	"https://www.googleapis.com/auth/webmasters",
+	"https://www.googleapis.com/auth/indexing",
+	"https://www.googleapis.com/auth/siteverification"
+];
+const FETCH_TIMEOUT_MS = 5e3;
+const TIME_SKEW_WARN_MS = 5 * 6e4;
+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) {
+	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 `BYOK ${isAccessToken ? "(access-token)" : "(refresh-token)"} from ${source} via ${driver}`;
+}
+async function checkAuth$1(envKeys) {
+	const checks = [];
+	const byok = resolveBYOK();
+	const tokens = await loadTokens();
+	if (!byok && !tokens) {
+		checks.push({
+			name: "auth",
+			status: "fail",
+			detail: "no BYOK env vars and no saved tokens; run `gscdump init`"
+		});
+		return {
+			checks,
+			liveToken: null
+		};
+	}
+	const clientId = process.env.GSC_CLIENT_ID ?? process.env.GOOGLE_CLIENT_ID ?? (await loadConfig()).clientId ?? null;
+	if (clientId) checks.push({
+		name: "auth.client_id",
+		status: "info",
+		detail: clientId
+	});
+	let liveToken = null;
+	let refreshError = null;
+	if (typeof byok === "string") liveToken = byok;
+	else if (byok && "getAccessToken" in byok) liveToken = await byok.getAccessToken().then((r) => r.token ?? null).catch((e) => {
+		refreshError = e?.data?.error_description ?? e?.data?.error ?? e?.message ?? String(e);
+		return null;
+	});
+	else if (tokens?.access_token) liveToken = tokens.access_token;
+	if (!liveToken) {
+		const source = describeAuthSource(envKeys, byok);
+		const detail = refreshError ? `${source} — refresh failed: ${refreshError} (token revoked / invalid — re-run \`gscdump auth login --force\` and update the source above)` : `${source} — no usable access token`;
+		checks.push({
+			name: "auth",
+			status: "fail",
+			detail
+		});
+		return {
+			checks,
+			liveToken: null
+		};
+	}
+	const info = await ofetch("https://oauth2.googleapis.com/tokeninfo", { query: { access_token: liveToken } }).catch((e) => ({ error: e.message }));
+	if ("error" in info) {
+		checks.push({
+			name: "auth",
+			status: "fail",
+			detail: `tokeninfo failed: ${info.error}`
+		});
+		return {
+			checks,
+			liveToken: null
+		};
+	}
+	checks.push({
+		name: "auth",
+		status: "pass",
+		detail: describeAuthSource(envKeys, byok)
+	});
+	if (info.email) checks.push({
+		name: "auth.account",
+		status: "pass",
+		detail: info.email
+	});
+	const scopes = info.scope ? info.scope.split(/\s+/) : [];
+	const missing = REQUIRED_SCOPES.filter((s) => !scopes.includes(s) && !scopes.includes(s.replace(".readonly", "")));
+	if (missing.length > 0) checks.push({
+		name: "auth.scopes",
+		status: "warn",
+		detail: `missing: ${missing.join(", ")} — \`gscdump auth login --force\` to re-consent`
+	});
+	else checks.push({
+		name: "auth.scopes",
+		status: "pass",
+		detail: `${scopes.length} granted`
+	});
+	if (tokens?.expiry_date) {
+		const expiresInMs = tokens.expiry_date - Date.now();
+		if (expiresInMs < 0) checks.push({
+			name: "auth.expiry",
+			status: "warn",
+			detail: `expired ${new Date(tokens.expiry_date).toISOString()} — will refresh on next call`
+		});
+		else checks.push({
+			name: "auth.expiry",
+			status: "pass",
+			detail: `valid for ${Math.floor(expiresInMs / 6e4)}m`
+		});
+	}
+	return {
+		checks,
+		liveToken
+	};
+}
+async function checkTimeSkew() {
+	const dateHeader = await ofetch.raw("https://oauth2.googleapis.com/tokeninfo", {
+		method: "GET",
+		timeout: FETCH_TIMEOUT_MS
+	}).then((r) => r.headers.get("date")).catch((e) => e?.response?.headers?.get("date") ?? null);
+	if (!dateHeader) return [{
+		name: "time",
+		status: "warn",
+		detail: "could not probe Google clock (no Date header)"
+	}];
+	const remoteMs = Date.parse(dateHeader);
+	if (!Number.isFinite(remoteMs)) return [{
+		name: "time",
+		status: "warn",
+		detail: `unparseable Date header: ${dateHeader}`
+	}];
+	const skewMs = Date.now() - remoteMs;
+	const human = `${skewMs >= 0 ? "+" : ""}${(skewMs / 1e3).toFixed(1)}s`;
+	if (Math.abs(skewMs) > TIME_SKEW_WARN_MS) return [{
+		name: "time",
+		status: "warn",
+		detail: `local clock ${human} off Google — OAuth refresh may reject; sync your clock`
+	}];
+	return [{
+		name: "time",
+		status: "pass",
+		detail: `in sync (${human})`
+	}];
+}
+async function checkDataDir() {
+	const dataDir = resolveDataDir(await loadConfig());
+	const display = displayPath(dataDir);
+	const stat = await fs.stat(dataDir).catch(() => null);
+	if (!stat) return [{
+		name: "dataDir",
+		status: "warn",
+		detail: `${display} does not exist (will be created on first sync)`
+	}];
+	if (!stat.isDirectory()) return [{
+		name: "dataDir",
+		status: "fail",
+		detail: `${display} is not a directory`
+	}];
+	const probe = `${dataDir}/.gscdump-doctor-probe`;
+	return await fs.writeFile(probe, "").then(() => fs.rm(probe)).then(() => true).catch(() => false) ? [{
+		name: "dataDir",
+		status: "pass",
+		detail: display
+	}] : [{
+		name: "dataDir",
+		status: "fail",
+		detail: `${display} not writable`
+	}];
+}
+async function checkStoreWatermarks() {
+	const dataDir = resolveDataDir(await loadConfig());
+	if (!(await fs.stat(dataDir).catch(() => null))?.isDirectory()) return [{
+		name: "store.watermarks",
+		status: "pass",
+		detail: "no store yet (run `gscdump sync`)"
+	}];
+	const store = createLocalStore({ dataDir });
+	const watermarks = await store.engine.getWatermarks({ userId: store.userId }).catch(() => null);
+	if (!watermarks || watermarks.length === 0) return [{
+		name: "store.watermarks",
+		status: "pass",
+		detail: "no watermarks (run `gscdump sync`)"
+	}];
+	const bySite = /* @__PURE__ */ new Map();
+	for (const w of watermarks) {
+		const site = w.siteId ?? "(global)";
+		const existing = bySite.get(site);
+		if (!existing || w.newestDateSynced > existing) bySite.set(site, w.newestDateSynced);
+	}
+	const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	const stale = [];
+	let freshest = null;
+	for (const [site, newest] of bySite) {
+		const days = Math.floor((Date.parse(today) - Date.parse(newest)) / 864e5);
+		if (days > WATERMARK_STALE_DAYS_WARN) stale.push({
+			site,
+			days
+		});
+		if (!freshest || days < freshest.days) freshest = {
+			site,
+			days
+		};
+	}
+	if (stale.length > 0) {
+		const sample = stale.slice(0, 3).map((s) => `${s.site} (${s.days}d)`).join(", ");
+		const more = stale.length > 3 ? ` +${stale.length - 3} more` : "";
+		return [{
+			name: "store.watermarks",
+			status: "warn",
+			detail: `${stale.length}/${bySite.size} site(s) stale >${WATERMARK_STALE_DAYS_WARN}d: ${sample}${more}`
+		}];
+	}
+	const tail = freshest ? `, freshest ${freshest.days}d ago` : "";
+	return [{
+		name: "store.watermarks",
+		status: "pass",
+		detail: `${bySite.size} site(s)${tail}`
+	}];
+}
+async function checkApiReachable(name, url) {
+	const reachable = await ofetch.raw(url, {
+		method: "GET",
+		timeout: FETCH_TIMEOUT_MS
+	}).then(() => true).catch(() => false);
+	return [{
+		name,
+		status: reachable ? "pass" : "warn",
+		detail: reachable ? "reachable" : `${new URL(url).hostname} unreachable (network/firewall?)`
+	}];
+}
+async function checkGscSites() {
+	const config = await loadConfig();
+	const auth = await resolveAuth({
+		interactive: false,
+		config
+	}).catch(() => null);
+	if (!auth) return [{
+		name: "gsc.sites",
+		status: "warn",
+		detail: "skipped (no usable auth)"
+	}];
+	const sites = await googleSearchConsole(auth).sites().catch((e) => e);
+	if (sites instanceof Error) return [{
+		name: "gsc.sites",
+		status: "fail",
+		detail: `sites() failed: ${sites.message}`
+	}];
+	const checks = [];
+	const verified = sites.filter((s) => s.permissionLevel !== "siteUnverifiedUser").length;
+	checks.push({
+		name: "gsc.sites",
+		status: "pass",
+		detail: `${sites.length} site(s) accessible (${verified} verified)`
+	});
+	if (config.defaultSite) {
+		const match = sites.find((s) => s.siteUrl === config.defaultSite || (s.siteUrl ?? "").includes(String(config.defaultSite)));
+		checks.push(match ? {
+			name: "config.defaultSite",
+			status: "pass",
+			detail: `${config.defaultSite} ✓`
+		} : {
+			name: "config.defaultSite",
+			status: "fail",
+			detail: `${config.defaultSite} not in verified site list`
+		});
+	}
+	return checks;
+}
+const doctorCommand = defineCommand({
+	meta: {
+		name: "doctor",
+		description: "Run health checks (env, auth, scopes, time, dataDir, store, GSC reachability + ping, defaultSite)"
+	},
+	args: { json: {
+		type: "boolean",
+		default: false,
+		description: "Output as JSON"
+	} },
+	async run({ args }) {
+		const envResult = await checkEnv();
+		const [authResult, timeChecks, dataDirChecks, watermarkChecks, gscApi, indexingApi, siteVerificationApi] = await Promise.all([
+			checkAuth$1(envResult.envKeys),
+			checkTimeSkew(),
+			checkDataDir(),
+			checkStoreWatermarks(),
+			checkApiReachable("gsc.api", "https://searchconsole.googleapis.com/$discovery/rest?version=v1"),
+			checkApiReachable("indexing.api", "https://indexing.googleapis.com/$discovery/rest?version=v3"),
+			checkApiReachable("siteverification.api", "https://www.googleapis.com/discovery/v1/apis/siteVerification/v1/rest")
+		]);
+		const sitesChecks = authResult.liveToken ? await checkGscSites() : [{
+			name: "gsc.sites",
+			status: "warn",
+			detail: "skipped (auth failed)"
+		}];
+		const all = [
+			...envResult.checks,
+			...authResult.checks,
+			...timeChecks,
+			...dataDirChecks,
+			...watermarkChecks,
+			...gscApi,
+			...indexingApi,
+			...siteVerificationApi,
+			...sitesChecks
+		];
+		if (args.json) {
+			console.log(JSON.stringify({
+				checks: all,
+				ok: all.every((c) => c.status !== "fail")
+			}, null, 2));
+			return;
+		}
+		const ICONS = {
+			pass: "\x1B[32m✓\x1B[0m",
+			warn: "\x1B[33m!\x1B[0m",
+			fail: "\x1B[31m✗\x1B[0m",
+			info: "\x1B[34mℹ\x1B[0m"
+		};
+		console.log();
+		for (const c of all) {
+			const detail = c.detail ? ` \x1B[90m${c.detail}\x1B[0m` : "";
+			console.log(`  ${ICONS[c.status]} ${c.name}${detail}`);
+		}
+		console.log();
+		const failed = all.filter((c) => c.status === "fail");
+		if (failed.length > 0) {
+			logger.error(`${failed.length} check(s) failed`);
+			process.exit(1);
+		}
+		const warned = all.filter((c) => c.status === "warn");
+		if (warned.length > 0) logger.warn(`${warned.length} warning(s)`);
+		else logger.success("All checks passed");
+	}
+});
+const DEFAULT_OUT = "./gscdump-export";
+const FORMATS = [
+	"parquet",
+	"json",
+	"ndjson",
+	"csv"
+];
+const dumpCommand = defineCommand({
+	meta: {
 		name: "dump",
 		description: "Export live Parquet files from the local store to a directory"
 	},
 	args: {
-		site: {
+		"site": {
 			type: "string",
 			alias: "s",
-			description: "Site URL (e.g., sc-domain:example.com)"
+			description: "Site URL (e.g., sc-domain:example.com); ignored with --all-sites"
 		},
-		out: {
+		"out": {
 			type: "string",
 			alias: "o",
 			default: DEFAULT_OUT,
 			description: `Output directory (default: ${DEFAULT_OUT})`
 		},
-		compact: {
+		"format": {
+			type: "string",
+			alias: "F",
+			default: "parquet",
+			description: `Output format: ${FORMATS.join(", ")} (default: parquet copies raw files)`
+		},
+		"tables": {
+			type: "string",
+			alias: "t",
+			description: `Comma-separated table list (default: all). Known: ${allTables().join(", ")}`
+		},
+		"all-sites": {
+			type: "boolean",
+			default: false,
+			description: "Iterate every site with local data"
+		},
+		"compact": {
 			type: "boolean",
 			default: false,
 			description: "Compact every closed month into a single file before exporting"
 		},
-		quiet: {
+		"json": {
+			type: "boolean",
+			default: false,
+			description: "Emit a JSON summary of what was exported"
+		},
+		"quiet": {
 			type: "boolean",
 			alias: "q",
 			default: false,
@@ -897,31 +1917,76 @@ const dumpCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
+		const format = String(args.format);
+		if (!FORMATS.includes(format)) {
+			logger.error(`Invalid --format: ${format}. Allowed: ${FORMATS.join(", ")}`);
+			process.exit(1);
+		}
+		const tablesFilter = args.tables ? new Set(String(args.tables).split(",").map((t) => t.trim()).filter(Boolean)) : null;
 		const ctx = await createCommandContext({
-			needsAuth: true,
+			needsAuth: !args["all-sites"],
 			needsStore: true
 		});
-		const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
 		const store = ctx.store;
 		const outDir = path.resolve(String(args.out));
-		if (args.compact) await compactClosedMonths(store, siteUrl, args.quiet);
-		const entries = await listLiveEntries(store, siteUrl);
-		if (entries.length === 0) {
-			logger.warn(`No data for ${siteUrl}. Run \`gscdump sync\` first.`);
+		const targets = args["all-sites"] ? await listSitesWithData(store) : [await ctx.resolveSite(args.site ? String(args.site) : void 0)];
+		if (targets.length === 0) {
+			logger.warn("No sites with local data. Run `gscdump sync` first.");
 			process.exit(0);
 		}
-		await fs.mkdir(outDir, { recursive: true });
-		let copied = 0;
-		for (const entry of entries) {
-			const bytes = await store.engine.readObject(entry.objectKey);
-			const target = path.join(outDir, entry.objectKey);
-			await fs.mkdir(path.dirname(target), { recursive: true });
-			await fs.writeFile(target, Buffer.from(bytes));
-			copied++;
+		if (args.compact) for (const siteUrl of targets) await compactClosedMonths(store, siteUrl, args.quiet);
+		const summary = [];
+		for (const siteUrl of targets) {
+			const entries = (await listLiveEntries(store, siteUrl)).filter((e) => !tablesFilter || tablesFilter.has(e.table));
+			if (entries.length === 0) {
+				if (!args.json && !args.quiet) logger.warn(`No data for ${siteUrl}; skipping`);
+				continue;
+			}
+			if (format === "parquet") {
+				const written = await dumpParquet(store, entries, outDir);
+				summary.push({
+					site: siteUrl,
+					files: written,
+					rows: 0,
+					format,
+					outPath: outDir
+				});
+			} else {
+				const written = await dumpRowFormat(store, entries, outDir, siteUrl, format);
+				summary.push({
+					site: siteUrl,
+					files: written.files,
+					rows: written.rows,
+					format,
+					outPath: outDir
+				});
+			}
+		}
+		if (args.json) {
+			console.log(JSON.stringify({
+				outDir,
+				sites: summary
+			}, null, 2));
+			return;
+		}
+		for (const s of summary) {
+			const rows = s.rows ? `, ${s.rows.toLocaleString()} rows` : "";
+			logger.success(`[${s.site}] ${s.files} ${s.format} file(s)${rows} → ${displayPath(s.outPath)}`);
 		}
-		if (!args.quiet) logger.success(`Exported ${copied} file(s) to ${outDir}`);
 	}
 });
+async function listSitesWithData(store) {
+	const siteIds = /* @__PURE__ */ new Set();
+	for (const table of allTables()) {
+		const entries = await store.engine.listLive({
+			userId: store.userId,
+			table
+		});
+		for (const e of entries) if (e.siteId) siteIds.add(e.siteId);
+	}
+	return Array.from(siteIds);
+}
 async function listLiveEntries(store, siteUrl) {
 	const siteId = store.siteIdFor(siteUrl);
 	return (await Promise.all(allTables().map((table) => store.engine.listLive({
@@ -930,6 +1995,58 @@ async function listLiveEntries(store, siteUrl) {
 		table
 	})))).flat();
 }
+async function dumpParquet(store, entries, outDir) {
+	await fs.mkdir(outDir, { recursive: true });
+	let copied = 0;
+	for (const entry of entries) {
+		const bytes = await store.engine.readObject(entry.objectKey);
+		const target = path.join(outDir, entry.objectKey);
+		await fs.mkdir(path.dirname(target), { recursive: true });
+		await fs.writeFile(target, Buffer.from(bytes));
+		copied++;
+	}
+	return copied;
+}
+async function dumpRowFormat(store, entries, outDir, siteUrl, format) {
+	const byTable = /* @__PURE__ */ new Map();
+	for (const e of entries) {
+		const arr = byTable.get(e.table) ?? [];
+		arr.push(e);
+		byTable.set(e.table, arr);
+	}
+	const safeSite = siteUrl.replace(/[^a-z0-9]+/gi, "_");
+	const siteDir = path.join(outDir, safeSite);
+	await fs.mkdir(siteDir, { recursive: true });
+	let files = 0;
+	let totalRows = 0;
+	for (const [table, tableEntries] of byTable) {
+		const rows = await readTableRows(tableEntries.map((e) => path.join(store.dataDir, e.objectKey)));
+		const ext = format === "csv" ? "csv" : format === "ndjson" ? "ndjson" : "json";
+		const target = path.join(siteDir, `${table}.${ext}`);
+		let body;
+		if (format === "json") body = JSON.stringify(rows, null, 2);
+		else if (format === "ndjson") body = rows.map((r) => JSON.stringify(r)).join("\n");
+		else body = rows.length > 0 ? toCSV(rows, Object.keys(rows[0])) : "";
+		await fs.writeFile(target, body);
+		files++;
+		totalRows += rows.length;
+	}
+	return {
+		files,
+		rows: totalRows
+	};
+}
+async function readTableRows(filePaths) {
+	const instance = await DuckDBInstance.create(":memory:");
+	const conn = await instance.connect();
+	try {
+		const fileList = filePaths.map((p) => `'${sqlEscape(p)}'`).join(", ");
+		return (await conn.runAndReadAll(`SELECT * FROM read_parquet([${fileList}], union_by_name=true)`)).getRowObjects();
+	} finally {
+		conn.closeSync();
+		instance.closeSync();
+	}
+}
 async function compactClosedMonths(store, siteUrl, quiet) {
 	const siteId = store.siteIdFor(siteUrl);
 	for (const table of allTables()) {
@@ -958,8 +2075,7 @@ const inspectSubCommand = defineCommand({
 		site: {
 			type: "string",
 			alias: "s",
-			required: true,
-			description: "Site URL (e.g., sc-domain:example.com)"
+			description: "Site URL (e.g., sc-domain:example.com); defaults to config.defaultSite or prompt"
 		},
 		file: {
 			type: "string",
@@ -976,6 +2092,11 @@ const inspectSubCommand = defineCommand({
 			default: "4",
 			description: "Concurrent in-flight inspect calls (default: 4)"
 		},
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Emit a JSON summary of inspection results"
+		},
 		quiet: {
 			type: "boolean",
 			alias: "q",
@@ -984,16 +2105,17 @@ const inspectSubCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
 		const ctx = await createCommandContext({
 			needsAuth: true,
 			needsStore: true
 		});
 		const client = ctx.client;
 		const store = ctx.store;
-		const siteUrl = String(args.site);
+		const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
 		const limit = args.limit ? Number.parseInt(String(args.limit), 10) : INSPECTION_QPD_PER_PROPERTY;
 		const concurrency = Math.max(1, Number.parseInt(String(args.concurrency), 10) || 4);
-		const quiet = Boolean(args.quiet);
+		const quiet = Boolean(args.quiet) || Boolean(args.json);
 		const urls = (await readUrlList({ file: args.file ? String(args.file) : void 0 })).slice(0, limit);
 		if (urls.length === 0) {
 			logger.warn("No URLs to inspect.");
@@ -1041,7 +2163,14 @@ const inspectSubCommand = defineCommand({
 			userId: store.userId,
 			siteId: store.siteIdFor(siteUrl)
 		}, records);
-		if (!quiet) {
+		if (args.json) console.log(JSON.stringify({
+			site: siteUrl,
+			inspected: records.length,
+			failed,
+			failures,
+			records
+		}, null, 2));
+		else if (!quiet) {
 			logger.success(`Inspected ${records.length}/${urls.length} URL(s)`);
 			if (failed > 0) {
 				logger.warn(`${failed} failed:`);
@@ -1061,8 +2190,7 @@ const showSubCommand = defineCommand({
 		site: {
 			type: "string",
 			alias: "s",
-			required: true,
-			description: "Site URL"
+			description: "Site URL (defaults to config.defaultSite or prompt)"
 		},
 		url: {
 			type: "positional",
@@ -1076,10 +2204,15 @@ const showSubCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const store = (await createCommandContext({ needsStore: true })).store;
+		const ctx = await createCommandContext({
+			needsAuth: true,
+			needsStore: true
+		});
+		const store = ctx.store;
+		const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
 		const record = await createInspectionStore({ dataSource: store.dataSource }).getLatest({
 			userId: store.userId,
-			siteId: store.siteIdFor(String(args.site))
+			siteId: store.siteIdFor(siteUrl)
 		}, String(args.url));
 		if (!record) {
 			logger.warn(`No inspection record for ${args.url}`);
@@ -1110,8 +2243,7 @@ const sitemapsSnapshotSubCommand = defineCommand({
 		site: {
 			type: "string",
 			alias: "s",
-			required: true,
-			description: "Site URL (e.g., sc-domain:example.com)"
+			description: "Site URL (e.g., sc-domain:example.com); defaults to config.defaultSite or prompt"
 		},
 		quiet: {
 			type: "boolean",
@@ -1132,7 +2264,7 @@ const sitemapsSnapshotSubCommand = defineCommand({
 		});
 		const client = ctx.client;
 		const store = ctx.store;
-		const siteUrl = String(args.site);
+		const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
 		const quiet = Boolean(args.quiet);
 		const apiSitemaps = await client.sitemaps.list(siteUrl);
 		const capturedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -1185,8 +2317,7 @@ const sitemapsShowSubCommand = defineCommand({
 		site: {
 			type: "string",
 			alias: "s",
-			required: true,
-			description: "Site URL"
+			description: "Site URL (defaults to config.defaultSite or prompt)"
 		},
 		path: {
 			type: "positional",
@@ -1200,10 +2331,15 @@ const sitemapsShowSubCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const store = (await createCommandContext({ needsStore: true })).store;
+		const ctx = await createCommandContext({
+			needsAuth: true,
+			needsStore: true
+		});
+		const store = ctx.store;
+		const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
 		const record = await createSitemapStore({ dataSource: store.dataSource }).getLatest({
 			userId: store.userId,
-			siteId: store.siteIdFor(String(args.site))
+			siteId: store.siteIdFor(siteUrl)
 		}, String(args.path));
 		if (!record) {
 			logger.warn(`No sitemap record for ${args.path}`);
@@ -1249,8 +2385,7 @@ const indexingSubCommand = defineCommand({
 			site: {
 				type: "string",
 				alias: "s",
-				required: true,
-				description: "Site URL (e.g., sc-domain:example.com)"
+				description: "Site URL (e.g., sc-domain:example.com); defaults to config.defaultSite or prompt"
 			},
 			file: {
 				type: "string",
@@ -1277,7 +2412,7 @@ const indexingSubCommand = defineCommand({
 			});
 			const client = ctx.client;
 			const store = ctx.store;
-			const siteUrl = String(args.site);
+			const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
 			const concurrency = Math.max(1, Number.parseInt(String(args.concurrency), 10) || 4);
 			const quiet = Boolean(args.quiet);
 			const urls = await readUrlList({ file: args.file ? String(args.file) : void 0 });
@@ -1346,124 +2481,575 @@ const entitiesCommand = defineCommand({
 		indexing: indexingSubCommand
 	}
 });
-const ENV_LINE_RE = /^([^=]+)=(.*)$/;
-async function promptDataDir(existing) {
-	const fallback = existing ?? defaultDataDir();
-	const answer = await text({
-		message: "Where should Parquet data be stored?",
-		placeholder: fallback,
-		defaultValue: fallback
-	});
-	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 RETRIES_ARG = { retries: {
+	type: "string",
+	description: "Override per-call retry count (default: 3)"
+} };
+function parseRetries(v) {
+	if (v == null || v === "") return void 0;
+	const n = Number.parseInt(String(v), 10);
+	return Number.isFinite(n) && n >= 0 ? n : void 0;
 }
-const initCommand = defineCommand({
-	meta: {
-		name: "init",
-		description: "Set up GSCDump authentication"
-	},
-	args: { force: {
-		type: "boolean",
-		alias: "f",
-		description: "Force re-initialization"
-	} },
-	async run({ args }) {
-		const config = await loadConfig();
-		if (config.clientId && config.clientSecret && !args.force) {
-			logger.info("Already configured");
-			logger.info("Run with --force to reconfigure");
-			return;
-		}
-		const envFile = await loadEnvFile();
-		if (envFile?.GOOGLE_CLIENT_ID && envFile?.GOOGLE_CLIENT_SECRET && envFile?.GOOGLE_REFRESH_TOKEN) {
-			logger.info("Found .env file with Google credentials");
-			process.env.GOOGLE_CLIENT_ID = envFile.GOOGLE_CLIENT_ID;
-			process.env.GOOGLE_CLIENT_SECRET = envFile.GOOGLE_CLIENT_SECRET;
-			process.env.GOOGLE_REFRESH_TOKEN = envFile.GOOGLE_REFRESH_TOKEN;
-			if (envFile.GOOGLE_ACCESS_TOKEN) process.env.GOOGLE_ACCESS_TOKEN = envFile.GOOGLE_ACCESS_TOKEN;
-			await saveConfig({
-				...config,
-				clientId: envFile.GOOGLE_CLIENT_ID,
-				clientSecret: envFile.GOOGLE_CLIENT_SECRET,
-				dataDir: config.dataDir ?? defaultDataDir()
-			});
-			const creds = (await authenticate({
-				clientId: envFile.GOOGLE_CLIENT_ID,
-				clientSecret: envFile.GOOGLE_CLIENT_SECRET
-			}, false)).credentials;
-			if (creds.access_token) await saveTokens({
-				access_token: creds.access_token,
-				refresh_token: creds.refresh_token || envFile.GOOGLE_REFRESH_TOKEN,
-				expiry_date: creds.expiry_date
-			});
-			console.log();
-			logger.success("Setup complete using .env credentials! Run gscdump to get started.");
-			return;
-		}
-		console.log();
-		console.log("  \x1B[1mWelcome to GSCDump!\x1B[0m");
-		console.log("  \x1B[90mGoogle Search Console data extraction CLI\x1B[0m");
-		console.log();
-		const dataDir = await promptDataDir(config.dataDir);
-		const credentials = await getAuthCredentials(true);
-		await saveConfig({
-			...config,
-			dataDir,
-			clientId: credentials.clientId,
-			clientSecret: credentials.clientSecret
-		});
-		await authenticate(credentials, true);
-		console.log();
-		logger.success("Setup complete! Run gscdump to get started.");
-	}
-});
-const inspectCommand = defineCommand({
+const submitCommand$1 = defineCommand({
 	meta: {
-		name: "inspect",
-		description: "Inspect a specific URL's indexing status"
+		name: "submit",
+		description: "Notify Google of a new or updated URL (URL_UPDATED)"
 	},
 	args: {
-		site: {
-			type: "string",
-			alias: "s",
-			required: true,
-			description: "Site URL (e.g., sc-domain:example.com)"
-		},
 		url: {
 			type: "positional",
 			required: true,
-			description: "URL to inspect"
+			description: "URL to submit"
 		},
 		json: {
 			type: "boolean",
 			default: false,
 			description: "Output as JSON"
-		}
+		},
+		quiet: {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info/success output"
+		},
+		...RETRIES_ARG
 	},
 	async run({ args }) {
-		const result = await (await createCommandContext({ needsAuth: true })).client.inspect(args.site, args.url).catch((e) => {
-			logger.error(`Inspection failed: ${e.message}`);
-			process.exit(1);
-		});
-		const indexStatus = (result?.inspectionResult)?.indexStatusResult;
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
+		const result = await requestIndexing((await createCommandContext({
+			needsAuth: true,
+			fetchOptions: { retry: parseRetries(args.retries) }
+		})).client, args.url, { type: "URL_UPDATED" }).catch(gscErrorHandler);
+		if (args.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		logger.success(`Submitted: ${result.url}`);
+		if (result.notifyTime) console.log(`  Notified: ${result.notifyTime}`);
+	}
+});
+const removeCommand = defineCommand({
+	meta: {
+		name: "remove",
+		description: "Notify Google a URL has been removed (URL_DELETED)"
+	},
+	args: {
+		url: {
+			type: "positional",
+			required: true,
+			description: "URL to mark removed"
+		},
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Output as JSON"
+		},
+		quiet: {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info/success output"
+		},
+		...RETRIES_ARG
+	},
+	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
+		const result = await requestIndexing((await createCommandContext({
+			needsAuth: true,
+			fetchOptions: { retry: parseRetries(args.retries) }
+		})).client, args.url, { type: "URL_DELETED" }).catch(gscErrorHandler);
+		if (args.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		logger.success(`Removed: ${result.url}`);
+		if (result.notifyTime) console.log(`  Notified: ${result.notifyTime}`);
+	}
+});
+const statusCommand = defineCommand({
+	meta: {
+		name: "status",
+		description: "Show indexing notification metadata for a URL"
+	},
+	args: {
+		url: {
+			type: "positional",
+			required: true,
+			description: "URL to inspect"
+		},
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Output as JSON"
+		},
+		quiet: {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info/success output"
+		}
+	},
+	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
+		const meta = await getIndexingMetadata((await createCommandContext({ needsAuth: true })).client, args.url).catch(gscErrorHandler);
+		if (args.json) {
+			console.log(JSON.stringify(meta, null, 2));
+			return;
+		}
+		const fmtNotification = (n) => {
+			if (!n?.notifyTime) return "never";
+			return n.type ? `${n.notifyTime} (${n.type})` : n.notifyTime;
+		};
+		const update = meta.latestUpdate;
+		const remove = meta.latestRemove;
+		console.log();
+		console.log(`  \x1B[1mURL:\x1B[0m ${meta.url}`);
+		console.log(`  Last update notify: ${fmtNotification(update)}`);
+		console.log(`  Last remove notify: ${fmtNotification(remove)}`);
+		console.log();
+	}
+});
+const INDEXING_DAILY_QUOTA = 200;
+const indexingCommand = defineCommand({
+	meta: {
+		name: "indexing",
+		description: "Notify Google about URL updates/removals (Indexing API)"
+	},
+	subCommands: {
+		submit: submitCommand$1,
+		remove: removeCommand,
+		status: statusCommand,
+		batch: defineCommand({
+			meta: {
+				name: "batch",
+				description: "Submit many URLs from a file or stdin (one URL per line)"
+			},
+			args: {
+				"urls": {
+					type: "positional",
+					required: false,
+					description: "URLs (or use --file/stdin)"
+				},
+				"file": {
+					type: "string",
+					alias: "f",
+					description: "File with URLs (one per line)"
+				},
+				"type": {
+					type: "string",
+					default: "URL_UPDATED",
+					description: "URL_UPDATED or URL_DELETED"
+				},
+				"delay-ms": {
+					type: "string",
+					default: "100",
+					description: "Delay between requests"
+				},
+				"concurrency": {
+					type: "string",
+					alias: "c",
+					default: "1",
+					description: "Concurrent in-flight requests"
+				},
+				"quiet": {
+					type: "boolean",
+					alias: "q",
+					default: false,
+					description: "Suppress progress output"
+				},
+				"json": {
+					type: "boolean",
+					default: false,
+					description: "Output as JSON"
+				},
+				"yes": {
+					type: "boolean",
+					alias: "y",
+					default: false,
+					description: "Skip the over-quota confirmation prompt"
+				},
+				"retries": {
+					type: "string",
+					description: "Override per-call retry count (default: 3)"
+				}
+			},
+			async run({ args }) {
+				setQuiet(Boolean(args.quiet) || Boolean(args.json));
+				const urls = await readUrlList$1(args);
+				if (urls.length === 0) {
+					logger.error("No URLs provided. Pass URLs as args, --file, or stdin.");
+					process.exit(1);
+				}
+				const type = String(args.type);
+				if (type !== "URL_UPDATED" && type !== "URL_DELETED") {
+					logger.error(`Invalid --type: ${type}. Use URL_UPDATED or URL_DELETED.`);
+					process.exit(1);
+				}
+				if (urls.length > INDEXING_DAILY_QUOTA && !args.yes && !args.json) {
+					logger.warn(`Submitting ${urls.length} URLs but the Indexing API daily quota is ${INDEXING_DAILY_QUOTA}/day.`);
+					logger.warn(`Excess submissions will fail with quota errors. Pass --yes to proceed anyway.`);
+					process.exit(1);
+				}
+				if (urls.length > INDEXING_DAILY_QUOTA && !args.json && !args.quiet) logger.warn(`Proceeding with ${urls.length} URLs (over the ${INDEXING_DAILY_QUOTA}/day quota). Excess will fail.`);
+				const ctx = await createCommandContext({
+					needsAuth: true,
+					fetchOptions: { retry: parseRetries(args.retries) }
+				});
+				const delayMs = Number.parseInt(String(args["delay-ms"]), 10);
+				const concurrency = Math.max(1, Number.parseInt(String(args.concurrency), 10) || 1);
+				if (!args.json && !args.quiet) logger.info(`Submitting ${urls.length} URLs (${type}) ...`);
+				const results = await batchRequestIndexing(ctx.client, urls, {
+					type,
+					delayMs,
+					concurrency,
+					onProgress: args.json || args.quiet ? void 0 : (r, i, total) => logger.info(`[${i + 1}/${total}] ${r.url}`)
+				}).catch(gscErrorHandler);
+				if (args.json) {
+					console.log(JSON.stringify(results, null, 2));
+					return;
+				}
+				if (!args.quiet) logger.success(`Submitted ${results.length}/${urls.length} URLs`);
+			}
+		})
+	}
+});
+const ENV_LINE_RE = /^([^=]+)=(.*)$/;
+async function promptDataDir(existing) {
+	const fallback = existing ?? defaultDataDir();
+	const answer = await text({
+		message: "Where should Parquet data be stored?",
+		placeholder: fallback,
+		defaultValue: fallback
+	});
+	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: {
+		name: "init",
+		description: "Set up GSCDump authentication"
+	},
+	args: {
+		"force": {
+			type: "boolean",
+			alias: "f",
+			description: "Force re-initialization"
+		},
+		"no-store": {
+			type: "boolean",
+			default: false,
+			description: "Skip dataDir prompt (auth-only setup)"
+		},
+		"quiet": {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info/success output"
+		}
+	},
+	async run({ args }) {
+		setQuiet(Boolean(args.quiet));
+		const config = await loadConfig();
+		if (config.clientId && config.clientSecret && !args.force) {
+			logger.info("Already configured");
+			logger.info("Run with --force to reconfigure");
+			return;
+		}
+		const byok = resolveBYOK();
+		if (byok) {
+			const dataDir = args["no-store"] ? void 0 : await promptDataDir(config.dataDir);
+			await saveConfig({
+				...config,
+				dataDir: dataDir ?? config.dataDir
+			});
+			logger.success(`BYOK detected (${typeof byok === "string" ? "access-token" : "refresh-token"}) — auth setup skipped`);
+			logger.success("Setup complete! Run gscdump to get started.");
+			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");
+			process.env.GOOGLE_CLIENT_ID = envCid;
+			process.env.GOOGLE_CLIENT_SECRET = envSec;
+			process.env.GOOGLE_REFRESH_TOKEN = envRef;
+			if (envAcc) process.env.GOOGLE_ACCESS_TOKEN = envAcc;
+			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
+			});
+			console.log();
+			logger.success("Setup complete using .env credentials! Run gscdump to get started.");
+			return;
+		}
+		console.log();
+		console.log("  \x1B[1mWelcome to GSCDump!\x1B[0m");
+		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
+		});
+		await smokeTest(await authenticate(credentials, true));
+		await maybeWriteEnvFile(credentials.clientId, credentials.clientSecret);
+		console.log();
+		logger.success("Setup complete! Run gscdump to get started.");
+	}
+});
+async function smokeTest(oauth) {
+	const sites = await googleSearchConsole(oauth).sites().catch((e) => e);
+	if (sites instanceof Error) {
+		logger.warn(`Smoke test failed: ${sites.message}`);
+		logger.info("Auth saved, but verify scopes via `gscdump auth status` / `gscdump doctor`.");
+		return;
+	}
+	logger.success(`Verified: ${sites.length} GSC site(s) accessible`);
+}
+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)}`);
+}
+function verdictTone(verdict) {
+	if (verdict === "PASS") return "\x1B[32m";
+	if (verdict === "NEUTRAL" || verdict === "PARTIAL") return "\x1B[33m";
+	if (verdict === "FAIL") return "\x1B[31m";
+	return "\x1B[90m";
+}
+function colorVerdict(verdict) {
+	return `${verdictTone(verdict)}${verdict || "N/A"}\x1B[0m`;
+}
+function printInspection(url, inspection) {
+	const indexStatus = inspection?.indexStatusResult;
+	console.log();
+	console.log(`  \x1B[1mURL:\x1B[0m ${url}`);
+	console.log();
+	console.log(`  \x1B[1mIndex status\x1B[0m`);
+	console.log(`    Verdict:        ${colorVerdict(indexStatus?.verdict)}`);
+	if (indexStatus?.coverageState) console.log(`    Coverage:       ${indexStatus.coverageState}`);
+	if (indexStatus?.indexingState) console.log(`    Indexing:       ${indexStatus.indexingState}`);
+	if (indexStatus?.lastCrawlTime) console.log(`    Last Crawl:     ${indexStatus.lastCrawlTime}`);
+	if (indexStatus?.crawledAs) console.log(`    Crawled As:     ${indexStatus.crawledAs}`);
+	if (indexStatus?.robotsTxtState) console.log(`    Robots.txt:     ${indexStatus.robotsTxtState}`);
+	if (indexStatus?.pageFetchState) console.log(`    Page Fetch:     ${indexStatus.pageFetchState}`);
+	if (indexStatus?.googleCanonical) console.log(`    Google Canon:   ${indexStatus.googleCanonical}`);
+	if (indexStatus?.userCanonical) console.log(`    User Canon:     ${indexStatus.userCanonical}`);
+	if (indexStatus?.sitemap?.length) {
+		console.log(`    Sitemaps:`);
+		for (const sm of indexStatus.sitemap) console.log(`      \x1B[90m└─\x1B[0m ${sm}`);
+	}
+	if (indexStatus?.referringUrls?.length) {
+		const shown = indexStatus.referringUrls.slice(0, 5);
+		console.log(`    Referring URLs (${indexStatus.referringUrls.length}):`);
+		for (const r of shown) console.log(`      \x1B[90m└─\x1B[0m ${r}`);
+		if (indexStatus.referringUrls.length > shown.length) console.log(`      \x1B[90m… ${indexStatus.referringUrls.length - shown.length} more\x1B[0m`);
+	}
+	const rich = inspection?.richResultsResult;
+	if (rich) {
+		console.log();
+		console.log(`  \x1B[1mRich results\x1B[0m`);
+		console.log(`    Verdict:        ${colorVerdict(rich.verdict)}`);
+		if (rich.detectedItems?.length) for (const group of rich.detectedItems) {
+			const count = group.items?.length ?? 0;
+			console.log(`    ${group.richResultType ?? "unknown"}: ${count} item${count === 1 ? "" : "s"}`);
+			for (const item of group.items ?? []) if (item.issues?.length) for (const issue of item.issues) {
+				const sev = issue.severity === "ERROR" ? "\x1B[31m" : "\x1B[33m";
+				console.log(`      ${sev}${issue.severity ?? "?"}\x1B[0m ${item.name ?? ""}: ${issue.issueMessage ?? ""}`);
+			}
+		}
+	}
+	const amp = inspection?.ampResult;
+	if (amp) {
+		console.log();
+		console.log(`  \x1B[1mAMP\x1B[0m`);
+		console.log(`    Verdict:        ${colorVerdict(amp.verdict)}`);
+		if (amp.ampUrl) console.log(`    AMP URL:        ${amp.ampUrl}`);
+		if (amp.ampIndexStatusVerdict) console.log(`    Index Verdict:  ${amp.ampIndexStatusVerdict}`);
+		if (amp.indexingState) console.log(`    Indexing:       ${amp.indexingState}`);
+		if (amp.robotsTxtState) console.log(`    Robots.txt:     ${amp.robotsTxtState}`);
+		if (amp.pageFetchState) console.log(`    Page Fetch:     ${amp.pageFetchState}`);
+		if (amp.lastCrawlTime) console.log(`    Last Crawl:     ${amp.lastCrawlTime}`);
+		if (amp.issues?.length) for (const issue of amp.issues) {
+			const sev = issue.severity === "ERROR" ? "\x1B[31m" : "\x1B[33m";
+			console.log(`    ${sev}${issue.severity ?? "?"}\x1B[0m ${issue.issueMessage ?? ""}`);
+		}
+	}
+	const mobile = inspection?.mobileUsabilityResult;
+	if (mobile) {
+		console.log();
+		console.log(`  \x1B[1mMobile usability\x1B[0m`);
+		console.log(`    Verdict:        ${colorVerdict(mobile.verdict)}`);
+		if (mobile.issues?.length) for (const issue of mobile.issues) console.log(`    \x1B[33m${issue.issueType ?? "?"}\x1B[0m ${issue.message ?? ""}`);
+	}
+	if (inspection?.inspectionResultLink) {
+		console.log();
+		console.log(`  \x1B[90mOpen in Search Console:\x1B[0m \x1B[36m${inspection.inspectionResultLink}\x1B[0m`);
+	}
+	console.log();
+}
+const inspectCommand = defineCommand({
+	meta: {
+		name: "inspect",
+		description: "Inspect URL indexing status (single URL; use `inspect batch` for many)"
+	},
+	args: {
+		site: {
+			type: "string",
+			alias: "s",
+			description: "Site URL (defaults to config.defaultSite or prompt)"
+		},
+		url: {
+			type: "positional",
+			required: true,
+			description: "URL to inspect"
+		},
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Output as JSON"
+		},
+		quiet: {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info/success output"
+		}
+	},
+	subCommands: { batch: defineCommand({
+		meta: {
+			name: "batch",
+			description: "Inspect many URLs from a file or stdin (one URL per line)"
+		},
+		args: {
+			"site": {
+				type: "string",
+				alias: "s",
+				description: "Site URL (defaults to config.defaultSite or prompt)"
+			},
+			"urls": {
+				type: "positional",
+				required: false,
+				description: "URLs (or use --file/stdin)"
+			},
+			"file": {
+				type: "string",
+				alias: "f",
+				description: "File with URLs (one per line)"
+			},
+			"delay-ms": {
+				type: "string",
+				default: "200",
+				description: "Delay between requests"
+			},
+			"concurrency": {
+				type: "string",
+				alias: "c",
+				default: "1",
+				description: "Concurrent in-flight requests"
+			},
+			"quiet": {
+				type: "boolean",
+				alias: "q",
+				default: false,
+				description: "Suppress progress output"
+			},
+			"json": {
+				type: "boolean",
+				default: false,
+				description: "Output as JSON"
+			}
+		},
+		async run({ args }) {
+			setQuiet(Boolean(args.quiet) || Boolean(args.json));
+			const urls = await readUrlList$1(args);
+			if (urls.length === 0) {
+				logger.error("No URLs provided. Pass URLs as args, --file, or stdin.");
+				process.exit(1);
+			}
+			const ctx = await createCommandContext({ needsAuth: true });
+			const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+			const delayMs = Number.parseInt(String(args["delay-ms"]), 10);
+			const concurrency = Math.max(1, Number.parseInt(String(args.concurrency), 10) || 1);
+			if (!args.json && !args.quiet) logger.info(`Inspecting ${urls.length} URLs ...`);
+			const results = await batchInspectUrls(ctx.client, siteUrl, urls, {
+				delayMs,
+				concurrency,
+				onProgress: args.json || args.quiet ? void 0 : (r, i, total) => logger.info(`[${i + 1}/${total}] ${r.url} ${r.isIndexed ? "PASS" : "FAIL"}`)
+			}).catch(gscErrorHandler);
+			if (args.json) {
+				console.log(JSON.stringify(results, null, 2));
+				return;
+			}
+			const indexed = results.filter((r) => r.isIndexed).length;
+			if (!args.quiet) logger.success(`Inspected ${results.length} URLs (${indexed} indexed, ${results.length - indexed} not)`);
+		}
+	}) },
+	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
+		const ctx = await createCommandContext({ needsAuth: true });
+		const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+		const result = await ctx.client.inspect(siteUrl, args.url).catch(gscErrorHandler);
+		const inspection = result?.inspectionResult;
+		const indexStatus = inspection?.indexStatusResult;
 		if (args.json) {
 			console.log(JSON.stringify({
 				url: args.url,
@@ -1476,23 +3062,11 @@ const inspectCommand = defineCommand({
 			}, null, 2));
 			return;
 		}
-		console.log();
-		console.log(`  \x1B[1mURL:\x1B[0m ${args.url}`);
-		console.log();
-		const verdictColor = indexStatus?.verdict === "PASS" ? "\x1B[32m" : "\x1B[31m";
-		console.log(`  Verdict:        ${verdictColor}${indexStatus?.verdict || "N/A"}\x1B[0m`);
-		if (indexStatus?.coverageState) console.log(`  Coverage:       ${indexStatus.coverageState}`);
-		if (indexStatus?.indexingState) console.log(`  Indexing:       ${indexStatus.indexingState}`);
-		if (indexStatus?.lastCrawlTime) console.log(`  Last Crawl:     ${indexStatus.lastCrawlTime}`);
-		if (indexStatus?.robotsTxtState) console.log(`  Robots.txt:     ${indexStatus.robotsTxtState}`);
-		if (indexStatus?.pageFetchState) console.log(`  Page Fetch:     ${indexStatus.pageFetchState}`);
-		if (indexStatus?.googleCanonical) console.log(`  Google Canon:   ${indexStatus.googleCanonical}`);
-		if (indexStatus?.userCanonical) console.log(`  User Canon:     ${indexStatus.userCanonical}`);
-		console.log();
+		printInspection(args.url, inspection);
 	}
 });
 async function checkAuth() {
-	if ((process.env.GOOGLE_ACCESS_TOKEN || process.env.GOOGLE_REFRESH_TOKEN) && process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) return { ok: true };
+	if (resolveBYOK()) return { ok: true };
 	const config = await loadConfig();
 	if (!config.clientId && !config.clientSecret) return {
 		ok: false,
@@ -1502,7 +3076,8 @@ Run this command to set up authentication:
 
   npx @gscdump/cli init
 
-Or provide env vars: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_ACCESS_TOKEN
+Or set BYOK env vars: GSC_ACCESS_TOKEN, or GSC_CLIENT_ID + GSC_CLIENT_SECRET + GSC_REFRESH_TOKEN
+(GOOGLE_* aliases also accepted).
 
 Then restart your MCP client.`
 	};
@@ -1512,7 +3087,7 @@ Then restart your MCP client.`
 
 Run this command to authenticate:
 
-  npx @gscdump/cli auth
+  npx @gscdump/cli auth login
 
 Then restart your MCP client.`
 	};
@@ -1546,23 +3121,78 @@ const DIMENSIONS = [
 	"device",
 	"searchAppearance"
 ];
-const DIM_COLUMNS = {
-	page,
+const DIM_COLUMNS = {
+	page,
+	query,
+	date,
+	country,
+	device,
+	searchAppearance
+};
+const FILTER_DIMS = [
+	"query",
+	"page",
+	"country",
+	"device",
+	"searchAppearance"
+];
+const FILTER_COL = {
 	query,
-	date,
+	page,
 	country,
 	device,
 	searchAppearance
 };
+const ALL_SEARCH_TYPES$1 = Object.values(SearchTypes);
+const DATA_STATES = [
+	"all",
+	"final",
+	"hourly_all"
+];
+const AGGREGATION_TYPES = [
+	"auto",
+	"byPage",
+	"byProperty"
+];
+function buildFilterFromArg(col, raw) {
+	if (raw.startsWith("!~")) return makeLeaf(col, "notContains", raw.slice(2));
+	if (raw.startsWith("!re:")) return notRegex(col, raw.slice(4));
+	if (raw.startsWith("!")) return makeLeaf(col, "notEquals", raw.slice(1));
+	if (raw.startsWith("~")) return contains(col, raw.slice(1));
+	if (raw.startsWith("re:")) return regex(col, raw.slice(3));
+	if (raw.startsWith("contains:")) return contains(col, raw.slice(9));
+	if (raw.startsWith("eq:")) return eq(col, raw.slice(3));
+	return eq(col, raw);
+}
+function makeLeaf(col, operator, value) {
+	return {
+		_constraints: {},
+		_filters: [{
+			dimension: col.dimension,
+			operator,
+			expression: value
+		}]
+	};
+}
 async function runLiveQuery(client, siteUrl, opts) {
 	const allRows = [];
 	let startRow = 0;
+	const baseBody = {
+		startDate: opts.startDate,
+		endDate: opts.endDate,
+		dimensions: opts.dimensions,
+		rowLimit: opts.rowLimit
+	};
+	if (opts.searchType) baseBody.searchType = opts.searchType;
+	if (opts.dataState) baseBody.dataState = opts.dataState;
+	if (opts.aggregationType) baseBody.aggregationType = opts.aggregationType;
+	if (opts.dimensionFilter) {
+		const groups = filterToGroups(opts.dimensionFilter);
+		if (groups.length > 0) baseBody.dimensionFilterGroups = groups;
+	}
 	while (true) {
 		const rows = ((await client._rawQuery(siteUrl, {
-			startDate: opts.startDate,
-			endDate: opts.endDate,
-			dimensions: opts.dimensions,
-			rowLimit: opts.rowLimit,
+			...baseBody,
 			startRow
 		})).rows || []).map((row) => {
 			const result = {
@@ -1582,71 +3212,116 @@ async function runLiveQuery(client, siteUrl, opts) {
 	}
 	return { rows: allRows };
 }
+function filterToGroups(f) {
+	if (f._filters.length === 0) return [];
+	return [{ filters: f._filters.map((leaf) => ({
+		dimension: leaf.dimension,
+		operator: leaf.operator,
+		expression: leaf.expression
+	})) }];
+}
 const queryCommand = defineCommand({
 	meta: {
 		name: "query",
 		description: "Run a search analytics query (local Parquet by default, --live hits GSC API)"
 	},
 	args: {
-		site: {
+		"site": {
 			type: "string",
 			alias: "s",
 			description: "Site URL (e.g., sc-domain:example.com)"
 		},
-		dimensions: {
+		"dimensions": {
 			type: "string",
 			alias: "d",
 			description: `Dimensions: ${DIMENSIONS.join(",")}`
 		},
-		start: {
+		"start": {
 			type: "string",
 			description: "Start date (YYYY-MM-DD)"
 		},
-		end: {
+		"end": {
 			type: "string",
 			description: "End date (YYYY-MM-DD)"
 		},
-		limit: {
+		"limit": {
 			type: "string",
 			alias: "l",
 			default: "1000",
 			description: "Max rows (default: 1000)"
 		},
-		output: {
+		"output": {
 			type: "string",
 			alias: "o",
 			description: "Output file path (default: stdout)"
 		},
-		format: {
+		"format": {
 			type: "string",
 			alias: "f",
 			default: "json",
 			description: "Output format: json or csv"
 		},
-		sql: {
+		"sql": {
 			type: "string",
 			description: "Raw DuckDB SQL using {{FILES}} as the file list placeholder (bypasses builder)"
 		},
-		table: {
+		"table": {
 			type: "string",
 			description: "Analytics table for --sql (default: pages)"
 		},
-		live: {
+		"live": {
 			type: "boolean",
 			default: false,
 			description: "Bypass local store; hit the GSC API directly"
 		},
-		quiet: {
+		"quiet": {
 			type: "boolean",
 			alias: "q",
 			default: false,
 			description: "Suppress progress output"
 		},
-		interactive: {
+		"interactive": {
 			type: "boolean",
 			alias: "i",
 			default: false,
 			description: "Interactive mode"
+		},
+		"query": {
+			type: "string",
+			description: "Filter by query (prefix: ~contains, !exclude, re:regex, !re:not-regex)"
+		},
+		"page": {
+			type: "string",
+			description: "Filter by page (same prefix syntax as --query)"
+		},
+		"country": {
+			type: "string",
+			description: "Filter by country (ISO-3 lowercase, e.g. usa). Same prefix syntax as --query"
+		},
+		"device": {
+			type: "string",
+			description: "Filter by device (DESKTOP/MOBILE/TABLET). Same prefix syntax"
+		},
+		"search-appearance": {
+			type: "string",
+			description: "Filter by search appearance feature. Same prefix syntax"
+		},
+		"type": {
+			type: "string",
+			description: `Search type (live mode only). One of: ${ALL_SEARCH_TYPES$1.join(",")}`
+		},
+		"data-state": {
+			type: "string",
+			description: `Data state (live mode only). One of: ${DATA_STATES.join(",")} (default: final)`
+		},
+		"aggregation-type": {
+			type: "string",
+			description: `Aggregation type (live mode only). One of: ${AGGREGATION_TYPES.join(",")}`
+		},
+		"explain": {
+			type: "boolean",
+			default: false,
+			description: "Print the request body / planned local SQL and exit without executing"
 		}
 	},
 	async run({ args }) {
@@ -1660,10 +3335,25 @@ const queryCommand = defineCommand({
 			});
 			return;
 		}
+		const ctxConfig = await loadConfig();
 		const dimNames = await resolveDimensions(args);
 		const { startDate, endDate } = await resolveRange(args);
-		const rowLimit = Number.parseInt(String(args.limit), 10);
+		await promptFilters(args);
+		const limitArg = args.limit != null ? String(args.limit) : null;
+		const rowLimit = limitArg != null && limitArg !== "1000" ? Number.parseInt(limitArg, 10) : ctxConfig.defaultLimit ?? 1e3;
 		const format = String(args.format);
+		const dimensionFilter = buildDimensionFilter(args);
+		const searchType = parseSearchType(args.type ?? ctxConfig.defaultSearchType);
+		const dataState = args["data-state"] ? String(args["data-state"]) : ctxConfig.defaultDataState;
+		const aggregationType = args["aggregation-type"] ? String(args["aggregation-type"]) : void 0;
+		if (dataState && !DATA_STATES.includes(dataState)) {
+			logger.error(`Invalid --data-state: ${dataState}. Allowed: ${DATA_STATES.join(", ")}`);
+			process.exit(1);
+		}
+		if (aggregationType && !AGGREGATION_TYPES.includes(aggregationType)) {
+			logger.error(`Invalid --aggregation-type: ${aggregationType}. Allowed: ${AGGREGATION_TYPES.join(", ")}`);
+			process.exit(1);
+		}
 		const ctx = await createCommandContext({
 			needsAuth: true,
 			needsStore: !args.live,
@@ -1671,16 +3361,34 @@ const queryCommand = defineCommand({
 		});
 		const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
 		if (args.live) {
+			if (args.explain) {
+				const body = {
+					startDate,
+					endDate,
+					dimensions: dimNames,
+					rowLimit
+				};
+				if (searchType) body.searchType = searchType;
+				if (dataState) body.dataState = dataState;
+				if (aggregationType) body.aggregationType = aggregationType;
+				if (dimensionFilter) body.dimensionFilterGroups = filterToGroups(dimensionFilter);
+				console.log(JSON.stringify({
+					siteUrl,
+					body
+				}, null, 2));
+				return;
+			}
 			if (!args.quiet) logger.info(`Querying ${siteUrl} via live GSC API...`);
 			const result = await runLiveQuery(ctx.client, siteUrl, {
 				startDate,
 				endDate,
 				dimensions: dimNames,
-				rowLimit
-			}).catch((e) => {
-				logger.error(`Query failed: ${e.message}`);
-				process.exit(1);
-			});
+				rowLimit,
+				searchType,
+				dataState,
+				aggregationType,
+				dimensionFilter
+			}).catch(gscErrorHandler);
 			await writeOutput({
 				output: {
 					siteUrl,
@@ -1698,10 +3406,23 @@ const queryCommand = defineCommand({
 			});
 			return;
 		}
+		if (searchType && searchType !== "web") {
+			logger.error(`--type=${searchType} requires --live (local store query path is web-only).`);
+			process.exit(1);
+		}
+		if (dataState || aggregationType) logger.warn("--data-state / --aggregation-type are ignored without --live");
 		if (!args.quiet) logger.info(`Querying ${siteUrl} from local Parquet store...`);
-		const state = buildLocalState(dimNames, startDate, endDate, rowLimit);
+		const state = buildLocalState(dimNames, startDate, endDate, rowLimit, dimensionFilter);
 		const store = ctx.store;
 		const table = inferTable(dimNames);
+		if (args.explain) {
+			console.log(JSON.stringify({
+				siteUrl,
+				table,
+				state
+			}, null, 2));
+			return;
+		}
 		await assertRangeCovered(store, siteUrl, table, startDate, endDate);
 		const result = await store.engine.query({
 			userId: store.userId,
@@ -1779,9 +3500,68 @@ async function resolveRange(args) {
 		endDate: daysAgo(3)
 	};
 }
-function buildLocalState(dimNames, startDate, endDate, rowLimit) {
+async function promptFilters(args) {
+	if (!args.interactive) return;
+	for (const dim of FILTER_DIMS) {
+		if (args[dim]) continue;
+		const v = await text({
+			message: `Filter by ${dim} (blank to skip; prefix ~ for contains, ! for not-equals, re: for regex)`,
+			placeholder: ""
+		});
+		if (isCancel(v)) {
+			cancel("Cancelled");
+			process.exit(0);
+		}
+		if (v && String(v).length > 0) args[dim] = String(v);
+	}
+	if (!args.type) {
+		const t = await text({
+			message: `Search type (blank for default web; allowed: ${ALL_SEARCH_TYPES$1.join(", ")})`,
+			placeholder: ""
+		});
+		if (isCancel(t)) {
+			cancel("Cancelled");
+			process.exit(0);
+		}
+		if (t && String(t).length > 0) args.type = String(t);
+	}
+	if (!args["data-state"]) {
+		const ds = await text({
+			message: `Data state (blank for default 'final'; allowed: ${DATA_STATES.join(", ")})`,
+			placeholder: ""
+		});
+		if (isCancel(ds)) {
+			cancel("Cancelled");
+			process.exit(0);
+		}
+		if (ds && String(ds).length > 0) args["data-state"] = String(ds);
+	}
+}
+function buildLocalState(dimNames, startDate, endDate, rowLimit, dimensionFilter) {
 	const dims = dimNames.map((d) => DIM_COLUMNS[d]).filter((c) => Boolean(c));
-	return gsc.select(...dims).where(between(date, startDate, endDate)).limit(rowLimit).getState();
+	const dateFilter = between(date, startDate, endDate);
+	const filter = dimensionFilter ? and(dateFilter, dimensionFilter) : dateFilter;
+	return gsc.select(...dims).where(filter).limit(rowLimit).getState();
+}
+function buildDimensionFilter(args) {
+	const leaves = [];
+	for (const dim of FILTER_DIMS) {
+		const raw = args[dim];
+		if (raw == null || raw === "") continue;
+		leaves.push(buildFilterFromArg(FILTER_COL[dim], String(raw)));
+	}
+	if (leaves.length === 0) return void 0;
+	if (leaves.length === 1) return leaves[0];
+	return and(...leaves);
+}
+function parseSearchType(value) {
+	if (!value) return void 0;
+	const v = String(value);
+	if (!ALL_SEARCH_TYPES$1.includes(v)) {
+		logger.error(`Invalid --type: ${v}. Allowed: ${ALL_SEARCH_TYPES$1.join(", ")}`);
+		process.exit(1);
+	}
+	return v;
 }
 async function assertRangeCovered(store, siteUrl, table, startDate, endDate) {
 	const wm = (await store.engine.getWatermarks({
@@ -1827,14 +3607,14 @@ async function runRawSqlMode(opts) {
 		total: rows.length,
 		data: rows
 	}, null, 2);
-	if (opts.output) {
+	if (opts.output && opts.output !== "-") {
 		await fs.writeFile(opts.output, payload);
 		if (!opts.quiet) logger.info(`Written to ${opts.output}`);
 	} else console.log(payload);
 }
 async function writeOutput(opts) {
 	const content = opts.format === "csv" ? exportToCSV(opts.output) : JSON.stringify(opts.output, null, 2);
-	if (opts.path) {
+	if (opts.path && opts.path !== "-") {
 		await fs.writeFile(opts.path, content);
 		if (!opts.quiet) logger.info(`Written to ${opts.path}`);
 	} else console.log(content);
@@ -1842,13 +3622,6 @@ async function writeOutput(opts) {
 function isKnownTable$1(name) {
 	return allTables().includes(name);
 }
-function requireSite(target) {
-	if (!target) {
-		logger.error("Site URL required (-s)");
-		process.exit(1);
-	}
-	return target;
-}
 const sitemapsCommand = defineCommand({
 	meta: {
 		name: "sitemaps",
@@ -1870,160 +3643,480 @@ const sitemapsCommand = defineCommand({
 					type: "boolean",
 					default: false,
 					description: "Output as JSON"
+				},
+				pending: {
+					type: "boolean",
+					default: false,
+					description: "Show only sitemaps with isPending=true"
+				},
+				errored: {
+					type: "boolean",
+					default: false,
+					description: "Show only sitemaps with errors > 0"
+				}
+			},
+			async run({ args }) {
+				const ctx = await createCommandContext({ needsAuth: true });
+				const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+				let sitemaps = (await ctx.client.sitemaps.list(siteUrl).catch((e) => {
+					logger.error(`Failed to fetch sitemaps: ${e.message}`);
+					process.exit(1);
+				})).map((sm) => ({
+					path: sm.path,
+					type: sm.type || void 0,
+					isPending: sm.isPending || false,
+					errors: Number(sm.errors) || 0,
+					warnings: Number(sm.warnings) || 0,
+					lastDownloaded: sm.lastDownloaded || null,
+					lastSubmitted: sm.lastSubmitted || null
+				}));
+				if (args.pending) sitemaps = sitemaps.filter((sm) => sm.isPending);
+				if (args.errored) sitemaps = sitemaps.filter((sm) => sm.errors > 0);
+				if (args.json) {
+					console.log(JSON.stringify(sitemaps, null, 2));
+					return;
+				}
+				if (sitemaps.length === 0) {
+					logger.warn("No sitemaps found");
+					return;
+				}
+				logger.success(`Found ${sitemaps.length} 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 submitted = sm.lastSubmitted ? ` \x1B[90msubmitted ${sm.lastSubmitted}\x1B[0m` : "";
+					console.log(`  ${sm.path}${pending}${errors}${warnings}${submitted}`);
+				}
+			}
+		}),
+		get: defineCommand({
+			meta: {
+				name: "get",
+				description: "Get details for a specific sitemap"
+			},
+			args: {
+				site: {
+					type: "string",
+					alias: "s",
+					description: "Site URL (defaults to config.defaultSite or prompt)"
+				},
+				url: {
+					type: "positional",
+					required: true,
+					description: "Sitemap URL"
+				},
+				json: {
+					type: "boolean",
+					default: false,
+					description: "Output as JSON"
+				}
+			},
+			async run({ args }) {
+				const ctx = await createCommandContext({ needsAuth: true });
+				const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+				const client = ctx.client;
+				const sitemap = await fetchSitemap(client, siteUrl, args.url).catch(gscErrorHandler);
+				if (args.json) {
+					console.log(JSON.stringify(sitemap, null, 2));
+					return;
+				}
+				console.log();
+				console.log(`  \x1B[1mPath:\x1B[0m ${sitemap.path}`);
+				console.log(`  \x1B[1mType:\x1B[0m ${sitemap.type || "sitemap"}`);
+				console.log(`  \x1B[1mLast Submitted:\x1B[0m ${sitemap.lastSubmitted || "N/A"}`);
+				console.log(`  \x1B[1mLast Downloaded:\x1B[0m ${sitemap.lastDownloaded || "N/A"}`);
+				console.log(`  \x1B[1mPending:\x1B[0m ${sitemap.isPending ? "Yes" : "No"}`);
+				console.log(`  \x1B[1mErrors:\x1B[0m ${sitemap.errors || 0}`);
+				console.log(`  \x1B[1mWarnings:\x1B[0m ${sitemap.warnings || 0}`);
+				if (sitemap.contents?.length) {
+					console.log();
+					console.log("  \x1B[1mContents:\x1B[0m");
+					for (const c of sitemap.contents) console.log(`    ${c.type}: ${c.submitted} submitted, ${c.indexed} indexed`);
+				}
+			}
+		}),
+		submit: defineCommand({
+			meta: {
+				name: "submit",
+				description: "Submit a sitemap to GSC"
+			},
+			args: {
+				site: {
+					type: "string",
+					alias: "s",
+					description: "Site URL (defaults to config.defaultSite or prompt)"
+				},
+				url: {
+					type: "positional",
+					required: true,
+					description: "Sitemap URL to submit"
+				}
+			},
+			async run({ args }) {
+				const ctx = await createCommandContext({ needsAuth: true });
+				const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+				await ctx.client.sitemaps.submit(siteUrl, args.url).catch((e) => {
+					logger.error(`Submit failed: ${e.message}`);
+					process.exit(1);
+				});
+				logger.success(`Submitted sitemap: ${args.url}`);
+			}
+		}),
+		delete: defineCommand({
+			meta: {
+				name: "delete",
+				description: "Delete a sitemap from GSC"
+			},
+			args: {
+				site: {
+					type: "string",
+					alias: "s",
+					description: "Site URL (defaults to config.defaultSite or prompt)"
+				},
+				url: {
+					type: "positional",
+					required: true,
+					description: "Sitemap URL to delete"
+				}
+			},
+			async run({ args }) {
+				const ctx = await createCommandContext({ needsAuth: true });
+				const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+				await ctx.client.sitemaps.delete(siteUrl, args.url).catch((e) => {
+					logger.error(`Delete failed: ${e.message}`);
+					process.exit(1);
+				});
+				logger.success(`Deleted sitemap: ${args.url}`);
+			}
+		})
+	}
+});
+const ALL_METHODS = [
+	"META",
+	"FILE",
+	"DNS_TXT",
+	"DNS_CNAME",
+	"ANALYTICS",
+	"TAG_MANAGER"
+];
+function pickDefaultMethod(siteUrl) {
+	return siteUrl.startsWith("sc-domain:") ? "DNS_TXT" : "META";
+}
+function validateMethod(siteUrl, method) {
+	const upper = method.toUpperCase();
+	if (!ALL_METHODS.includes(upper)) {
+		logger.error(`Invalid --method: ${method}. Valid: ${ALL_METHODS.join(", ")}`);
+		process.exit(1);
+	}
+	const site = siteUrlToVerificationSite(siteUrl);
+	const allowed = verificationMethodsFor(site);
+	if (!allowed.includes(upper)) {
+		logger.error(`Method ${upper} not valid for ${site.type === "INET_DOMAIN" ? "domain" : "URL-prefix"} property "${siteUrl}". Valid: ${allowed.join(", ")}`);
+		process.exit(1);
+	}
+	return upper;
+}
+function printPlacementInstructions(method, siteUrl, token) {
+	console.log();
+	console.log(`  \x1B[1mPlacement instructions (${method})\x1B[0m`);
+	console.log();
+	switch (method) {
+		case "META":
+			console.log(`  Add this tag inside the <head> of \x1B[36m${siteUrl}\x1B[0m:`);
+			console.log();
+			console.log(`    \x1B[2m<meta name="google-site-verification" content="${token}" />\x1B[0m`);
+			break;
+		case "FILE":
+			console.log(`  Upload a file named \x1B[1m${token}\x1B[0m to the site root, accessible at:`);
+			console.log();
+			console.log(`    \x1B[36m${siteUrl.replace(/\/?$/, "/")}${token}\x1B[0m`);
+			break;
+		case "DNS_TXT":
+			console.log(`  Add a TXT record on \x1B[1m${siteUrl.replace(/^sc-domain:/, "")}\x1B[0m with value:`);
+			console.log();
+			console.log(`    \x1B[2m${token}\x1B[0m`);
+			break;
+		case "DNS_CNAME": {
+			const [host, target] = token.split(/\s+/, 2);
+			console.log(`  Add a CNAME record:`);
+			console.log();
+			console.log(`    \x1B[2mHost:   ${host}\x1B[0m`);
+			console.log(`    \x1B[2mTarget: ${target ?? "(see token)"}\x1B[0m`);
+			break;
+		}
+		case "ANALYTICS":
+			console.log(`  Make sure your Google Analytics tracking tag is installed on the site, then run \`gscdump sites verify\`.`);
+			break;
+		case "TAG_MANAGER":
+			console.log(`  Make sure your Google Tag Manager container snippet is installed on the site, then run \`gscdump sites verify\`.`);
+			break;
+	}
+	console.log();
+	console.log(`  \x1B[90mThen run:\x1B[0m gscdump sites verify ${siteUrl} --method ${method}`);
+	console.log();
+}
+const sitesCommand = defineCommand({
+	meta: {
+		name: "sites",
+		description: "List GSC sites; manage properties (add/delete) and verify ownership"
+	},
+	args: {
+		"json": {
+			type: "boolean",
+			default: false,
+			description: "Output as JSON for scripting"
+		},
+		"with-sitemaps": {
+			type: "boolean",
+			default: false,
+			description: "Include sitemaps for each owned site"
+		},
+		"owner-only": {
+			type: "boolean",
+			default: false,
+			description: "Filter to permissionLevel=siteOwner"
+		},
+		"quiet": {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info/success output"
+		}
+	},
+	subCommands: {
+		"add": defineCommand({
+			meta: {
+				name: "add",
+				description: "Register a property in Search Console (unverified state — verify ownership separately)"
+			},
+			args: {
+				url: {
+					type: "positional",
+					required: true,
+					description: "Property URL (https://example.com/ or sc-domain:example.com)"
+				},
+				json: {
+					type: "boolean",
+					default: false,
+					description: "Output as JSON"
+				},
+				quiet: {
+					type: "boolean",
+					alias: "q",
+					default: false,
+					description: "Suppress info/success output"
 				}
 			},
 			async run({ args }) {
-				const config = await loadConfig();
-				const siteUrl = requireSite(args.site || config.defaultSite);
-				const sitemaps = (await (await createCommandContext({ needsAuth: true })).client.sitemaps.list(siteUrl).catch((e) => {
-					logger.error(`Failed to fetch sitemaps: ${e.message}`);
-					process.exit(1);
-				})).map((sm) => ({
-					path: sm.path,
-					type: sm.type || void 0,
-					isPending: sm.isPending || false,
-					errors: Number(sm.errors) || 0,
-					warnings: Number(sm.warnings) || 0,
-					lastDownloaded: sm.lastDownloaded || null
-				}));
+				setQuiet(Boolean(args.quiet) || Boolean(args.json));
+				await addSite((await createCommandContext({ needsAuth: true })).client, args.url).catch(gscErrorHandler);
 				if (args.json) {
-					console.log(JSON.stringify(sitemaps, null, 2));
-					return;
-				}
-				if (sitemaps.length === 0) {
-					logger.warn("No sitemaps found");
+					console.log(JSON.stringify({
+						siteUrl: args.url,
+						status: "added",
+						verified: false
+					}, null, 2));
 					return;
 				}
-				logger.success(`Found ${sitemaps.length} 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` : "";
-					console.log(`  ${sm.path}${pending}${errors}${warnings}`);
-				}
+				logger.success(`Added: ${args.url}`);
+				logger.info(`Property is in unverified state. Verify ownership next:`);
+				const method = pickDefaultMethod(args.url);
+				console.log(`    \x1B[2mgscdump sites verify-token ${args.url} --method ${method}\x1B[0m`);
 			}
 		}),
-		get: defineCommand({
+		"delete": defineCommand({
 			meta: {
-				name: "get",
-				description: "Get details for a specific sitemap"
+				name: "delete",
+				description: "Remove a property from Search Console"
 			},
 			args: {
-				site: {
-					type: "string",
-					alias: "s",
-					required: true,
-					description: "Site URL"
-				},
 				url: {
 					type: "positional",
 					required: true,
-					description: "Sitemap URL"
+					description: "Property URL to remove"
+				},
+				yes: {
+					type: "boolean",
+					alias: "y",
+					default: false,
+					description: "Skip confirmation prompt"
 				},
 				json: {
 					type: "boolean",
 					default: false,
 					description: "Output as JSON"
+				},
+				quiet: {
+					type: "boolean",
+					alias: "q",
+					default: false,
+					description: "Suppress info/success output"
 				}
 			},
 			async run({ args }) {
-				const client = (await createCommandContext({ needsAuth: true })).client;
-				const sitemap = await fetchSitemap(client, args.site, args.url).catch(gscErrorHandler);
+				setQuiet(Boolean(args.quiet) || Boolean(args.json));
+				if (!args.yes && !args.json) {
+					const ok = await confirm({
+						message: `Remove ${args.url} from Search Console? Local synced data is unaffected.`,
+						initialValue: false
+					});
+					if (isCancel(ok) || !ok) {
+						logger.info("Cancelled");
+						process.exit(0);
+					}
+				}
+				await deleteSite((await createCommandContext({ needsAuth: true })).client, args.url).catch(gscErrorHandler);
 				if (args.json) {
-					console.log(JSON.stringify(sitemap, null, 2));
+					console.log(JSON.stringify({
+						siteUrl: args.url,
+						status: "deleted"
+					}, null, 2));
 					return;
 				}
-				console.log();
-				console.log(`  \x1B[1mPath:\x1B[0m ${sitemap.path}`);
-				console.log(`  \x1B[1mType:\x1B[0m ${sitemap.type || "sitemap"}`);
-				console.log(`  \x1B[1mLast Submitted:\x1B[0m ${sitemap.lastSubmitted || "N/A"}`);
-				console.log(`  \x1B[1mLast Downloaded:\x1B[0m ${sitemap.lastDownloaded || "N/A"}`);
-				console.log(`  \x1B[1mPending:\x1B[0m ${sitemap.isPending ? "Yes" : "No"}`);
-				console.log(`  \x1B[1mErrors:\x1B[0m ${sitemap.errors || 0}`);
-				console.log(`  \x1B[1mWarnings:\x1B[0m ${sitemap.warnings || 0}`);
-				if (sitemap.contents?.length) {
-					console.log();
-					console.log("  \x1B[1mContents:\x1B[0m");
-					for (const c of sitemap.contents) console.log(`    ${c.type}: ${c.submitted} submitted, ${c.indexed} indexed`);
-				}
+				logger.success(`Removed: ${args.url}`);
 			}
 		}),
-		submit: defineCommand({
+		"verify-token": defineCommand({
 			meta: {
-				name: "submit",
-				description: "Submit a sitemap to GSC"
+				name: "verify-token",
+				description: "Get a verification token to place on the site or in DNS"
 			},
 			args: {
-				site: {
-					type: "string",
-					alias: "s",
-					required: true,
-					description: "Site URL"
-				},
 				url: {
 					type: "positional",
 					required: true,
-					description: "Sitemap URL to submit"
+					description: "Property URL"
+				},
+				method: {
+					type: "string",
+					alias: "m",
+					description: "META, FILE, DNS_TXT, DNS_CNAME, ANALYTICS, TAG_MANAGER (default: META for URL-prefix, DNS_TXT for sc-domain:)"
+				},
+				json: {
+					type: "boolean",
+					default: false,
+					description: "Output as JSON"
+				},
+				quiet: {
+					type: "boolean",
+					alias: "q",
+					default: false,
+					description: "Suppress info/success output"
 				}
 			},
 			async run({ args }) {
-				await (await createCommandContext({ needsAuth: true })).client.sitemaps.submit(args.site, args.url).catch((e) => {
-					logger.error(`Submit failed: ${e.message}`);
-					process.exit(1);
-				});
-				logger.success(`Submitted sitemap: ${args.url}`);
+				setQuiet(Boolean(args.quiet) || Boolean(args.json));
+				const method = validateMethod(args.url, args.method ?? pickDefaultMethod(args.url));
+				const result = await getVerificationToken((await createCommandContext({ needsAuth: true })).client, args.url, method).catch(gscErrorHandler);
+				if (args.json) {
+					console.log(JSON.stringify({
+						siteUrl: args.url,
+						method,
+						token: result.token,
+						site: result.site
+					}, null, 2));
+					return;
+				}
+				printPlacementInstructions(method, args.url, result.token);
 			}
 		}),
-		delete: defineCommand({
+		"verify": defineCommand({
 			meta: {
-				name: "delete",
-				description: "Delete a sitemap from GSC"
+				name: "verify",
+				description: "Trigger verification — Google fetches/validates the token you placed"
 			},
 			args: {
-				site: {
-					type: "string",
-					alias: "s",
-					required: true,
-					description: "Site URL"
-				},
 				url: {
 					type: "positional",
 					required: true,
-					description: "Sitemap URL to delete"
+					description: "Property URL"
+				},
+				method: {
+					type: "string",
+					alias: "m",
+					description: "Verification method to validate (must match the one used for verify-token)"
+				},
+				json: {
+					type: "boolean",
+					default: false,
+					description: "Output as JSON"
+				},
+				quiet: {
+					type: "boolean",
+					alias: "q",
+					default: false,
+					description: "Suppress info/success output"
 				}
 			},
 			async run({ args }) {
-				await (await createCommandContext({ needsAuth: true })).client.sitemaps.delete(args.site, args.url).catch((e) => {
-					logger.error(`Delete failed: ${e.message}`);
-					process.exit(1);
-				});
-				logger.success(`Deleted sitemap: ${args.url}`);
+				setQuiet(Boolean(args.quiet) || Boolean(args.json));
+				const method = validateMethod(args.url, args.method ?? pickDefaultMethod(args.url));
+				const resource = await verifySite((await createCommandContext({ needsAuth: true })).client, args.url, method).catch(gscErrorHandler);
+				if (args.json) {
+					console.log(JSON.stringify({
+						siteUrl: args.url,
+						method,
+						resource
+					}, null, 2));
+					return;
+				}
+				logger.success(`Verified: ${args.url}`);
+				if (resource.owners?.length) {
+					console.log();
+					console.log(`  Owners:`);
+					for (const o of resource.owners) console.log(`    \x1B[90m└─\x1B[0m ${o}`);
+				}
 			}
 		})
-	}
-});
-const sitesCommand = defineCommand({
-	meta: {
-		name: "sites",
-		description: "List available GSC sites"
 	},
-	args: { json: {
-		type: "boolean",
-		default: false,
-		description: "Output as JSON for scripting"
-	} },
 	async run({ args }) {
-		const sites = await (await createCommandContext({ needsAuth: true })).loadSites();
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
+		const ctx = await createCommandContext({ needsAuth: true });
+		const ownerOnly = Boolean(args["owner-only"]);
+		if (args["with-sitemaps"]) {
+			const all = await fetchSitesWithSitemaps(ctx.client).catch(gscErrorHandler);
+			const sites = ownerOnly ? all.filter((s) => s.permissionLevel === "siteOwner") : all;
+			if (args.json) {
+				const enriched = sites.map((s) => ({
+					...s,
+					sitemapCounts: {
+						total: s.sitemaps.length,
+						pending: s.sitemaps.filter((sm) => sm.isPending).length,
+						errored: s.sitemaps.filter((sm) => Number(sm.errors) > 0).length
+					}
+				}));
+				console.log(JSON.stringify(enriched, null, 2));
+				return;
+			}
+			if (sites.length === 0) {
+				logger.warn(ownerOnly ? "No owned sites found" : "No verified sites found");
+				return;
+			}
+			logger.success(`Found ${sites.length} ${ownerOnly ? "owned" : "verified"} sites:`);
+			console.log();
+			for (const site of sites) {
+				const perm = site.permissionLevel === "siteOwner" ? "\x1B[32m" : "\x1B[90m";
+				console.log(`  ${site.siteUrl} ${perm}(${site.permissionLevel})\x1B[0m`);
+				for (const sm of site.sitemaps) {
+					const pending = sm.isPending ? " \x1B[33m(pending)\x1B[0m" : "";
+					console.log(`    \x1B[90m└─\x1B[0m ${sm.path}${pending}`);
+				}
+			}
+			return;
+		}
+		const all = await ctx.loadSites();
+		const sites = ownerOnly ? all.filter((s) => s.permissionLevel === "siteOwner") : all;
 		if (args.json) {
 			console.log(JSON.stringify(sites, null, 2));
 			return;
 		}
 		if (sites.length === 0) {
-			logger.warn("No verified sites found");
+			logger.warn(ownerOnly ? "No owned sites found" : "No verified sites found");
 			return;
 		}
-		logger.success(`Found ${sites.length} sites:`);
+		logger.success(`Found ${sites.length} ${ownerOnly ? "owned " : ""}sites:`);
 		console.log();
 		for (const site of sites) {
 			const perm = site.permissionLevel === "siteOwner" ? "\x1B[32m" : "\x1B[90m";
@@ -2054,6 +4147,16 @@ const compactCommand = defineCommand({
 			type: "string",
 			description: "Override d30→d90 age threshold in days (default: 90)"
 		},
+		"dry-run": {
+			type: "boolean",
+			default: false,
+			description: "Report tier counts per (table, site) without compacting"
+		},
+		"json": {
+			type: "boolean",
+			default: false,
+			description: "Output a JSON summary"
+		},
 		"quiet": {
 			type: "boolean",
 			alias: "q",
@@ -2062,13 +4165,43 @@ const compactCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
 		const store = (await createCommandContext({ needsStore: true })).store;
 		const siteId = args.site ? store.siteIdFor(String(args.site)) : void 0;
-		const quiet = Boolean(args.quiet);
+		const dryRun = Boolean(args["dry-run"]);
 		const thresholds = {};
 		if (args["raw-days"]) thresholds.raw = Number(args["raw-days"]);
 		if (args["d7-days"]) thresholds.d7 = Number(args["d7-days"]);
 		if (args["d30-days"]) thresholds.d30 = Number(args["d30-days"]);
+		if (dryRun) {
+			const report = [];
+			for (const table of allTables()) {
+				const bySite = groupBySite(await store.engine.listLive({
+					userId: store.userId,
+					siteId,
+					table
+				}));
+				for (const [s, group] of bySite) report.push({
+					table,
+					siteId: s,
+					...countByTier(group)
+				});
+			}
+			if (args.json) {
+				console.log(JSON.stringify({
+					thresholds,
+					plan: report
+				}, null, 2));
+				return;
+			}
+			console.log();
+			console.log(`  table                site                 raw    d7   d30   d90`);
+			for (const r of report) console.log(`  ${r.table.padEnd(20)} ${(r.siteId ?? "-").padEnd(20)} ${String(r.raw).padStart(4)}  ${String(r.d7).padStart(4)}  ${String(r.d30).padStart(4)}  ${String(r.d90).padStart(4)}`);
+			console.log();
+			logger.info(`compact --dry-run: ${report.length} (table, site) pair(s) — pass without --dry-run to apply`);
+			return;
+		}
+		const summary = [];
 		for (const table of allTables()) {
 			const entries = await store.engine.listLive({
 				userId: store.userId,
@@ -2077,17 +4210,56 @@ const compactCommand = defineCommand({
 			});
 			const siteIds = new Set(entries.map((e) => e.siteId));
 			for (const targetSite of siteIds) {
-				if (!quiet) logger.info(`Compacting ${table} [${targetSite ?? "-"}] (raw→d7→d30→d90)`);
+				logger.info(`Compacting ${table} [${targetSite ?? "-"}] (raw→d7→d30→d90)`);
 				await store.engine.compactTiered({
 					userId: store.userId,
 					siteId: targetSite,
 					table
 				}, thresholds);
+				summary.push({
+					table,
+					siteId: targetSite
+				});
 			}
 		}
-		if (!quiet) logger.success(`compact: done`);
+		if (args.json) {
+			console.log(JSON.stringify({
+				thresholds,
+				compacted: summary
+			}, null, 2));
+			return;
+		}
+		logger.success(`compact: done`);
 	}
 });
+function groupBySite(entries) {
+	const m = /* @__PURE__ */ new Map();
+	for (const e of entries) {
+		const arr = m.get(e.siteId) ?? [];
+		arr.push(e);
+		m.set(e.siteId, arr);
+	}
+	return m;
+}
+function countByTier(entries) {
+	let raw = 0;
+	let d7 = 0;
+	let d30 = 0;
+	let d90 = 0;
+	for (const e of entries) {
+		const tier = e.tier ?? inferLegacyTier(e) ?? "raw";
+		if (tier === "raw") raw++;
+		else if (tier === "d7") d7++;
+		else if (tier === "d30") d30++;
+		else if (tier === "d90") d90++;
+	}
+	return {
+		raw,
+		d7,
+		d30,
+		d90
+	};
+}
 async function exportToDuckDB(opts) {
 	const outPath = path.resolve(opts.outPath);
 	if (opts.force) await rm(outPath, { force: true });
@@ -2141,9 +4313,21 @@ const exportCommand = defineCommand({
 			type: "boolean",
 			default: false,
 			description: "Overwrite the output file if it already exists"
+		},
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Output a JSON summary instead of formatted text"
+		},
+		quiet: {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info/success output"
 		}
 	},
 	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
 		const store = (await createCommandContext({ needsStore: true })).store;
 		const siteId = args.site ? store.siteIdFor(args.site) : void 0;
 		const result = await exportToDuckDB({
@@ -2154,12 +4338,16 @@ const exportCommand = defineCommand({
 			outPath: args.out,
 			force: args.force
 		});
+		if (args.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
 		if (result.tables.length === 0) {
 			console.log(`\n  No data to export. Run \`gscdump sync\` first.`);
 			return;
 		}
 		for (const t of result.tables) console.log(`  ${t.table.padEnd(15)} ${String(t.files).padStart(4)} parquet → ${t.table}  (${t.rows.toLocaleString()} rows)`);
-		console.log(`\n  Exported ${result.tables.length} table(s), ${result.totalRows.toLocaleString()} rows → ${result.outPath}`);
+		console.log(`\n  Exported ${result.tables.length} table(s), ${result.totalRows.toLocaleString()} rows → ${displayPath(result.outPath)}`);
 		console.log(`\n  Attach from DuckDB:     \x1B[36mATTACH '${result.outPath}' AS gsc (READ_ONLY); SELECT * FROM gsc.pages LIMIT 10;\x1B[0m`);
 		console.log(`  Attach in a browser:    use DuckDB-WASM registerFileBuffer + \x1B[36mATTACH 'gsc.duckdb' AS gsc (READ_ONLY)\x1B[0m`);
 	}
@@ -2181,6 +4369,16 @@ const gcCommand = defineCommand({
 			alias: "s",
 			description: "Restrict to a single site (default: all sites)"
 		},
+		"dry-run": {
+			type: "boolean",
+			default: false,
+			description: "List retired manifest entries past the grace window without deleting"
+		},
+		"json": {
+			type: "boolean",
+			default: false,
+			description: "Output a JSON summary"
+		},
 		"quiet": {
 			type: "boolean",
 			alias: "q",
@@ -2189,15 +4387,52 @@ const gcCommand = defineCommand({
 		}
 	},
 	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
 		const store = (await createCommandContext({ needsStore: true })).store;
 		const siteId = args.site ? store.siteIdFor(String(args.site)) : void 0;
-		const quiet = Boolean(args.quiet);
 		const graceMs = Number(args["grace-hours"]) * 36e5;
+		if (args["dry-run"]) {
+			const cutoff = Date.now() - graceMs;
+			const candidates = [];
+			for (const table of allTables()) {
+				const all = await store.engine.listAll({
+					userId: store.userId,
+					siteId,
+					table
+				});
+				for (const e of all) if (e.retiredAt && e.retiredAt < cutoff) candidates.push({
+					table,
+					siteId: e.siteId,
+					partition: e.partition,
+					retiredAt: e.retiredAt,
+					objectKey: e.objectKey
+				});
+			}
+			if (args.json) {
+				console.log(JSON.stringify({
+					graceHours: Number(args["grace-hours"]),
+					candidates
+				}, null, 2));
+				return;
+			}
+			console.log();
+			for (const c of candidates) console.log(`  ${c.objectKey}  \x1B[90m(retired ${new Date(c.retiredAt).toISOString()})\x1B[0m`);
+			console.log();
+			logger.info(`gc --dry-run: ${candidates.length} retired manifest entry(ies) past ${args["grace-hours"]}h grace; pass without --dry-run to delete`);
+			return;
+		}
 		const result = await store.engine.gcOrphans({
 			userId: store.userId,
 			siteId
 		}, graceMs);
-		if (!quiet) logger.success(`gc: deleted ${result.deleted} orphan file(s)`);
+		if (args.json) {
+			console.log(JSON.stringify({
+				graceHours: Number(args["grace-hours"]),
+				deleted: result.deleted
+			}, null, 2));
+			return;
+		}
+		logger.success(`gc: deleted ${result.deleted} orphan file(s)`);
 	}
 });
 const rollupsCommand = defineCommand({
@@ -2216,6 +4451,11 @@ const rollupsCommand = defineCommand({
 				alias: "s",
 				description: "Restrict to a single site (default: all sites with local data)"
 			},
+			json: {
+				type: "boolean",
+				default: false,
+				description: "Output a JSON summary"
+			},
 			quiet: {
 				type: "boolean",
 				alias: "q",
@@ -2224,9 +4464,9 @@ const rollupsCommand = defineCommand({
 			}
 		},
 		async run({ args }) {
+			setQuiet(Boolean(args.quiet) || Boolean(args.json));
 			const store = (await createCommandContext({ needsStore: true })).store;
 			const explicitSiteId = args.site ? store.siteIdFor(String(args.site)) : void 0;
-			const quiet = Boolean(args.quiet);
 			const allSiteIds = /* @__PURE__ */ new Set();
 			if (explicitSiteId) allSiteIds.add(explicitSiteId);
 			else for (const table of allTables()) {
@@ -2237,12 +4477,17 @@ const rollupsCommand = defineCommand({
 				for (const e of entries) if (e.siteId) allSiteIds.add(e.siteId);
 			}
 			if (allSiteIds.size === 0) {
-				logger.warn("No sites with local data. Run `gscdump sync` first.");
+				if (args.json) console.log(JSON.stringify({
+					sites: [],
+					totalBytes: 0
+				}, null, 2));
+				else logger.warn("No sites with local data. Run `gscdump sync` first.");
 				return;
 			}
+			const summary = [];
 			let totalBytes = 0;
 			for (const siteId of allSiteIds) {
-				if (!quiet) logger.info(`Rebuilding rollups for [${siteId}] (${DEFAULT_ROLLUPS.length} rollups)`);
+				logger.info(`Rebuilding rollups for [${siteId}] (${DEFAULT_ROLLUPS.length} rollups)`);
 				const results = await rebuildRollups({
 					engine: store.engine,
 					dataSource: store.dataSource,
@@ -2252,12 +4497,29 @@ const rollupsCommand = defineCommand({
 					},
 					defs: DEFAULT_ROLLUPS
 				});
+				const site = {
+					siteId,
+					rollups: []
+				};
 				for (const r of results) {
 					totalBytes += r.bytes;
-					if (!quiet) console.log(`  ${r.id.padEnd(20)} ${(r.bytes / 1024).toFixed(1).padStart(8)} KB  ${r.objectKey}`);
+					site.rollups.push({
+						id: r.id,
+						bytes: r.bytes,
+						objectKey: r.objectKey
+					});
+					if (!args.json) console.log(`  ${r.id.padEnd(20)} ${(r.bytes / 1024).toFixed(1).padStart(8)} KB  ${r.objectKey}`);
 				}
+				summary.push(site);
+			}
+			if (args.json) {
+				console.log(JSON.stringify({
+					sites: summary,
+					totalBytes
+				}, null, 2));
+				return;
 			}
-			if (!quiet) logger.success(`Rebuilt rollups across ${allSiteIds.size} site(s) — total ${(totalBytes / 1024).toFixed(1)} KB`);
+			logger.success(`Rebuilt rollups across ${allSiteIds.size} site(s) — total ${(totalBytes / 1024).toFixed(1)} KB`);
 		}
 	}) }
 });
@@ -2275,11 +4537,27 @@ const statsCommand = defineCommand({
 		site: {
 			type: "string",
 			description: "Limit to one site URL (sc-domain:example.com, https://example.com/, ...)"
+		},
+		quiet: {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info/success output"
 		}
 	},
 	async run({ args }) {
+		setQuiet(Boolean(args.quiet) || Boolean(args.json));
 		const store = (await createCommandContext({ needsStore: true })).store;
-		const siteId = args.site ? store.siteIdFor(args.site) : void 0;
+		let siteId;
+		if (args.site) {
+			const known = await listKnownSiteIds(store);
+			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 perTable = await Promise.all(allTables().map(async (table) => {
 			const all = await store.engine.listAll({
 				userId: store.userId,
@@ -2323,7 +4601,7 @@ const statsCommand = defineCommand({
 			return;
 		}
 		console.log();
-		console.log(`  \x1B[1m${store.dataDir}\x1B[0m`);
+		console.log(`  \x1B[1m${displayPath(store.dataDir)}\x1B[0m`);
 		console.log(`  \x1B[90mDisk: ${disk.files} file(s), ${formatBytes(disk.bytes)}\x1B[0m`);
 		console.log();
 		const totalRows = perTable.reduce((acc, t) => acc + sumRows(t.live), 0);
@@ -2351,6 +4629,17 @@ const statsCommand = defineCommand({
 		console.log();
 	}
 });
+async function listKnownSiteIds(store) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const table of allTables()) {
+		const entries = await store.engine.listLive({
+			userId: store.userId,
+			table
+		});
+		for (const e of entries) if (e.siteId) ids.add(e.siteId);
+	}
+	return ids;
+}
 function sortWatermarks(ws) {
 	return [...ws].sort((a, b) => {
 		if (a.table !== b.table) return a.table.localeCompare(b.table);
@@ -2585,6 +4874,16 @@ const syncCommand = defineCommand({
 			type: "boolean",
 			default: false,
 			description: "Run tables sequentially (default: run all tables in parallel)"
+		},
+		"retry-failed": {
+			type: "boolean",
+			default: false,
+			description: "Only re-run dates currently in `failed` state (cheaper than --force)"
+		},
+		"dry-run": {
+			type: "boolean",
+			default: false,
+			description: "Print the planned (table, searchType, date) work and exit without hitting the API"
 		}
 	},
 	async run({ args }) {
@@ -2631,14 +4930,63 @@ const syncCommand = defineCommand({
 		else if (args.full) startDate = daysAgo(450);
 		else if (args.days) startDate = daysAgo(Number.parseInt(String(args.days), 10) + DEFAULT_PENDING_DAYS - 1);
 		else startDate = daysAgo(DEFAULT_PENDING_DAYS + DEFAULT_PENDING_DAYS - 1);
-		const dates = getDateRange(startDate, endDate);
+		let dates = getDateRange(startDate, endDate);
 		if (dates.length === 0) {
 			logger.error(`No dates to sync (start=${startDate}, end=${endDate})`);
 			process.exit(1);
 		}
 		const store = ctx.store;
+		if (args["retry-failed"]) {
+			const failedSet = /* @__PURE__ */ new Set();
+			for (const table of tables) for (const type of types) {
+				const states = await store.engine.getSyncStates({
+					userId: store.userId,
+					siteId,
+					table,
+					searchType: type
+				});
+				for (const s of states) if (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.");
+				return;
+			}
+			args.force = true;
+			if (!args.quiet) logger.info(`--retry-failed: ${dates.length} date(s) to retry`);
+		}
+		if (args["dry-run"]) {
+			const plan = [];
+			for (const table of tables) for (const type of types) for (const date of dates) plan.push({
+				table,
+				searchType: type,
+				date
+			});
+			if (args.json) {
+				console.log(JSON.stringify({
+					siteUrl,
+					range: {
+						start: startDate,
+						end: endDate
+					},
+					tables,
+					types,
+					totalCalls: plan.length,
+					plan
+				}, null, 2));
+				return;
+			}
+			console.log();
+			logger.info(`Plan: ${plan.length} API call(s) for ${siteUrl}`);
+			console.log(`  Tables:   ${tables.join(", ")}`);
+			console.log(`  Types:    ${types.join(", ")}`);
+			console.log(`  Range:    ${startDate} → ${endDate} (${dates.length} days)`);
+			console.log();
+			logger.info("Pass without --dry-run to execute.");
+			return;
+		}
 		if (!args.quiet) {
-			logger.info(`Syncing ${siteUrl} (${tables.join(", ")}) [${types.join(", ")}] → ${store.dataDir}`);
+			logger.info(`Syncing ${siteUrl} (${tables.join(", ")}) [${types.join(", ")}] → ${displayPath(store.dataDir)}`);
 			logger.info(`Range: ${startDate} → ${endDate} (${dates.length} days)`);
 		}
 		const concurrency = args.concurrency ? Math.max(1, Number.parseInt(String(args.concurrency), 10) || DEFAULT_CONCURRENCY) : DEFAULT_CONCURRENCY;
@@ -2763,7 +5111,7 @@ async function printSyncStatus(config, siteFilter, asJson) {
 		return;
 	}
 	console.log();
-	console.log(`  \x1B[1m${store.dataDir}\x1B[0m`);
+	console.log(`  \x1B[1m${displayPath(store.dataDir)}\x1B[0m`);
 	if (siteFilter) console.log(`  \x1B[90mSite: ${siteFilter}\x1B[0m`);
 	console.log();
 	if (watermarks.length === 0) {
@@ -2794,6 +5142,51 @@ async function printSyncStatus(config, siteFilter, asJson) {
 	}
 	console.log();
 }
+function shouldShowSplash() {
+	if (!process.stdout.isTTY) return false;
+	const argv = process.argv;
+	if (argv.includes("mcp")) return false;
+	for (const flag of [
+		"--json",
+		"--quiet",
+		"-q",
+		"--version",
+		"-v",
+		"--help",
+		"-h"
+	]) if (argv.includes(flag)) return false;
+	return true;
+}
+function applyGlobalArgs() {
+	const argv = process.argv;
+	if (argv.includes("--no-color") || process.env.NO_COLOR) setNoColor(true);
+	const profile = pluckArgValue(argv, "--profile") ?? process.env.GSCDUMP_PROFILE;
+	const configDir = pluckArgValue(argv, "--config-dir") ?? process.env.GSCDUMP_CONFIG_DIR;
+	if (configDir) setConfigDir(configDir);
+	else if (profile) setConfigDir(path.join(os.homedir(), ".config", "gscdump", "profiles", profile));
+	if (argv.includes("-v") && !argv.includes("--version")) {
+		const i = argv.indexOf("-v");
+		argv[i] = "--version";
+	}
+}
+function pluckArgValue(argv, flag) {
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === flag && i + 1 < argv.length) {
+			const v = argv[i + 1];
+			argv.splice(i, 2);
+			return v;
+		}
+		if (a.startsWith(`${flag}=`)) {
+			const v = a.slice(flag.length + 1);
+			argv.splice(i, 1);
+			return v;
+		}
+	}
+	return null;
+}
+applyGlobalArgs();
+loadEnvFromCwd();
 runMain(defineCommand({
 	meta: {
 		name: "gscdump",
@@ -2809,14 +5202,16 @@ runMain(defineCommand({
 		sync: syncCommand,
 		store: storeCommand,
 		inspect: inspectCommand,
+		indexing: indexingCommand,
 		entities: entitiesCommand,
 		analyze: analyzeCommand,
 		auth: authCommand,
 		config: configCommand,
+		doctor: doctorCommand,
 		mcp: mcpCommand
 	},
 	setup() {
-		if (!process.argv.includes("mcp")) showSplash();
+		if (shouldShowSplash()) showSplash();
 	}
 }));
 export {};