@gscdump/cli 4.1.0 → 4.2.0

package/README.md

@@ -2,14 +2,16 @@
 
 Google Search Console CLI and MCP server.
 
+Choose [cloud or local access](../../docs/gscdump-cli/guides/1.start/2.choose-access.md) before login. Cloud login opens gscdump.com and saves a CLI session. Local login calls Google directly and can use your own Google credentials.
+
 ```bash
 npm install -g @gscdump/cli
 ```
 
-- [Getting started](../../docs/gscdump-cli/guides/1.getting-started.md)
-- [Authentication](../../docs/gscdump-cli/guides/2.authentication.md)
+- [Getting started](../../docs/gscdump-cli/guides/1.start/1.first-result.md)
+- [Authentication](../../docs/gscdump-cli/guides/1.start/2.choose-access.md)
 - [Command reference](../../docs/gscdump-cli/api/1.commands.md)
-- [AI integration and MCP](../../docs/gscdump-cli/guides/3.ai-integration.md)
+- [AI integration and MCP](../../docs/gscdump-cli/guides/1.start/3.connect-an-agent.md)
 
 ## License
 

package/dist/auth-state.mjs

@@ -5,6 +5,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { gscdumpAvailableSiteSchema } from "@gscdump/contracts";
 import { z } from "zod";
+const HOSTED_SESSION_REJECTED = "gscdump.com rejected the CLI session. Run `gscdump auth login --mode cloud` again.";
 const apiRootSchema = z.url().transform((value) => value.replace(/\/+$/, "")).refine((value) => {
 	const url = new URL(value);
 	return !url.username && !url.password && !url.search && !url.hash && (url.protocol === "https:" || url.protocol === "http:" && [
@@ -13,11 +14,19 @@ const apiRootSchema = z.url().transform((value) => value.replace(/\/+$/, "")).re
 		"[::1]"
 	].includes(url.hostname));
 }, "Use HTTPS, or HTTP on loopback, for the API root");
