@gscdump/cli 4.2.3 → 4.3.0

package/dist/commands/auth.mjs

@@ -1,23 +1,23 @@
 import { authCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
-import { clearAuthentication, formatHostedSync, getCloudAccount, getCloudSites, parseAuthMode, parseAuthentication, resolveAuthentication, revokeCloudSession, saveAuthentication } from "../auth-state.mjs";
+import { clearAuthentication, formatHostedSync, getHostedAccount, parseAuthMode, parseAuthentication, resolveAuthentication, revokeHostedSession, saveAuthentication } from "../auth-state.mjs";
 import { loadConfig, saveConfig } from "../config.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
-import { loginWithCloudSession } from "../hosted-auth.mjs";
-import { GOOGLE_NOT_CONNECTED, clearTokens, formatAuthProvenance, getAuth, loadServiceAccount, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
+import { ACCESS_NOT_SET_UP, clearTokens, formatAuthProvenance, getAuth, loadServiceAccount, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
 import { missingRequiredScopes } from "../auth-scopes.mjs";
 import { clearBingCredentials, getBingClient, inspectBingCredentials } from "../bing-auth.mjs";
+import { loginWithHostedSession } from "../hosted-auth.mjs";
 import { currentAccessToken, fetchTokenInfo, redactTokens } from "../token-info.mjs";
 import { runSmokeTest } from "./init.mjs";
 import { adoptCurrentConfigAsProfile, profileNameFromEmail, resolveActiveProfile } from "./profile.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import path from "node:path";
-import { setTimeout } from "node:timers/promises";
 import open from "open";
+import { setTimeout } from "node:timers/promises";
 const MODE_ARG = {
 	type: "string",
-	description: "Authentication mode: cloud or local"
+	description: "Access mode: local or hosted"
 };
 function applyAuthMode(args) {
 	const mode = parseAuthMode(args.mode);
@@ -25,45 +25,62 @@ function applyAuthMode(args) {
 }
 async function requireLocalAuth(args) {
 	applyAuthMode(args);
-	if ((await resolveAuthentication())._tag === "Cloud") throw new Error("Cloud authentication uses a CLI session. Google OAuth scopes and token refresh require --mode local.");
+	if ((await resolveAuthentication())._tag === "Hosted") throw new Error("Google scopes and token refresh apply to Local mode only. Hosted mode uses a gscdump.com CLI session.");
 }
-async function loginCloud(args) {
+const HOSTED_MODE_NOTE = "Hosted mode reads your gscdump.com record. Commands that call Google need Local mode.";
+const HOSTED_COMMANDS = [
+	"sites",
+	"query",
+	"sitemaps current",
+	"sitemaps history",
+	"sitemaps membership",
+	"sitemaps lastmod",
+	"sitemaps export",
+	"indexing urls",
+	"bing login",
+	"bing sites",
+	"bing status",
+	"bing dump",
+	"bing inspect",
+	"bing verify"
+];
+async function loginHosted(args) {
 	const env = useCliRuntime().environment;
 	const apiKey = String(args["api-key"] ?? env.GSCDUMP_API_KEY ?? "");
 	const apiRoot = String(args["api-root"] ?? env.GSCDUMP_API_ROOT ?? "https://gscdump.com/api");
 	if (!apiKey) {
 		if (apiRoot.replace(/\/+$/, "") !== "https://gscdump.com/api") throw new Error("Browser login uses gscdump.com. Supply --api-key for a custom API root.");
-		const sessionId = await loginWithCloudSession({
+		const sessionId = await loginWithHostedSession({
 			request: fetch,
 			now: Date.now,
 			wait: setTimeout,
 			authorize: async (url) => {
-				logger.info(`Open this URL to connect cloud access:\n${url}`);
+				logger.info(`Open this URL to link the CLI to gscdump.com:\n${url}`);
 				if (args.browser !== false) await open(url).catch((error) => logger.warn(`Browser could not open: ${error.message}. Open the URL above.`));
 			}
 		});
 		const state = parseAuthentication({
-			_tag: "Cloud",
+			_tag: "Hosted",
 			apiRoot,
 			sessionId
 		});
-		if (state._tag !== "Cloud") throw new Error("Cloud login did not return a CLI session.");
-		const account = await getCloudAccount(state);
+		if (state._tag !== "Hosted") throw new Error("Hosted login did not return a CLI session.");
+		const account = await getHostedAccount(state);
 		await saveAuthentication(state);
-		logger.success(`Cloud authentication saved for ${account.user.email}`);
-		logger.info("Google and Bing commands use connections saved on gscdump.com.");
+		logger.success(`Hosted mode saved for ${account.user.email}`);
+		logger.info(HOSTED_MODE_NOTE);
 		return;
 	}
 	const state = parseAuthentication({
-		_tag: "Cloud",
+		_tag: "Hosted",
 		apiKey,
 		apiRoot
 	});
-	if (state._tag !== "Cloud") throw new Error("Cloud login requires a gscdump user API key.");
-	const account = await getCloudAccount(state);
+	if (state._tag !== "Hosted") throw new Error("Hosted login needs a gscdump user API key.");
+	const account = await getHostedAccount(state);
 	await saveAuthentication(state);
-	logger.success(`Cloud authentication saved for ${account.user.email}`);
-	logger.info("Google and Bing commands use connections saved on gscdump.com.");
+	logger.success(`Hosted mode saved for ${account.user.email}`);
+	logger.info(HOSTED_MODE_NOTE);
 }
 async function resolveLiveAuthState() {
 	const tokens = await loadTokens();
@@ -78,7 +95,7 @@ async function resolveLiveAuthState() {
 	const tokenInfo = verified?.kind === "valid" ? verified.info : null;
 	const failure = current?.kind === "failed" ? current.detail : verified?.kind === "invalid" ? verified.detail : null;
 	const scopes = tokenInfo?.scope ? tokenInfo.scope.split(/\s+/).filter(Boolean) : [];
-	const missing = missingRequiredScopes(scopes, byok ? void 0 : tokens?.provider);
+	const missing = missingRequiredScopes(scopes);
 	return {
 		byok,
 		tokens: tokens && !byok ? await loadTokens() : tokens,
@@ -93,86 +110,54 @@ async function runStatus(args) {
 	const { json } = applyOutputMode(args);
 	applyAuthMode(args);
 	const authentication = await resolveAuthentication();
-	if (authentication._tag === "Cloud") {
-		const capabilities = {
-			google: [
-				"sites",
-				"query",
-				"sync",
-				"inspect",
-				"sitemaps",
-				"analyze",
-				"report"
-			],
-			bing: [
-				"sites",
-				"dump",
-				"inspect",
-				"login",
-				"status",
-				"verify"
-			],
-			cloud: [
-				"sitemaps current",
-				"sitemaps history",
-				"sitemaps membership",
-				"sitemaps lastmod",
-				"sitemaps export"
-			],
-			local: ["indexing", "sites verification"]
-		};
-		const account = await getCloudAccount(authentication).then((value) => ({
+	if (authentication._tag === "Hosted") {
+		const account = await getHostedAccount(authentication).then((value) => ({
 			_tag: "Ok",
 			value
 		}), (error) => ({
 			_tag: "Err",
-			detail: error instanceof Error ? error.message : "Hosted authentication failed."
+			detail: error instanceof Error ? error.message : "Hosted credentials failed."
 		}));
 		if (account._tag === "Err") {
 			if (json) console.log(JSON.stringify({
 				authenticated: false,
-				mode: "cloud",
+				mode: "hosted",
 				apiRoot: authentication.apiRoot,
 				error: account.detail
 			}, null, 2));
 			else {
-				logger.warn(`Cloud status check failed: ${account.detail}`);
+				logger.warn(`Hosted status check failed: ${account.detail}`);
 				logger.info(`API: ${authentication.apiRoot}`);
 				logger.info("Fix connectivity or the API key, then run `gscdump auth status` again.");
 			}
 			return;
 		}
-		const hosted = await getCloudSites(authentication).then((sites) => ({
-			_tag: "Ok",
-			sites: sites.filter((site) => site.registered)
-		}), (error) => ({
-			_tag: "Err",
-			detail: error instanceof Error ? error.message : "Hosted Site list failed."
-		}));
+		const sites = account.value.sites;
 		if (json) console.log(JSON.stringify({
 			authenticated: true,
-			mode: "cloud",
+			mode: "hosted",
 			account: account.value.user.email,
 			apiRoot: authentication.apiRoot,
-			sites: account.value.sites,
-			...hosted._tag === "Ok" ? { hostedSync: hosted.sites.map((site) => ({
+			sites: sites.map((site) => ({
+				siteId: site.siteId,
+				siteUrl: site.siteUrl
+			})),
+			hostedSync: sites.map((site) => ({
 				siteUrl: site.siteUrl,
 				syncStatus: site.syncStatus ?? null,
 				syncProgress: site.syncProgress ?? null,
 				oldestDateSynced: site.oldestDateSynced ?? null,
 				newestDateSynced: site.newestDateSynced ?? null
-			})) } : { hostedSyncError: hosted.detail },
-			capabilities
+			})),
+			commands: HOSTED_COMMANDS
 		}, null, 2));
 		else {
-			logger.success(`Authenticated with cloud: ${account.value.user.email}`);
+			logger.success(`Hosted mode: ${account.value.user.email}`);
 			console.log(`  API: ${authentication.apiRoot}`);
-			console.log(`  Sites: ${account.value.sites.length}`);
-			if (hosted._tag === "Ok") for (const site of hosted.sites) console.log(`    ${site.siteUrl}  ${formatHostedSync(site)}`);
-			else console.log(`  Hosted sync status is not available: ${hosted.detail}`);
-			console.log("  Google and Bing use connections saved on gscdump.com.");
-			console.log(`  Cloud commands: ${capabilities.cloud.join(", ")}`);
-			console.log("  Google indexing and Site Verification require --mode local.");
+			console.log(`  Sites: ${sites.length}`);
+			for (const site of sites) console.log(`    ${site.siteUrl}  ${formatHostedSync(site)}`);
+			console.log(`  ${HOSTED_MODE_NOTE}`);
+			console.log(`  Hosted commands: ${HOSTED_COMMANDS.join(", ")}`);
 		}
 		return;
 	}
@@ -193,8 +178,8 @@ async function runStatus(args) {
 			googleAuthenticated,
 			googleError: failure,
 			bing,
-			source: byok ? "byok" : tokens ? "saved-tokens" : null,
-			byokKind,
+			source: byok ? "env" : tokens ? "saved-tokens" : null,
+			envCredential: byokKind,
 			scopes,
 			tokenAccount: tokenInfo?.email ?? null,
 			tokens: tokens ? {
@@ -219,8 +204,8 @@ async function runStatus(args) {
 		}
 	};
 	if (byok) {
-		if (googleAuthenticated) logger.success(`Authenticated via BYOK (${byokKind})`);
-		else logger.warn(`BYOK credentials (${byokKind}) failed verification: ${failure}`);
+		if (googleAuthenticated) logger.success(`Authenticated with environment credentials (${byokKind})`);
+		else logger.warn(`Environment credentials (${byokKind}) failed verification: ${failure}`);
 		if (tokenInfo?.email) console.log(`  Account:       ${tokenInfo.email}`);
 		reportScopes();
 		return;
@@ -230,7 +215,7 @@ async function runStatus(args) {
 			logger.info("Google credentials are missing. Run `gscdump auth login --mode local` to connect Google.");
 			return;
 		}
-		logger.warn(GOOGLE_NOT_CONNECTED);
+		logger.warn(ACCESS_NOT_SET_UP);
 		return;
 	}
 	const hasAccess = !!tokens.access_token;
@@ -262,7 +247,7 @@ const statusCommand = defineCommand({
 const refreshCommand = defineCommand({
 	meta: {
 		name: "refresh",
-		description: "Force-refresh saved OAuth tokens (no-op for BYOK)"
+		description: "Force-refresh saved OAuth tokens (no-op for environment credentials)"
 	},
 	args: {
 		...OUTPUT_ARGS,
@@ -272,7 +257,7 @@ const refreshCommand = defineCommand({
 		applyOutputMode(args);
 		await requireLocalAuth(args);
 		if (resolveBYOK()) {
-			logger.info("BYOK detected; refresh handled per-call by the SDK");
+			logger.info("Environment credentials found. The SDK refreshes them for each call.");
 			return;
 		}
 		const tokens = await loadTokens();
@@ -298,11 +283,11 @@ const loginCommand = defineCommand({
 		"mode": MODE_ARG,
 		"api-key": {
 			type: "string",
-			description: "gscdump user API key; defaults to GSCDUMP_API_KEY"
+			description: "gscdump user API key for Hosted mode; defaults to GSCDUMP_API_KEY"
 		},
 		"api-root": {
 			type: "string",
-			description: "Cloud API root; defaults to GSCDUMP_API_ROOT or https://gscdump.com/api"
+			description: "Hosted API root; defaults to GSCDUMP_API_ROOT or https://gscdump.com/api"
 		},
 		"force": {
 			type: "boolean",
@@ -324,13 +309,13 @@ const loginCommand = defineCommand({
 		applyOutputMode(args);
 		const runtime = useCliRuntime();
 		const requestedMode = parseAuthMode(args.mode) ?? runtime.authModeOverride ?? parseAuthMode(runtime.environment.GSCDUMP_AUTH_MODE);
-		if (requestedMode === "cloud" || !requestedMode && (args["api-key"] || (await resolveAuthentication())._tag === "Cloud")) {
-			await loginCloud(args);
+		if (requestedMode === "hosted" || !requestedMode && (args["api-key"] || (await resolveAuthentication())._tag === "Hosted")) {
+			await loginHosted(args);
 			return;
 		}
 		if (resolveBYOK() && !args.force) {
 			await saveAuthentication({ _tag: "Local" });
-			logger.info("BYOK env vars detected, no login needed (--force to override)");
+			logger.info("Google credentials found in the environment. No login is needed. Pass --force to log in again.");
 			return;
 		}
 		if (args["service-account"]) {
@@ -385,9 +370,9 @@ const logoutCommand = defineCommand({
 	args: { ...OUTPUT_ARGS },
 	async run({ args }) {
 		applyOutputMode(args);
-		await resolveAuthentication().then((authentication) => authentication._tag === "Cloud" ? revokeCloudSession(authentication) : void 0).catch((error) => {
+		await resolveAuthentication().then((authentication) => authentication._tag === "Hosted" ? revokeHostedSession(authentication) : void 0).catch((error) => {
 			const message = error instanceof Error ? error.message : String(error);
-			logger.warn(`Cloud session revocation failed (${message}). Local credentials are still cleared.`);
+			logger.warn(`Hosted session revocation failed (${message}). Saved credentials are still cleared.`);
 		});
 		await clearTokens();
 		await clearBingCredentials();
@@ -446,4 +431,4 @@ const authCommand = defineCommand({
 		await runStatus(args);
 	}
 });
-export { authCommand, loginCloud, loginCommand, logoutCommand, statusCommand };
+export { HOSTED_COMMANDS, authCommand, loginCommand, loginHosted, logoutCommand, statusCommand };

package/dist/commands/bing.mjs

@@ -56,8 +56,8 @@ const bingCommand = defineCommand({
 				const { json } = applyOutputMode(args);
 				const env = useCliRuntime().environment;
 				const authentication = await resolveAuthentication();
-				if (authentication._tag === "Cloud") {
-					if (args.oauth || args["api-key"] || args["client-id"] || args["client-secret"] || args["redirect-uri"]) throw new Error("Local Bing credentials require --mode local. Hosted login uses `gscdump auth login --mode cloud`.");
+				if (authentication._tag === "Hosted") {
+					if (args.oauth || args["api-key"] || args["client-id"] || args["client-secret"] || args["redirect-uri"]) throw new Error("Local Bing credentials need Local mode. Pass --mode local. Hosted mode uses the Bing connection saved on gscdump.com.");
 					if (!args.site) throw new Error("Choose --site SITE_ID from `gscdump bing sites` to connect Bing.");
 					const [site] = await resolveHostedBingSites(authentication, {
 						site: args.site,
@@ -128,7 +128,7 @@ const bingCommand = defineCommand({
 			args: OUTPUT_ARGS,
 			async run({ args }) {
 				const { json } = applyOutputMode(args);
-				if ((await resolveAuthentication())._tag === "Cloud") throw new Error("Hosted authentication is shared with Google. Use `gscdump auth logout` to remove it.");
+				if ((await resolveAuthentication())._tag === "Hosted") throw new Error("Hosted authentication is shared with Google. Use `gscdump auth logout` to remove it.");
 				await clearBingCredentials();
 				const env = useCliRuntime().environment;
 				const environmentCredentials = Boolean(env.BING_API_KEY?.trim() || env.BING_ACCESS_TOKEN?.trim());
@@ -152,14 +152,14 @@ const bingCommand = defineCommand({
 			async run({ args }) {
 				const { json } = applyOutputMode(args);
 				const authentication = await resolveAuthentication();
-				if (authentication._tag === "Cloud") {
+				if (authentication._tag === "Hosted") {
 					const sites = args.site ? await resolveHostedBingSites(authentication, {
 						site: args.site,
 						requireConnected: false
 					}) : await listHostedBingSites(authentication);
 					console.log(JSON.stringify({
 						searchEngine: "bing",
-						mode: "cloud",
+						mode: "hosted",
 						sites
 					}, null, 2));
 					return;
@@ -183,7 +183,7 @@ const bingCommand = defineCommand({
 			async run({ args }) {
 				applyOutputMode(args);
 				const authentication = await resolveAuthentication();
-				if (authentication._tag === "Cloud") {
+				if (authentication._tag === "Hosted") {
 					console.log(JSON.stringify({
 						searchEngine: "bing",
 						sites: await listHostedBingSites(authentication)
@@ -223,7 +223,7 @@ const bingCommand = defineCommand({
 				},
 				"datasets": {
 					type: "string",
-					description: `Comma-separated datasets: ${BING_DATASETS.join(", ")}. Default: all. Crawl issues have no dates, so --start, --end, and cloud mode leave them out`
+					description: `Comma-separated datasets: ${BING_DATASETS.join(", ")}. Default: all. Crawl issues have no dates, so --start, --end, and Hosted mode leave them out`
 				},
 				"start": {
 					type: "string",
@@ -239,7 +239,7 @@ const bingCommand = defineCommand({
 				const { json } = applyOutputMode(args);
 				const options = parseBingDumpOptions(args);
 				const authentication = await resolveAuthentication();
-				if (authentication._tag === "Cloud") {
+				if (authentication._tag === "Hosted") {
 					if (options.datasetsExplicit && options.datasets.includes("crawl-issues")) throw new Error("Bing crawl issues require local authentication. Use --mode local.");
 					if (options.start && options.end && Date.parse(options.end) - Date.parse(options.start) > 316224e5) throw new Error("Hosted Bing exports support at most 366 days. Use a shorter --start and --end range.");
 					const sites = await resolveHostedBingSites(authentication, {
@@ -297,7 +297,7 @@ const bingCommand = defineCommand({
 				const url = URL.parse(args.url);
 				if (!url || !["http:", "https:"].includes(url.protocol)) throw new Error("Use a full HTTP or HTTPS page URL.");
 				const authentication = await resolveAuthentication();
-				if (authentication._tag === "Cloud") {
+				if (authentication._tag === "Hosted") {
 					const [site] = await resolveHostedBingSites(authentication, { site: args.site });
 					console.log(JSON.stringify(await inspectHostedBingUrl(authentication, site.siteId, args.url), null, 2));
 					return;
@@ -323,7 +323,7 @@ const bingCommand = defineCommand({
 			async run({ args }) {
 				applyOutputMode(args);
 				const authentication = await resolveAuthentication();
-				if (authentication._tag !== "Cloud") throw new Error("Hosted Bing connection verification requires --mode cloud.");
+				if (authentication._tag !== "Hosted") throw new Error("Hosted Bing connection verification needs Hosted mode. Pass --mode hosted.");
 				const [site] = await resolveHostedBingSites(authentication, {
 					site: args.site,
 					requireConnected: false

package/dist/commands/doctor.mjs

@@ -1,10 +1,10 @@
 import { doctorCommandMeta } from "../command-meta.mjs";
-import { getCloudAccount, resolveAuthentication } from "../auth-state.mjs";
+import { getHostedAccount, resolveAuthentication } from "../auth-state.mjs";
 import { loadConfig } from "../config.mjs";
 import { resolveCliEnvironment } from "../environment.mjs";
 import { parseEnvFile } from "../env-file.mjs";
 import { OUTPUT_ARGS, applyOutputMode, displayPath, logger } from "../utils.mjs";
-import { getAuth, loadTokens, resolveAuth, resolveBYOK } from "../auth.mjs";
+import { getAuth, isStaleServiceAccountPointer, loadTokens, resolveAuth, resolveBYOK, resolveServiceAccount } from "../auth.mjs";
 import { createLocalStore } from "../local-store.mjs";
 import { createCommandContext, formatSiteResolution } from "../context.mjs";
 import { missingRequiredScopes } from "../auth-scopes.mjs";
@@ -76,17 +76,62 @@ function describeAuthSource(envKeys, byok) {
 	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}`;
+	return `environment credentials ${isAccessToken ? "(access-token)" : "(refresh-token)"} from ${source} via ${driver}`;
 }
 async function checkAuth(envKeys) {
 	const checks = [];
+	const serviceAccount = await resolveServiceAccount().catch((error) => {
+		if (isStaleServiceAccountPointer(error)) {
+			checks.push({
+				name: "auth.service_account",
+				status: "warn",
+				detail: `ignored: ${error instanceof Error ? error.message : String(error)}`
+			});
+			return null;
+		}
+		return error instanceof Error ? error : new Error(String(error));
+	});
+	if (serviceAccount instanceof Error) {
+		checks.push({
+			name: "auth",
+			status: "fail",
+			detail: `service account: ${serviceAccount.message}`
+		});
+		return {
+			checks,
+			liveToken: null
+		};
+	}
+	if (serviceAccount) {
+		const token = await serviceAccount.getAccessToken().then((result) => result.token ?? null, (error) => error instanceof Error ? error : new Error(String(error)));
+		if (!token || token instanceof Error) {
+			checks.push({
+				name: "auth",
+				status: "fail",
+				detail: `service account ${serviceAccount.email}: ${token instanceof Error ? redactTokens(token.message) : "no access token"}`
+			});
+			return {
+				checks,
+				liveToken: null
+			};
+		}
+		checks.push({
+			name: "auth",
+			status: "pass",
+			detail: `service account ${serviceAccount.email}`
+		});
+		return {
+			checks,
+			liveToken: token
+		};
+	}
 	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`"
+			detail: "no Google credentials: no service account, no environment tokens, no saved tokens. Run `gscdump init`, or `gscdump auth login --mode hosted` for Hosted mode"
 		});
 		return {
 			checks,
@@ -140,7 +185,7 @@ async function checkAuth(envKeys) {
 		detail: info.email
 	});
 	const scopes = info.scope ? info.scope.split(/\s+/) : [];
-	const missing = missingRequiredScopes(scopes, byok ? void 0 : tokens?.provider);
+	const missing = missingRequiredScopes(scopes);
 	if (missing.length > 0) checks.push({
 		name: "auth.scopes",
 		status: "warn",
@@ -324,8 +369,8 @@ function describeGscSites(sites, defaultSite) {
 	}
 	return checks;
 }
-async function checkCloudConnection(authentication) {
-	const account = await getCloudAccount(authentication).then((value) => ({
+async function checkHostedConnection(authentication) {
+	const account = await getHostedAccount(authentication).then((value) => ({
 		_tag: "Ok",
 		value
 	}), (error) => ({
@@ -341,16 +386,21 @@ async function checkCloudConnection(authentication) {
 		status: "warn",
 		detail: "skipped (auth failed)"
 	}];
-	const sitesChecks = await createCommandContext({ needsAuth: true }).then(async (context) => describeGscSites(await context.loadSites(), context.config.defaultSite)).catch((error) => [{
-		name: "gsc.sites",
-		status: "fail",
-		detail: error instanceof Error ? error.message : "Hosted Sites request failed."
-	}]);
+	const count = account.value.sites.length;
+	const sitesChecks = [count > 0 ? {
+		name: "hosted.sites",
+		status: "pass",
+		detail: `${count} hosted Site(s)`
+	} : {
+		name: "hosted.sites",
+		status: "warn",
+		detail: "no hosted Sites. Connect a Site at https://gscdump.com/app/onboarding?step=connect-sites"
+	}];
 	return [
 		{
 			name: "auth",
 			status: "pass",
-			detail: `cloud via ${authentication.apiRoot}`
+			detail: `Hosted mode via ${authentication.apiRoot}`
 		},
 		{
 			name: "auth.account",
@@ -391,7 +441,7 @@ const doctorCommand = defineCommand({
 		const authentication = await resolveAuthentication();
 		const envResult = await checkEnv();
 		const [connectionChecks, dataDirChecks, watermarkChecks] = await Promise.all([
-			authentication._tag === "Cloud" ? checkCloudConnection(authentication) : checkLocalConnection(envResult.envKeys),
+			authentication._tag === "Hosted" ? checkHostedConnection(authentication) : checkLocalConnection(envResult.envKeys),
 			checkDataDir(dataDir),
 			checkStoreWatermarks(dataDir)
 		]);

package/dist/commands/init.mjs

@@ -4,8 +4,8 @@ import { saveAuthentication } from "../auth-state.mjs";
 import { defaultDataDir, loadConfig, saveConfig } from "../config.mjs";
 import { applyCliEnvironment } from "../environment.mjs";
 import { OUTPUT_ARGS, applyOutputMode, displayPath, logger } from "../utils.mjs";
-import { authenticate, getAuth, loadTokens, resolveBYOK, saveTokens } from "../auth.mjs";
-import { loginCloud } from "./auth.mjs";
+import { ACCESS_NOT_SET_UP, authenticate, getAuth, loadTokens, resolveBYOK, resolveServiceAccount, saveTokens } from "../auth.mjs";
+import { loginHosted } from "./auth.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import fs from "node:fs/promises";
@@ -61,15 +61,15 @@ const initCommand = defineCommand({
 		},
 		"mode": {
 			type: "string",
-			description: "Authentication mode to save: cloud or local"
+			description: "Access mode to save: local or hosted"
 		},
 		"api-key": {
 			type: "string",
-			description: "gscdump user API key for --mode cloud; defaults to GSCDUMP_API_KEY"
+			description: "gscdump user API key for --mode hosted; defaults to GSCDUMP_API_KEY"
 		},
 		"api-root": {
 			type: "string",
-			description: "Cloud API root for --mode cloud; defaults to GSCDUMP_API_ROOT or https://gscdump.com/api"
+			description: "Hosted API root for --mode hosted; defaults to GSCDUMP_API_ROOT or https://gscdump.com/api"
 		},
 		...OUTPUT_ARGS
 	},
@@ -77,9 +77,9 @@ const initCommand = defineCommand({
 		applyOutputMode(args);
 		const config = await loadConfig();
 		const mode = useCliRuntime().authModeOverride;
-		if (mode === "cloud") {
-			await loginCloud(args);
-			printNextSteps();
+		if (mode === "hosted") {
+			await loginHosted(args);
+			printHostedNextSteps();
 			return;
 		}
 		if (config.clientId && config.clientSecret && !args.force) {
@@ -104,11 +104,23 @@ const initCommand = defineCommand({
 				...dataDir ? { dataDir } : {}
 			});
 			await saveAuthentication({ _tag: "Local" });
-			logger.success(`BYOK detected (${typeof byok === "string" ? "access-token" : "refresh-token"}). Auth setup skipped.`);
+			logger.success(`Google credentials found in the environment (${typeof byok === "string" ? "access-token" : "refresh-token"}). Login skipped.`);
 			logger.success("Setup complete.");
 			printNextSteps();
 			return;
 		}
+		const serviceAccount = await resolveServiceAccount().catch(() => null);
+		if (serviceAccount) {
+			const dataDir = args.store ? config.dataDir ?? defaultDataDir() : config.dataDir;
+			await saveConfig({
+				...config,
+				...dataDir ? { dataDir } : {}
+			});
+			await saveAuthentication({ _tag: "Local" });
+			logger.success(`Service account found (${serviceAccount.email ?? "key file"}). Login skipped.`);
+			printNextSteps();
+			return;
+		}
 		const envFile = await loadEnvFile();
 		const envCid = envFile?.GSC_CLIENT_ID ?? envFile?.GOOGLE_CLIENT_ID;
 		const envSec = envFile?.GSC_CLIENT_SECRET ?? envFile?.GOOGLE_CLIENT_SECRET;
@@ -145,11 +157,7 @@ const initCommand = defineCommand({
 		}
 		if (!canPrompt()) {
 			if (!await loadTokens()) {
-				logger.error([
-					"No Google credentials found. Init cannot prompt without a terminal.",
-					"Run `gscdump auth login` in a terminal, or set GSC_CLIENT_ID, GSC_CLIENT_SECRET and GSC_REFRESH_TOKEN.",
-					"To use gscdump.com, run `gscdump auth login --mode cloud`."
-				].join("\n"));
+				logger.error(`Init cannot prompt without a terminal.\n${ACCESS_NOT_SET_UP}`);
 				process.exit(1);
 			}
 			await saveConfig({
@@ -188,6 +196,14 @@ function printNextSteps(sites = []) {
 	line(`gscdump sync --status --site ${site}`, "see what the Store holds");
 	console.log();
 }
+function printHostedNextSteps() {
+	console.log();
+	console.log("  Next:");
+	const line = (command, note) => console.log(`    ${command.padEnd(44)} # ${note}`);
+	line("gscdump sites", "list your hosted Sites and their sync state");
+	line("gscdump query --site <site> -d query", "read the hosted record");
+	console.log();
+}
 async function runSmokeTest(oauth) {
 	const sites = await googleSearchConsole(oauth).sites().catch((e) => e);
 	if (sites instanceof Error) {
@@ -241,4 +257,4 @@ async function maybeWriteEnvFile(clientId, clientSecret) {
 	await fs.writeFile(envPath, content, { mode: 384 });
 	logger.success(`Wrote ${displayPath(envPath)}`);
 }
-export { initCommand, printNextSteps, runSmokeTest };
+export { initCommand, printHostedNextSteps, printNextSteps, runSmokeTest };