-const stateSchema = z.discriminatedUnion("_tag", [z.object({ _tag: z.literal("Local") }), z.object({
-	_tag: z.literal("Cloud"),
-	apiRoot: apiRootSchema,
-	apiKey: z.string().trim().regex(/^gsd_user_\S+$/)
-})]);
+const stateSchema = z.union([
+	z.object({ _tag: z.literal("Local") }),
+	z.object({
+		_tag: z.literal("Cloud"),
+		apiRoot: apiRootSchema,
+		apiKey: z.string().trim().regex(/^gsd_user_\S+$/)
+	}),
+	z.object({
+		_tag: z.literal("Cloud"),
+		apiRoot: apiRootSchema,
+		sessionId: z.string().regex(/^[a-f0-9]{64}$/)
+	})
+]);
 function parseAuthMode(value) {
 	if (value === void 0 || value === "") return void 0;
 	if (value === "cloud" || value === "local") return value;
@@ -25,7 +34,7 @@ function parseAuthMode(value) {
 }
 function parseAuthentication(value) {
 	const parsed = stateSchema.safeParse(value);
-	if (!parsed.success) throw new Error("Invalid authentication. Use a gscdump user API key and a trusted API root.");
+	if (!parsed.success) throw new Error("Invalid authentication. Use a CLI session or gscdump user API key with a trusted API root.");
 	return parsed.data;
 }
 async function saveAuthentication(state) {
@@ -50,6 +59,10 @@ async function saveAuthentication(state) {
 async function clearAuthentication() {
 	await fs.rm(path.join(useCliRuntime().configDir, "authentication.json"), { force: true });
 }
+async function revokeCloudSession(state) {
+	if (!("sessionId" in state)) return;
+	await cloudRequest(state, "/cli/auth/logout", { method: "POST" });
+}
 async function resolveAuthentication() {
 	const runtime = useCliRuntime();
 	const env = runtime.environment;
@@ -73,7 +86,7 @@ async function resolveAuthentication() {
 		return parsed.data;
 	}
 	if (state?._tag === "Cloud") {
-		if (env.GSCDUMP_API_ROOT && env.GSCDUMP_API_ROOT.replace(/\/+$/, "") !== state.apiRoot) throw new Error("The API root changed. Supply GSCDUMP_API_KEY explicitly for the new API root.");
+		if (env.GSCDUMP_API_ROOT && env.GSCDUMP_API_ROOT.replace(/\/+$/, "") !== state.apiRoot) throw new Error("The API root changed. Run `gscdump auth login --mode cloud` for the new API root.");
 		return state;
 	}
 	if (mode === "cloud") throw new Error("Hosted credentials are missing. Run `gscdump auth login --mode cloud`.");
@@ -94,13 +107,13 @@ async function cloudRequest(state, route, options = {}) {
 		...options,
 		headers: {
 			"Content-Type": "application/json",
-			"x-api-key": state.apiKey
+			..."sessionId" in state ? { "x-cli-session": state.sessionId } : { "x-api-key": state.apiKey }
 		},
 		signal: options.signal ?? AbortSignal.timeout(3e4),
 		redirect: "error"
 	});
 	if (!response.ok) {
-		const message = response.status === 401 ? HOSTED_KEY_REJECTED : `Hosted request failed (${response.status}) for ${route.split("?")[0]}. Check \`gscdump auth status\`.`;
+		const message = response.status === 401 ? "sessionId" in state ? HOSTED_SESSION_REJECTED : HOSTED_KEY_REJECTED : `Hosted request failed (${response.status}) for ${route.split("?")[0]}. Check \`gscdump auth status\`.`;
 		throw Object.assign(new Error(message), {
 			statusCode: response.status,
 			retryAfter: response.headers.get("retry-after"),
@@ -109,6 +122,9 @@ async function cloudRequest(state, route, options = {}) {
 	}
 	return response.status === 204 ? void 0 : response.json();
 }
+function cloudCredential(state) {
+	return "sessionId" in state ? state.sessionId : state.apiKey;
+}
 async function getCloudAccount(state) {
 	const result = accountSchema.safeParse(await cloudRequest(state, "/cli/me"));
 	if (!result.success) throw new Error("The hosted API returned invalid account data.");
@@ -124,4 +140,4 @@ function formatHostedSync(site) {
 	const status = site.syncStatus ?? "pending";
 	return `${status}${site.syncProgress && site.syncProgress.total > 0 && status !== "synced" ? `: ${site.syncProgress.completed.toLocaleString("en-US")} of ${site.syncProgress.total.toLocaleString("en-US")} days (${Math.round(site.syncProgress.percent)}%)` : ""}${status === "synced" && site.oldestDateSynced && site.newestDateSynced ? `: ${site.oldestDateSynced} to ${site.newestDateSynced}` : ""}`;
 }
-export { clearAuthentication, cloudRequest, formatHostedSync, getCloudAccount, getCloudSites, parseAuthMode, parseAuthentication, resolveAuthentication, saveAuthentication };
+export { HOSTED_SESSION_REJECTED, clearAuthentication, cloudCredential, cloudRequest, formatHostedSync, getCloudAccount, getCloudSites, parseAuthMode, parseAuthentication, resolveAuthentication, revokeCloudSession, saveAuthentication };

package/dist/auth.mjs

@@ -70,7 +70,7 @@ function getTokensPath() {
 const GOOGLE_NOT_CONNECTED = [
 	"Google is not connected. Use one of these:",
 	"  Local:  gscdump auth login",
-	"  Hosted: gscdump auth login --mode cloud --api-key KEY (a gscdump.com API key)",
+	"  Cloud:  gscdump auth login --mode cloud (opens a browser)",
 	"  BYOK:   set GSC_ACCESS_TOKEN, or GSC_CLIENT_ID, GSC_CLIENT_SECRET and GSC_REFRESH_TOKEN"
 ].join("\n");
 async function loadTokens() {

package/dist/bing-hosted.mjs

@@ -1,11 +1,11 @@
-import { getCloudAccount } from "./auth-state.mjs";
+import { cloudCredential, getCloudAccount } from "./auth-state.mjs";
 import { logger } from "./utils.mjs";
 import { writeBingDump } from "./bing-data.mjs";
 import { createGscdumpV1Client } from "@gscdump/sdk/v1";
 function hostedBingClient(state) {
 	return createGscdumpV1Client({
 		apiRoot: state.apiRoot,
-		credential: state.apiKey
+		credential: cloudCredential(state)
 	});
 }
 async function listHostedBingSites(state) {

package/dist/cloud-google.mjs

@@ -1,5 +1,5 @@
 import { HOSTED_KEY_REJECTED } from "./error-handler.mjs";
-import { cloudRequest } from "./auth-state.mjs";
+import { HOSTED_SESSION_REJECTED, cloudRequest } from "./auth-state.mjs";
 import { googleSearchConsole } from "gscdump/client";
 import { ofetch } from "ofetch";
 function createCloudGoogleClient(state, fetchOptions) {
@@ -69,7 +69,7 @@ function createCloudGoogleClient(state, fetchOptions) {
 		if (error && typeof error === "object" && "response" in error && error.response instanceof Response) {
 			if (error.response.status === 401) return Response.json({ error: {
 				code: 401,
-				message: HOSTED_KEY_REJECTED
+				message: "sessionId" in state ? HOSTED_SESSION_REJECTED : HOSTED_KEY_REJECTED
 			} }, { status: 401 });
 			return error.response;
 		}

package/dist/commands/auth.mjs

@@ -1,8 +1,9 @@
 import { authCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
-import { clearAuthentication, formatHostedSync, getCloudAccount, getCloudSites, parseAuthMode, parseAuthentication, resolveAuthentication, saveAuthentication } from "../auth-state.mjs";
+import { clearAuthentication, formatHostedSync, getCloudAccount, getCloudSites, parseAuthMode, parseAuthentication, resolveAuthentication, revokeCloudSession, 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 { missingRequiredScopes } from "../auth-scopes.mjs";
 import { clearBingCredentials, getBingClient, inspectBingCredentials } from "../bing-auth.mjs";
@@ -12,7 +13,8 @@ import { adoptCurrentConfigAsProfile, profileNameFromEmail, resolveActiveProfile
 import process from "node:process";
 import { defineCommand } from "citty";
 import path from "node:path";
-import { isCancel, password } from "@clack/prompts";
+import { setTimeout } from "node:timers/promises";
+import open from "open";
 const MODE_ARG = {
 	type: "string",
 	description: "Authentication mode: cloud or local"
@@ -23,21 +25,39 @@ function applyAuthMode(args) {
 }
 async function requireLocalAuth(args) {
 	applyAuthMode(args);
-	if ((await resolveAuthentication())._tag === "Cloud") throw new Error("Cloud authentication uses an API key. OAuth scopes and token refresh require --mode local.");
+	if ((await resolveAuthentication())._tag === "Cloud") throw new Error("Cloud authentication uses a CLI session. Google OAuth scopes and token refresh require --mode local.");
 }
 async function loginCloud(args) {
 	const env = useCliRuntime().environment;
-	let apiKey = String(args["api-key"] ?? env.GSCDUMP_API_KEY ?? "");
+	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 (!process.stdin.isTTY) throw new Error("Cloud login requires --api-key or GSCDUMP_API_KEY.");
-		const answer = await password({ message: "gscdump user API key" });
-		if (isCancel(answer) || typeof answer !== "string") throw new Error("Login cancelled.");
-		apiKey = answer;
+		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({
+			request: fetch,
+			now: Date.now,
+			wait: setTimeout,
+			authorize: async (url) => {
+				logger.info(`Open this URL to connect cloud access:\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",
+			apiRoot,
+			sessionId
+		});
+		if (state._tag !== "Cloud") throw new Error("Cloud login did not return a CLI session.");
+		const account = await getCloudAccount(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.");
+		return;
 	}
 	const state = parseAuthentication({
 		_tag: "Cloud",
 		apiKey,
-		apiRoot: String(args["api-root"] ?? env.GSCDUMP_API_ROOT ?? "https://gscdump.com/api")
+		apiRoot
 	});
 	if (state._tag !== "Cloud") throw new Error("Cloud login requires a gscdump user API key.");
 	const account = await getCloudAccount(state);
@@ -365,6 +385,10 @@ const logoutCommand = defineCommand({
 	args: { ...OUTPUT_ARGS },
 	async run({ args }) {
 		applyOutputMode(args);
+		await resolveAuthentication().then((authentication) => authentication._tag === "Cloud" ? revokeCloudSession(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.`);
+		});
 		await clearTokens();
 		await clearBingCredentials();
 		await clearAuthentication();

package/dist/commands/init.mjs

@@ -148,7 +148,7 @@ const initCommand = defineCommand({
 				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 init --mode cloud --api-key <key>`."
+					"To use gscdump.com, run `gscdump auth login --mode cloud`."
 				].join("\n"));
 				process.exit(1);
 			}

package/dist/commands/mcp.mjs

@@ -9,7 +9,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 const MCP_NO_AUTH_MESSAGE = [
 	"gscdump has no Google authentication.",
 	"Run `gscdump auth login` in a terminal, then call this tool again.",
-	"For cloud mode, set GSCDUMP_API_KEY to a user API key from your gscdump.com settings.",
+	"For cloud mode, run `gscdump auth login --mode cloud` in a terminal.",
 	"For local mode, set GSC_SERVICE_ACCOUNT_JSON or GOOGLE_APPLICATION_CREDENTIALS to a service-account key file, set GSC_ACCESS_TOKEN, or set GSC_CLIENT_ID, GSC_CLIENT_SECRET, and GSC_REFRESH_TOKEN.",
 	"If you set environment variables, set them in the MCP server configuration and restart the MCP client.",
 	"If the gscdump command is missing, run `npm install -g @gscdump/cli`."

package/dist/hosted-auth.mjs

@@ -8,7 +8,11 @@ const pollSchema = z.discriminatedUnion("status", [z.object({ status: z.literal(
 	status: z.literal("complete"),
 	tokens: accessSchema.extend({ refreshToken: z.string().min(1) })
 })]);
-async function requestJson(request, route, init = {}) {
+const cloudPollSchema = z.discriminatedUnion("status", [z.object({ status: z.literal("pending") }), z.object({
+	status: z.literal("complete"),
+	sessionId: z.string().regex(/^[a-f0-9]{64}$/)
+})]);
+async function requestJson(request, route, init = {}, failureMessage) {
 	const response = await request(`${ORIGIN}/api/cli/auth/${route}`, {
 		...init,
 		redirect: "error",
@@ -16,7 +20,7 @@ async function requestJson(request, route, init = {}) {
 	});
 	if (!response.ok) {
 		if (response.status === 429 || response.status >= 500) throw new Error("Google authorization is temporarily unavailable. Try again later.");
-		throw new Error("Google authorization failed. Run `gscdump auth login --mode local --force` to reconnect.");
+		throw new Error(failureMessage ?? "Google authorization failed. Run `gscdump auth login --mode local --force` to reconnect.");
 	}
 	return response.json();
 }
@@ -52,4 +56,20 @@ async function loginWithPlatform(deps) {
 	}
 	throw new Error("Authorization expired. Run `gscdump auth login` to try again.");
 }
-export { loginWithPlatform, refreshWithPlatform };
+const CLOUD_SESSION_FAILURE = "Cloud authorization failed. Run `gscdump auth login --mode cloud` to try again.";
+async function loginWithCloudSession(deps) {
+	const init = z.object({
+		code: z.string().regex(/^S-[A-F0-9]{20}$/),
+		expiresIn: z.number().int().positive().max(600)
+	}).parse(await requestJson(deps.request, "init?mode=cloud", { method: "POST" }, CLOUD_SESSION_FAILURE));
+	const deadline = deps.now() + init.expiresIn * 1e3;
+	const url = `${ORIGIN}/app/cli/auth?code=${init.code}`;
+	await deps.authorize(url);
+	while (deps.now() < deadline) {
+		const result = cloudPollSchema.parse(await requestJson(deps.request, `poll?code=${init.code}`, {}, CLOUD_SESSION_FAILURE));
+		if (result.status === "complete") return result.sessionId;
+		await deps.wait(2e3);
+	}
+	throw new Error("Authorization expired. Run `gscdump auth login --mode cloud` to try again.");
+}
+export { loginWithCloudSession, loginWithPlatform, refreshWithPlatform };

package/dist/hosted-site.mjs

@@ -1,4 +1,4 @@
-import { getCloudAccount, parseAuthentication, resolveAuthentication } from "./auth-state.mjs";
+import { cloudCredential, getCloudAccount, parseAuthentication, resolveAuthentication } from "./auth-state.mjs";
 import { loadConfig } from "./config.mjs";
 import { resolveCliEnvironment } from "./environment.mjs";
 import { logger } from "./utils.mjs";
@@ -83,7 +83,7 @@ async function resolveHostedSite(args, command) {
 	return {
 		client: createGscdumpV1Client({
 			apiRoot: authentication.apiRoot,
-			credential: authentication.apiKey
+			credential: cloudCredential(authentication)
 		}),
 		site: match.site
 	};

package/dist/mcp/errors.mjs

@@ -114,7 +114,7 @@ function nextStep(error, status, mode) {
 		return "The signed-in account cannot open this Site. Check its Search Console permissions, or run `gscdump auth status` to see the account.";
 	}
 	if (status === 401 || error.kind === "auth-expired") {
-		if (mode === "cloud") return "Set or refresh GSCDUMP_API_KEY to a user API key from your gscdump.com settings.";
+		if (mode === "cloud") return "Run `gscdump auth login --mode cloud` in a terminal, then restart the MCP client.";
 		if (mode === "service-account") return "Fix the service-account key (GSC_SERVICE_ACCOUNT_JSON or GOOGLE_APPLICATION_CREDENTIALS) in the MCP server configuration and restart the MCP client, or run `gscdump auth status`.";
 		if (mode === "byok") return "Refresh GSC_ACCESS_TOKEN (or GSC_CLIENT_ID, GSC_CLIENT_SECRET, and GSC_REFRESH_TOKEN) in the MCP server configuration and restart the MCP client.";
 		return "Run `gscdump auth login` in a terminal to connect again.";
@@ -128,7 +128,9 @@ function describeApiError(error, mode = "local") {
 	if (status === void 0) return null;
 	const classified = classifyGoogleError(error);
 	const message = googleMessage(error) ?? classified.message;
-	return `API error ${status}: ${(message === HOSTED_KEY_REJECTED ? HOSTED_KEY_REJECTED_REASON : message).replace(/\s+/g, " ").trim().replace(/\.$/, "")}. ${nextStep(classified, status, mode)}`.trim();
+	if (message === HOSTED_KEY_REJECTED) return `API error ${status}: ${HOSTED_KEY_REJECTED_REASON}. Replace GSCDUMP_API_KEY with a key from gscdump.com Agent setup, then restart the MCP client.`;
+	if (message === "gscdump.com rejected the CLI session. Run `gscdump auth login --mode cloud` again.") return `API error ${status}: gscdump.com rejected the CLI session. Run \`gscdump auth login --mode cloud\` again, then restart the MCP client.`;
+	return `API error ${status}: ${message.replace(/\s+/g, " ").trim().replace(/\.$/, "")}. ${nextStep(classified, status, mode)}`.trim();
 }
 function googleMessage(error) {
 	const bodies = [error?.data, error?.response?.data];

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "4.1.0";
+var version = "4.2.0";
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "CLI for Google Search Console and Bing with hosted or local authentication, data exports, and an MCP server",
   "author": {
     "name": "Harlan Wilton",
@@ -44,16 +44,16 @@
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "@duckdb/node-api": "1.5.5-r.5",
-    "@gscdump/analysis": "^4.1.0",
-    "@gscdump/contracts": "^4.1.0",
-    "@gscdump/engine": "^4.1.0",
-    "@gscdump/engine-gsc-api": "^4.1.0",
-    "@gscdump/sdk": "^4.1.0",
+    "@gscdump/analysis": "^4.2.0",
+    "@gscdump/contracts": "^4.2.0",
+    "@gscdump/engine": "^4.2.0",
+    "@gscdump/engine-gsc-api": "^4.2.0",
+    "@gscdump/sdk": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.30.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.1.0",
-    "gscdump": "^4.1.0",
+    "gscdump": "^4.2.0",
     "ofetch": "^1.5.1",
     "open": "^11.0.4",
     "proper-lockfile": "^4.1.2",

package/skills/gscdump/SKILL.md

@@ -38,7 +38,7 @@ In cloud mode, `hostedSync` lists each gscdump.com Site with `syncStatus` and `s
 
 | Mode | Credentials | Query path |
 | --- | --- | --- |
-| `cloud` | gscdump user API key | `https://gscdump.com/api` uses saved Search Engine connections |
+| `cloud` | Browser-approved CLI session; optional user API key for automation | `https://gscdump.com/api` uses saved Search Engine connections |
 | `local` | Google OAuth/service account or Bing API key/OAuth | Calls the Search Engine directly |
 
 `--mode cloud|local` overrides one invocation. `GSCDUMP_AUTH_MODE` also overrides the saved mode.
@@ -47,28 +47,32 @@ If no mode is saved, `GSCDUMP_API_KEY` selects cloud mode.
 With neither source, the CLI defaults to local mode.
 When a saved mode exists, it remains selected unless an explicit override applies.
 Never switch modes to bypass an authentication failure.
-`GSCDUMP_API_ROOT` defaults to `https://gscdump.com/api`. Supply the API key explicitly when changing a saved API root.
+`GSCDUMP_API_ROOT` defaults to `https://gscdump.com/api`. Browser login uses this root. Supply an API key explicitly for a custom root.
 
 ```sh
-# The user supplies a user API key from gscdump.com settings.
+# Open gscdump.com in a browser and approve the CLI session.
 gscdump auth login --mode cloud
 gscdump bing sites --json
 gscdump bing login --site s_SITE_ID
 gscdump bing dump --site s_SITE_ID --out ./bing-export --format json
 
-# Local Google and Bing credentials stay separate.
+# Local Google login uses gscdump.com for OAuth by default.
+# Google data requests go directly from the CLI to Google.
 gscdump auth login --mode local
 gscdump bing login --mode local
 gscdump bing dump --site https://example.com/ --out ./bing-export
 ```
 
+For a fully local Google login, set `GSC_CLIENT_ID` and `GSC_CLIENT_SECRET` before `auth login --mode local`.
+The CLI then opens Google directly. A service account can use `--service-account` instead.
+
 Hosted Bing login opens the existing connection flow on gscdump.com.
 Local Bing login uses `BING_API_KEY` or a password prompt.
 Local `--oauth` uses `BING_CLIENT_ID`, `BING_CLIENT_SECRET`, and a registered loopback callback.
 The default callback is `http://127.0.0.1:53683/oauth/bing`. `BING_ACCESS_TOKEN` accepts an existing OAuth access token.
 After cloud Bing login opens a browser, use `bing status --site s_SITE_ID` to confirm the connection.
 
-`auth logout` removes the saved mode and saved Google and Bing credentials.
+`auth logout` revokes a saved cloud CLI session and removes saved mode and Google and Bing credentials.
 `bing logout --mode local` removes only saved Bing credentials. Environment credentials remain active until unset.
 
 Hosted Bing commands use the API's plan and preview access rules.
@@ -154,6 +158,8 @@ If local Google credentials are missing, use one of these paths:
 
 Default local login opens gscdump.com for free Google login and token refresh.
 Data queries call Google directly. No Google Cloud project or hosted activation is required.
+For a fully local connection, set `GSC_CLIENT_ID` and `GSC_CLIENT_SECRET` before login.
+The CLI then opens Google directly and uses a loopback callback.
 Use `gscdump auth login --mode local --no-browser` when a browser runs on another host.
 The default grant is read-only Search Console access.
 For Google write operations, use your own OAuth client with the required scopes.