@bjesuiter/codex-switcher 1.8.4 → 1.8.6

package/README.md

@@ -6,11 +6,21 @@ Switch the coding-agents [pi](https://pi.dev/), [codex](https://developers.opena
 
 ## Latest Changes
 
-### 1.8.4
+### 1.8.6
+
+#### Features
+
+- Add Linux `cdx keyring check` for focused `gnome-keyring` dependency/runtime checks plus a secure-store probe.
+- Add Linux `cdx keyring install` to install required keyring packages on Debian/Ubuntu/Mint, with `--yes` and `--skip-check` support.
+- Expand Linux `cdx doctor` secure-store remediation with deeper guidance and step-by-step follow-up checks when Secret Service/keyring access fails.
 
 #### Fixes
 
-- Linux `cdx doctor` guided checks now detect `gnome-keyring-daemon` with a full-command `pgrep -f` match, fixing false negatives/errors on systems where `pgrep -x` cannot match process names longer than 15 characters.
+- When Linux secure-store access fails because the keyring is locked, `cdx` now prompts you to unlock it and retry instead of only surfacing a generic error.
+
+#### Internal
+
+- Update dependencies and tooling: `@bomb.sh/tab`, `@clack/prompts`, `@types/bun`, `@types/node`, and `tsdown`.
 
 see full changelog here: https://github.com/bjesuiter/codex-switcher/blob/main/CHANGELOG.md
 
@@ -167,6 +177,8 @@ cdx migrate-secrets
 | `cdx migrate-secrets` | Migrate macOS legacy keychain entries to cross-keychain and switch config to `auto` |
 | `cdx doctor` | Show auth file paths/state and runtime capabilities |
 | `cdx doctor --check-keychain-acl` | Detect macOS keychain ACL/runtime mismatches (`cdx`/Bun vs legacy `security` CLI), warn about prompt-heavy setups, and suggest `cdx migrate-secrets` (slow) |
+| `cdx keyring check` | Run focused Linux gnome-keyring dependency/runtime checks and secure-store probe |
+| `cdx keyring install` | Install Linux keyring dependencies on Debian/Ubuntu/Mint (`--yes`, `--skip-check`) |
 | `cdx usage` | Show usage overview for all accounts |
 | `cdx usage <account>` | Show detailed usage for a specific account |
 | `cdx update-self` | Update cdx to the latest version |

package/cdx.mjs

@@ -13,10 +13,8 @@ import { randomBytes } from "node:crypto";
 import { Decrypter, Encrypter } from "age-encryption";
 import { generatePKCE } from "@openauthjs/openauth/pkce";
 import http from "node:http";
-
 //#region package.json
-var version = "1.8.4";
-
+var version = "1.8.6";
 //#endregion
 //#region lib/platform/path-resolver.ts
 const envValue = (env, key) => {
@@ -61,7 +59,6 @@ const resolveRuntimePaths = (input) => {
 	if (input.platform === "win32") return resolveWindowsPaths(input.env, input.homeDir);
 	return resolveXdgPaths(input.env, input.homeDir, input.platform);
 };
-
 //#endregion
 //#region lib/paths.ts
 const toPathConfig = (paths) => ({
@@ -109,7 +106,6 @@ const createTestPaths = (testDir) => ({
 	codexAuthPath: path.join(testDir, "codex", "auth.json"),
 	piAuthPath: path.join(testDir, "pi", "auth.json")
 });
-
 //#endregion
 //#region lib/config.ts
 const isSecretStoreSelection = (value) => value === "auto" || value === "legacy-keychain";
@@ -143,7 +139,6 @@ const configExists = () => {
 	const { configPath } = getPaths();
 	return existsSync(configPath);
 };
-
 //#endregion
 //#region lib/commands/errors.ts
 const exitWithCommandError = (error) => {
@@ -151,7 +146,6 @@ const exitWithCommandError = (error) => {
 	process.stderr.write(`${message}\n`);
 	process.exit(1);
 };
-
 //#endregion
 //#region lib/auth.ts
 const readExistingJson = async (filePath) => {
@@ -231,7 +225,6 @@ const writeAllAuthFiles = async (payload) => {
 		codexCleared
 	};
 };
-
 //#endregion
 //#region lib/platform/browser.ts
 const getBrowserLauncher = (platform = process.platform, url) => {
@@ -256,7 +249,7 @@ const getBrowserLauncher = (platform = process.platform, url) => {
 		label: "xdg-open"
 	};
 };
-const isCommandAvailable$2 = (command, platform = process.platform) => {
+const isCommandAvailable$3 = (command, platform = process.platform) => {
 	const probe = platform === "win32" ? "where" : "which";
 	return Bun.spawnSync({
 		cmd: [probe, command],
@@ -269,13 +262,13 @@ const getBrowserLauncherCapability = (platform = process.platform) => {
 	return {
 		command: launcher.command,
 		label: launcher.label,
-		available: isCommandAvailable$2(launcher.command, platform)
+		available: isCommandAvailable$3(launcher.command, platform)
 	};
 };
 const openBrowserUrl = (url, options = {}) => {
 	const platform = options.platform ?? process.platform;
 	const spawnImpl = options.spawnImpl ?? spawn;
-	const commandAvailable = options.isCommandAvailableImpl ?? isCommandAvailable$2;
+	const commandAvailable = options.isCommandAvailableImpl ?? isCommandAvailable$3;
 	const launcher = getBrowserLauncher(platform, url);
 	if (!commandAvailable(launcher.command, platform)) return {
 		ok: false,
@@ -303,10 +296,9 @@ const openBrowserUrl = (url, options = {}) => {
 		};
 	}
 };
-
 //#endregion
 //#region lib/platform/clipboard.ts
-const isCommandAvailable$1 = (command, platform = process.platform) => {
+const isCommandAvailable$2 = (command, platform = process.platform) => {
 	const probe = platform === "win32" ? "where" : "which";
 	return Bun.spawnSync({
 		cmd: [probe, command],
@@ -392,7 +384,7 @@ const getLocalClipboardTargets = (platform, env, commandExists) => {
 	});
 	return targets;
 };
-const resolveClipboardTargets = (context = {}, commandExists = isCommandAvailable$1) => {
+const resolveClipboardTargets = (context = {}, commandExists = isCommandAvailable$2) => {
 	const platform = context.platform ?? process.platform;
 	const env = context.env ?? process.env;
 	const isTTY = context.isTTY ?? (Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY));
@@ -433,7 +425,7 @@ const defaultRunCommand = (command, args, input) => {
 	};
 };
 const tryCopyToClipboard = (text, options = {}) => {
-	const commandExists = options.commandExistsImpl ?? isCommandAvailable$1;
+	const commandExists = options.commandExistsImpl ?? isCommandAvailable$2;
 	const runCommand = options.runCommandImpl ?? defaultRunCommand;
 	const writeStdout = options.writeStdoutImpl ?? ((chunk) => {
 		process.stdout.write(chunk);
@@ -479,7 +471,7 @@ const tryCopyToClipboard = (text, options = {}) => {
 	};
 };
 const escapePosixSingleQuoted = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
-const buildClipboardHelperCommand = (text, context = {}, commandExists = isCommandAvailable$1) => {
+const buildClipboardHelperCommand = (text, context = {}, commandExists = isCommandAvailable$2) => {
 	const commandTarget = resolveClipboardTargets(context, commandExists).find((target) => target.kind === "command");
 	if (!commandTarget) return null;
 	if (commandTarget.method === "powershell") {
@@ -489,7 +481,6 @@ const buildClipboardHelperCommand = (text, context = {}, commandExists = isComma
 	if (commandTarget.method === "clip") return `printf '%s' ${escapePosixSingleQuoted(text)} | cmd /c clip`;
 	return `printf '%s' ${escapePosixSingleQuoted(text)} | ${commandTarget.command} ${commandTarget.args.join(" ")}`.trim();
 };
-
 //#endregion
 //#region lib/keychain.ts
 const SERVICE_PREFIX$3 = "cdx-openai-";
@@ -588,11 +579,9 @@ const listKeychainAccounts = () => {
 	while ((match = serviceRegex.exec(output)) !== null) if (match[1]) accounts.push(match[1]);
 	return [...new Set(accounts)];
 };
-
 //#endregion
 //#region lib/secrets/cross-keychain-overrides.ts
 const LEGACY_MAX_PASSWORD_LENGTH = 4096;
-const DEFAULT_CROSS_KEYCHAIN_MAX_PASSWORD_LENGTH = 16384;
 const parseMaxPasswordLength = (value) => {
 	if (!value) return null;
 	const parsed = Number.parseInt(value, 10);
@@ -600,9 +589,8 @@ const parseMaxPasswordLength = (value) => {
 	return parsed;
 };
 const getCrossKeychainBackendOverrides = () => {
-	return { max_password_length: parseMaxPasswordLength(process.env.CDX_CROSS_KEYCHAIN_MAX_PASSWORD_LENGTH) ?? DEFAULT_CROSS_KEYCHAIN_MAX_PASSWORD_LENGTH };
+	return { max_password_length: parseMaxPasswordLength(process.env.CDX_CROSS_KEYCHAIN_MAX_PASSWORD_LENGTH) ?? 16384 };
 };
-
 //#endregion
 //#region lib/secrets/fallback-consent.ts
 const CONSENT_FILE = "secure-store-fallback-consent.json";
@@ -654,7 +642,6 @@ const ensureFallbackConsent = async (scope, warningMessage) => {
 	accepted[scope] = { acceptedAt: (/* @__PURE__ */ new Date()).toISOString() };
 	await saveConsentMap(accepted);
 };
-
 //#endregion
 //#region lib/secrets/linux-cross-keychain.ts
 const SERVICE_PREFIX$2 = "cdx-openai-";
@@ -670,6 +657,7 @@ const STORE_UNAVAILABLE_MARKERS = [
 	"unable to initialize linux secure-store backend",
 	"no keyring backend could be initialized",
 	"native keyring module not available",
+	"linux secure store is unavailable",
 	"secret service operation failed",
 	"couldn't access platform secure storage",
 	"dbus",
@@ -759,6 +747,82 @@ const withService$1 = async (accountId, run, options = {}) => {
 		throw error;
 	}
 };
+const isInteractiveTerminal$2 = () => Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+const applyEnvAssignments$1 = (raw) => {
+	const lines = raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+	for (const line of lines) {
+		const match = line.match(/^([A-Z0-9_]+)=(.*);?$/);
+		if (!match) continue;
+		const key = match[1];
+		const value = match[2].replace(/;$/, "");
+		if (key) process.env[key] = value;
+	}
+};
+const runCommandWithInput = async (command, args, input) => await new Promise((resolve) => {
+	const child = spawn(command, args, { stdio: [
+		"pipe",
+		"pipe",
+		"pipe"
+	] });
+	let stdout = "";
+	let stderr = "";
+	let spawnError = null;
+	child.stdout?.on("data", (chunk) => {
+		stdout += chunk.toString();
+	});
+	child.stderr?.on("data", (chunk) => {
+		stderr += chunk.toString();
+	});
+	child.once("error", (error) => {
+		spawnError = error.message;
+	});
+	child.once("close", (code) => {
+		resolve({
+			ok: spawnError === null && code === 0,
+			stdout: stdout.trim(),
+			stderr: stderr.trim(),
+			...spawnError ? { error: spawnError } : {}
+		});
+	});
+	child.stdin?.write(input);
+	child.stdin?.end();
+});
+const attemptInteractiveLinuxKeyringUnlock = async () => {
+	if (!isInteractiveTerminal$2()) return false;
+	const shouldUnlock = await p.confirm({
+		message: "Linux keyring appears locked. Unlock it now?",
+		initialValue: true
+	});
+	if (p.isCancel(shouldUnlock) || !shouldUnlock) return false;
+	const passphrase = await p.password({
+		message: "Enter Linux keyring password:",
+		validate: (value) => {
+			if (!value || !value.trim()) return "Password is required to unlock keyring.";
+		}
+	});
+	if (p.isCancel(passphrase) || !passphrase) return false;
+	const result = await runCommandWithInput("gnome-keyring-daemon", ["--unlock", "--components=secrets"], `${passphrase}\n`);
+	if (!result.ok) {
+		const details = result.error || result.stderr || result.stdout;
+		if (details) process.stderr.write(`cdx: keyring unlock failed (${details})\n`);
+		return false;
+	}
+	applyEnvAssignments$1(result.stdout);
+	return true;
+};
+const withLinuxUnlockRetry = async (run, options = {}) => {
+	let unlockAttempted = false;
+	while (true) try {
+		return await run();
+	} catch (error) {
+		const kind = classifyLinuxSecureStoreError(error);
+		if (!(!unlockAttempted && (kind === "store_unavailable" || kind === "missing_entry" && options.forWrite && options.retryOnMissingEntryForNativeWrite && selectedBackend$2 === "native-linux"))) throw error;
+		unlockAttempted = true;
+		if (!await attemptInteractiveLinuxKeyringUnlock()) throw error;
+		backendInitPromise$2 = null;
+		selectedBackend$2 = null;
+	}
+};
 const trySaveWithSecretServiceFallback = async (accountId, serializedPayload) => {
 	if (!await trySwitchBackend("secret-service", { forWrite: true })) return {
 		ok: false,
@@ -777,7 +841,10 @@ const trySaveWithSecretServiceFallback = async (accountId, serializedPayload) =>
 const saveLinuxCrossKeychainPayload = async (accountId, payload) => {
 	const serialized = JSON.stringify(payload);
 	try {
-		await withService$1(accountId, (service) => setPassword(service, accountId, serialized), { forWrite: true });
+		await withLinuxUnlockRetry(() => withService$1(accountId, (service) => setPassword(service, accountId, serialized), { forWrite: true }), {
+			forWrite: true,
+			retryOnMissingEntryForNativeWrite: true
+		});
 		return;
 	} catch (error) {
 		const kind = classifyLinuxSecureStoreError(error);
@@ -792,7 +859,7 @@ const saveLinuxCrossKeychainPayload = async (accountId, payload) => {
 };
 const loadLinuxCrossKeychainPayload = async (accountId) => {
 	try {
-		const raw = await withService$1(accountId, (service) => getPassword(service, accountId));
+		const raw = await withLinuxUnlockRetry(() => withService$1(accountId, (service) => getPassword(service, accountId)));
 		if (raw === null) throw new Error(`No stored credentials found for account ${accountId}.`);
 		return parsePayload$2(accountId, raw);
 	} catch (error) {
@@ -802,7 +869,7 @@ const loadLinuxCrossKeychainPayload = async (accountId) => {
 };
 const deleteLinuxCrossKeychainPayload = async (accountId) => {
 	try {
-		await withService$1(accountId, (service) => deletePassword(service, accountId));
+		await withLinuxUnlockRetry(() => withService$1(accountId, (service) => deletePassword(service, accountId)));
 	} catch (error) {
 		if (classifyLinuxSecureStoreError(error) === "missing_entry") return;
 		throw error;
@@ -810,13 +877,12 @@ const deleteLinuxCrossKeychainPayload = async (accountId) => {
 };
 const linuxCrossKeychainPayloadExists = async (accountId) => {
 	try {
-		return await withService$1(accountId, async (service) => await getPassword(service, accountId) !== null);
+		return await withLinuxUnlockRetry(() => withService$1(accountId, async (service) => await getPassword(service, accountId) !== null));
 	} catch (error) {
 		if (classifyLinuxSecureStoreError(error) === "missing_entry") return false;
 		throw error;
 	}
 };
-
 //#endregion
 //#region lib/secrets/macos-cross-keychain.ts
 const SERVICE_PREFIX$1 = "cdx-openai-";
@@ -881,7 +947,6 @@ const loadMacOSCrossKeychainPayload = async (accountId) => {
 };
 const deleteMacOSCrossKeychainPayload = async (accountId) => withService(accountId, (service) => deletePassword(service, accountId));
 const macosCrossKeychainPayloadExists = async (accountId) => withService(accountId, async (service) => await getPassword(service, accountId) !== null);
-
 //#endregion
 //#region lib/secrets/windows-cross-keychain.ts
 const SERVICE_PREFIX = "cdx-openai-";
@@ -1059,7 +1124,6 @@ const windowsCrossKeychainPayloadExists = async (accountId) => withWindowsBacken
 	}
 	return await loadLegacyPayload(accountId) !== null;
 });
-
 //#endregion
 //#region lib/secrets/store.ts
 const MISSING_SECRET_STORE_ERROR_MARKERS = [
@@ -1287,7 +1351,6 @@ const getSecretStoreCapability = () => {
 		...capability.reason ? { reason: capability.reason } : {}
 	};
 };
-
 //#endregion
 //#region lib/oauth/constants.ts
 const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
@@ -1297,7 +1360,6 @@ const TOKEN_URL = "https://auth.openai.com/oauth/token";
 const REDIRECT_URI = "http://localhost:1455/auth/callback";
 const SCOPE = "openid profile email offline_access";
 const CALLBACK_PORT = 1455;
-
 //#endregion
 //#region lib/oauth/auth.ts
 const createState = () => {
@@ -1530,7 +1592,6 @@ const extractAccountId = (accessToken) => {
 	if (authClaim?.user_id) return authClaim.user_id;
 	return payload.sub ?? null;
 };
-
 //#endregion
 //#region lib/oauth/server.ts
 const AUTH_TIMEOUT_MS = 300 * 1e3;
@@ -1628,7 +1689,6 @@ const startOAuthServer = (state) => {
 		});
 	});
 };
-
 //#endregion
 //#region lib/oauth/login.ts
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -2149,7 +2209,6 @@ const performLogin = async (options = {}) => {
 	p.outro("You can now use 'cdx switch' to activate this account.");
 	return { accountId };
 };
-
 //#endregion
 //#region lib/refresh.ts
 const writeActiveAuthFilesIfCurrent = async (accountId) => {
@@ -2159,7 +2218,6 @@ const writeActiveAuthFilesIfCurrent = async (accountId) => {
 	if (!current || current.accountId !== accountId) return null;
 	return writeAllAuthFiles(await getSecretStoreAdapter().load(accountId));
 };
-
 //#endregion
 //#region lib/platform/capabilities.ts
 const getRuntimeCapabilities = () => {
@@ -2171,7 +2229,6 @@ const getRuntimeCapabilities = () => {
 		browserLauncher: getBrowserLauncherCapability(process.platform)
 	};
 };
-
 //#endregion
 //#region lib/status.ts
 const formatDuration = (ms) => {
@@ -2299,7 +2356,6 @@ const getStatus = async () => {
 		capabilities: getRuntimeCapabilities()
 	};
 };
-
 //#endregion
 //#region lib/interactive.ts
 const getAccountDisplay = (accountId, isCurrent, label) => {
@@ -2630,7 +2686,6 @@ const runInteractiveMode = async () => {
 	}
 	p.outro("Goodbye!");
 };
-
 //#endregion
 //#region lib/commands/interactive.ts
 const registerDefaultInteractiveAction = (program) => {
@@ -2642,7 +2697,6 @@ const registerDefaultInteractiveAction = (program) => {
 		}
 	});
 };
-
 //#endregion
 //#region lib/keychain-acl.ts
 const getDefaultMap = (services) => {
@@ -2714,7 +2768,6 @@ const getKeychainDecryptAccessByServiceAsync = async (services) => {
 	if (!dumpResult.success) return defaultResult;
 	return parseKeychainDecryptAccessFromDump(dumpResult.output, dedupedServices);
 };
-
 //#endregion
 //#region lib/secrets/probe.ts
 const toError = (error) => error instanceof Error ? error : new Error(String(error));
@@ -2764,7 +2817,6 @@ const runSecretStoreWriteReadProbe = async (secretStore, options = {}) => {
 	}
 	return result;
 };
-
 //#endregion
 //#region lib/commands/doctor.ts
 const hasRuntimeTrustedApp = (trustedApplications, runtimeExecutablePath) => {
@@ -2791,8 +2843,8 @@ const getSecretStoreProbeGuidance = (platform) => {
 	if (platform === "win32") return "Suggested fix: ensure Windows Credential Manager is available for this user session, then retry login.";
 	return null;
 };
-const isInteractiveTerminal = () => Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
-const runCommandCapture = async (command, args) => await new Promise((resolve) => {
+const isInteractiveTerminal$1 = () => Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+const runCommandCapture$1 = async (command, args) => await new Promise((resolve) => {
 	const child = spawn(command, args, { stdio: [
 		"ignore",
 		"pipe",
@@ -2819,27 +2871,83 @@ const runCommandCapture = async (command, args) => await new Promise((resolve) =
 		});
 	});
 });
-const extractCommandFailureDetails = (result) => result.error || result.stderr || result.stdout || void 0;
-const isCommandAvailable = async (commandName) => {
-	return (await runCommandCapture("sh", ["-lc", `command -v ${commandName} >/dev/null 2>&1`])).ok;
+const runCommandCaptureWithInput = async (command, args, input) => await new Promise((resolve) => {
+	const child = spawn(command, args, { stdio: [
+		"pipe",
+		"pipe",
+		"pipe"
+	] });
+	let stdout = "";
+	let stderr = "";
+	let spawnError = null;
+	child.stdout?.on("data", (chunk) => {
+		stdout += chunk.toString();
+	});
+	child.stderr?.on("data", (chunk) => {
+		stderr += chunk.toString();
+	});
+	child.once("error", (error) => {
+		spawnError = error.message;
+	});
+	child.stdin?.write(input);
+	child.stdin?.end();
+	child.once("close", (code) => {
+		resolve({
+			ok: spawnError === null && code === 0,
+			stdout: stdout.trim(),
+			stderr: stderr.trim(),
+			...spawnError ? { error: spawnError } : {}
+		});
+	});
+});
+const runCommandDetached = async (command, args) => {
+	try {
+		spawn(command, args, {
+			detached: true,
+			stdio: "ignore"
+		}).unref();
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
 };
-const checkGnomeKeyringRunning = async () => {
-	if (await isCommandAvailable("pgrep")) {
-		const pgrepResult = await runCommandCapture("pgrep", ["-f", "(^|/)gnome-keyring-daemon( |$)"]);
+const extractCommandFailureDetails$1 = (result) => result.error || result.stderr || result.stdout || void 0;
+const isCommandAvailable$1 = async (commandName) => {
+	return (await runCommandCapture$1("sh", ["-lc", `command -v ${commandName} >/dev/null 2>&1`])).ok;
+};
+const GNOME_KEYRING_CMDLINE_PATTERN$1 = /(^|\/)gnome-keyring-daemon(\s|$)/;
+const checkGnomeKeyringRunning$1 = async () => {
+	if (await isCommandAvailable$1("ps")) {
+		const psResult = await runCommandCapture$1("ps", [
+			"-A",
+			"-o",
+			"args="
+		]);
+		if (psResult.ok) {
+			if (psResult.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).some((line) => GNOME_KEYRING_CMDLINE_PATTERN$1.test(line))) return { ok: true };
+			return {
+				ok: false,
+				details: "No gnome-keyring-daemon process found."
+			};
+		}
+	}
+	if (await isCommandAvailable$1("pgrep")) {
+		const pgrepResult = await runCommandCapture$1("pgrep", ["-f", "gnome-keyring-daemon"]);
 		if (pgrepResult.ok) return { ok: true };
 		return {
 			ok: false,
-			details: extractCommandFailureDetails(pgrepResult) ?? "No gnome-keyring-daemon process found."
+			details: extractCommandFailureDetails$1(pgrepResult) ?? "No gnome-keyring-daemon process found."
 		};
 	}
-	const psFallback = await runCommandCapture("sh", ["-lc", "ps -A -o comm= | grep -q '^gnome-keyring-daemon$'"]);
-	if (psFallback.ok) return { ok: true };
 	return {
 		ok: false,
-		details: extractCommandFailureDetails(psFallback) ?? "No gnome-keyring-daemon process found."
+		details: "Neither ps nor pgrep is available to check gnome-keyring-daemon."
 	};
 };
-const parseSystemctlEnabledState = (output) => {
+const parseSystemctlEnabledState$1 = (output) => {
 	const normalized = output.trim().toLowerCase();
 	if ([
 		"enabled",
@@ -2857,8 +2965,8 @@ const parseSystemctlEnabledState = (output) => {
 	].includes(normalized)) return "disabled";
 	return "unknown";
 };
-const getLinuxGnomeKeyringAutoStartStatus = async () => {
-	if (!await isCommandAvailable("systemctl")) return {
+const getLinuxGnomeKeyringAutoStartStatus$1 = async () => {
+	if (!await isCommandAvailable$1("systemctl")) return {
 		state: "unknown",
 		details: "systemctl is not available; autostart detection depends on your desktop/session config."
 	};
@@ -2866,12 +2974,12 @@ const getLinuxGnomeKeyringAutoStartStatus = async () => {
 	let sawDisabled = false;
 	const details = [];
 	for (const unit of units) {
-		const result = await runCommandCapture("systemctl", [
+		const result = await runCommandCapture$1("systemctl", [
 			"--user",
 			"is-enabled",
 			unit
 		]);
-		const state = parseSystemctlEnabledState(result.stdout || result.stderr);
+		const state = parseSystemctlEnabledState$1(result.stdout || result.stderr);
 		if (state === "enabled") return {
 			state: "enabled",
 			details: `${unit} is enabled (${result.stdout || "enabled"}).`
@@ -2881,7 +2989,7 @@ const getLinuxGnomeKeyringAutoStartStatus = async () => {
 			details.push(`${unit}: ${result.stdout || result.stderr || "disabled"}`);
 			continue;
 		}
-		const maybeDetail = extractCommandFailureDetails(result);
+		const maybeDetail = extractCommandFailureDetails$1(result);
 		if (maybeDetail) details.push(`${unit}: ${maybeDetail}`);
 	}
 	if (sawDisabled) return {
@@ -2903,25 +3011,25 @@ const applyKeyringEnvAssignments = (raw) => {
 		if (key) process.env[key] = value;
 	}
 };
-const startGnomeKeyringNow = async () => {
-	const directStart = await runCommandCapture("gnome-keyring-daemon", ["--start", "--components=secrets"]);
+const startGnomeKeyringNow$1 = async () => {
+	const directStart = await runCommandCapture$1("gnome-keyring-daemon", ["--start", "--components=secrets"]);
 	if (directStart.ok) {
 		applyKeyringEnvAssignments(directStart.stdout);
-		const runningCheck = await checkGnomeKeyringRunning();
+		const runningCheck = await checkGnomeKeyringRunning$1();
 		if (runningCheck.ok) return { ok: true };
 		return {
 			ok: false,
 			details: runningCheck.details ?? "gnome-keyring-daemon start command succeeded, but process was not detected afterwards."
 		};
 	}
-	if (await isCommandAvailable("systemctl")) {
-		const serviceStart = await runCommandCapture("systemctl", [
+	if (await isCommandAvailable$1("systemctl")) {
+		const serviceStart = await runCommandCapture$1("systemctl", [
 			"--user",
 			"start",
 			"gnome-keyring-daemon.service"
 		]);
 		if (serviceStart.ok) {
-			const runningCheck = await checkGnomeKeyringRunning();
+			const runningCheck = await checkGnomeKeyringRunning$1();
 			if (runningCheck.ok) return { ok: true };
 			return {
 				ok: false,
@@ -2930,23 +3038,23 @@ const startGnomeKeyringNow = async () => {
 		}
 		return {
 			ok: false,
-			details: extractCommandFailureDetails(directStart) ?? extractCommandFailureDetails(serviceStart) ?? "Failed to start gnome-keyring-daemon."
+			details: extractCommandFailureDetails$1(directStart) ?? extractCommandFailureDetails$1(serviceStart) ?? "Failed to start gnome-keyring-daemon."
 		};
 	}
 	return {
 		ok: false,
-		details: extractCommandFailureDetails(directStart) ?? "Failed to start gnome-keyring-daemon."
+		details: extractCommandFailureDetails$1(directStart) ?? "Failed to start gnome-keyring-daemon."
 	};
 };
 const enableGnomeKeyringAutoStart = async () => {
-	if (!await isCommandAvailable("systemctl")) return {
+	if (!await isCommandAvailable$1("systemctl")) return {
 		ok: false,
 		details: "systemctl is not available, so cdx cannot automatically enable startup in this session manager."
 	};
 	const units = ["gnome-keyring-daemon.socket", "gnome-keyring-daemon.service"];
 	const failures = [];
 	for (const unit of units) {
-		const result = await runCommandCapture("systemctl", [
+		const result = await runCommandCapture$1("systemctl", [
 			"--user",
 			"enable",
 			unit
@@ -2955,7 +3063,7 @@ const enableGnomeKeyringAutoStart = async () => {
 			ok: true,
 			details: `${unit} enabled.`
 		};
-		const detail = extractCommandFailureDetails(result);
+		const detail = extractCommandFailureDetails$1(result);
 		failures.push(`${unit}: ${detail ?? "enable failed"}`);
 	}
 	return {
@@ -2964,14 +3072,14 @@ const enableGnomeKeyringAutoStart = async () => {
 	};
 };
 const maybeOfferToStartGnomeKeyring = async () => {
-	const autoStartStatus = await getLinuxGnomeKeyringAutoStartStatus();
+	const autoStartStatus = await getLinuxGnomeKeyringAutoStartStatus$1();
 	if (autoStartStatus.state === "enabled") {
 		const shouldStartNow = await p.confirm({
 			message: "gnome-keyring autostart appears enabled, but it is not running right now. Start it now?",
 			initialValue: true
 		});
 		if (p.isCancel(shouldStartNow) || !shouldStartNow) return false;
-		const startResult = await startGnomeKeyringNow();
+		const startResult = await startGnomeKeyringNow$1();
 		if (!startResult.ok) {
 			process.stdout.write(`      failed to start gnome-keyring-daemon: ${startResult.details ?? "unknown error"}\n`);
 			return false;
@@ -3007,7 +3115,7 @@ const maybeOfferToStartGnomeKeyring = async () => {
 		}
 		process.stdout.write(`      autostart enabled${enableResult.details ? ` (${enableResult.details})` : ""}.\n`);
 	}
-	const startResult = await startGnomeKeyringNow();
+	const startResult = await startGnomeKeyringNow$1();
 	if (!startResult.ok) {
 		process.stdout.write(`      failed to start gnome-keyring-daemon: ${startResult.details ?? "unknown error"}\n`);
 		return false;
@@ -3016,9 +3124,9 @@ const maybeOfferToStartGnomeKeyring = async () => {
 	return true;
 };
 const runLinuxSecretStoreChecklist = async () => {
-	const gnomeKeyringInstalled = await isCommandAvailable("gnome-keyring-daemon");
-	const secretToolInstalled = await isCommandAvailable("secret-tool");
-	const gnomeKeyringRunning = await checkGnomeKeyringRunning();
+	const gnomeKeyringInstalled = await isCommandAvailable$1("gnome-keyring-daemon");
+	const secretToolInstalled = await isCommandAvailable$1("secret-tool");
+	const gnomeKeyringRunning = await checkGnomeKeyringRunning$1();
 	return [
 		{
 			id: "gnome-keyring-installed",
@@ -3037,12 +3145,118 @@ const runLinuxSecretStoreChecklist = async () => {
 			question: "Is gnome-keyring running?",
 			ok: gnomeKeyringRunning.ok,
 			details: gnomeKeyringRunning.details,
-			hint: "Start/unlock gnome-keyring-daemon in your session (for a quick test: `gnome-keyring-daemon --start --components=secrets`)."
+			hint: "Start/unlock gnome-keyring-daemon in your session (cdx can do this interactively)."
 		}
 	];
 };
+const runSecretToolRoundTripCheck = async () => {
+	const id = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+	const service = `cdx-doctor-secret-service-${id}`;
+	const account = `cdx-doctor-account-${id}`;
+	const value = `cdx-doctor-value-${id}`;
+	const storeResult = await runCommandCaptureWithInput("secret-tool", [
+		"store",
+		"--label=cdx doctor Secret Service probe",
+		"service",
+		service,
+		"account",
+		account
+	], `${value}\n`);
+	if (!storeResult.ok) return {
+		ok: false,
+		details: extractCommandFailureDetails$1(storeResult) ?? "secret-tool store failed."
+	};
+	const lookupResult = await runCommandCapture$1("secret-tool", [
+		"lookup",
+		"service",
+		service,
+		"account",
+		account
+	]);
+	if (!lookupResult.ok) return {
+		ok: false,
+		details: extractCommandFailureDetails$1(lookupResult) ?? "secret-tool lookup failed."
+	};
+	if (lookupResult.stdout.trim() !== value) return {
+		ok: false,
+		details: "secret-tool lookup returned an unexpected value after store."
+	};
+	const clearResult = await runCommandCapture$1("secret-tool", [
+		"clear",
+		"service",
+		service,
+		"account",
+		account
+	]);
+	if (!clearResult.ok) return {
+		ok: false,
+		details: extractCommandFailureDetails$1(clearResult) ?? "secret-tool clear failed."
+	};
+	return { ok: true };
+};
+const runLinuxSecretStoreDeepRemediation = async () => {
+	if (!isInteractiveTerminal$1()) return;
+	const hasSecretTool = await isCommandAvailable$1("secret-tool");
+	const hasSeahorse = await isCommandAvailable$1("seahorse");
+	const shouldStart = await p.confirm({
+		message: "Run deeper Linux Secret Service remediation now? (interactive actions, no copy/paste commands)",
+		initialValue: true
+	});
+	if (p.isCancel(shouldStart) || !shouldStart) return;
+	while (true) {
+		const action = await p.select({
+			message: "Choose next remediation action:",
+			options: [
+				{
+					value: "secret-tool-test",
+					label: hasSecretTool ? "Run Secret Service write/read/clear test now" : "Run Secret Service write/read/clear test now (secret-tool not found)"
+				},
+				{
+					value: "open-keyring-manager",
+					label: hasSeahorse ? "Open keyring manager now" : "Open keyring manager now (seahorse not found)"
+				},
+				{
+					value: "retry-probe",
+					label: "Retry cdx secure-store probe now"
+				},
+				{
+					value: "done",
+					label: "Done"
+				}
+			],
+			initialValue: "secret-tool-test"
+		});
+		if (p.isCancel(action) || action === "done") return;
+		if (action === "secret-tool-test") {
+			if (!hasSecretTool) {
+				process.stdout.write("    secret-tool is not installed; install it first, then rerun this remediation action.\n");
+				continue;
+			}
+			const result = await runSecretToolRoundTripCheck();
+			if (result.ok) process.stdout.write("    secret-tool roundtrip test passed.\n");
+			else process.stdout.write(`    secret-tool roundtrip test failed: ${result.details ?? "unknown error"}\n`);
+			continue;
+		}
+		if (action === "open-keyring-manager") {
+			if (!hasSeahorse) {
+				process.stdout.write("    keyring manager app was not found (seahorse). Install it to manage collections/locks interactively.\n");
+				continue;
+			}
+			const opened = await runCommandDetached("seahorse", []);
+			if (!opened.ok) process.stdout.write(`    failed to open keyring manager: ${opened.error ?? "unknown error"}\n`);
+			else process.stdout.write("    opened keyring manager. Unlock/create the default keyring, then return here and retry probe.\n");
+			continue;
+		}
+		const probeResult = await runSecretStoreWriteReadProbe(createProbeAdapterForCurrentPlatform());
+		if (probeResult.ok) {
+			process.stdout.write("    cdx secure-store probe now passes.\n");
+			return;
+		}
+		process.stdout.write(`    probe still failing (${probeResult.stage}): ${probeResult.error.message}\n`);
+	}
+};
 const maybeRunLinuxSecretStoreChecklist = async () => {
-	if (!isInteractiveTerminal()) {
+	if (!isInteractiveTerminal$1()) {
 		process.stdout.write("  Tip: run `cdx doctor` in an interactive terminal to start guided Linux secret-store checks.\n");
 		return;
 	}
@@ -3069,7 +3283,7 @@ const maybeRunLinuxSecretStoreChecklist = async () => {
 		if (item.hint) process.stdout.write(`      hint: ${item.hint}\n`);
 		if (item.id === "gnome-keyring-running") {
 			if (await maybeOfferToStartGnomeKeyring()) {
-				const runningNow = await checkGnomeKeyringRunning();
+				const runningNow = await checkGnomeKeyringRunning$1();
 				if (runningNow.ok) {
 					passed += 1;
 					process.stdout.write("      re-check: gnome-keyring-daemon is now running.\n");
@@ -3078,6 +3292,10 @@ const maybeRunLinuxSecretStoreChecklist = async () => {
 		}
 	}
 	process.stdout.write(`  Guided checklist summary: ${passed}/${checklist.length} checks passed.\n`);
+	if (passed === checklist.length) {
+		process.stdout.write("  Note: basic checks passed, but secure-store probe still failed. This can happen when the keyring is locked, has no default collection, or your D-Bus/session setup prevents Secret Service writes.\n");
+		await runLinuxSecretStoreDeepRemediation();
+	}
 };
 const registerDoctorCommand = (program) => {
 	program.command("doctor").description("Show auth file paths and runtime capabilities").option("--check-keychain-acl", "Run keychain trusted-app/ACL checks on macOS (can be slow)").action(async (options) => {
@@ -3192,7 +3410,6 @@ const registerDoctorCommand = (program) => {
 		}
 	});
 };
-
 //#endregion
 //#region lib/commands/help.ts
 const registerHelpCommand = (program) => {
@@ -3210,7 +3427,362 @@ const registerHelpCommand = (program) => {
 		program.outputHelp();
 	});
 };
-
+//#endregion
+//#region lib/commands/keyring.ts
+const APT_INSTALL_COMMAND = "sudo apt-get update && sudo apt-get install -y gnome-keyring libsecret-tools dbus-user-session xdg-utils libpam-gnome-keyring";
+const GNOME_KEYRING_CMDLINE_PATTERN = /(^|\/)gnome-keyring-daemon(\s|$)/;
+const isInteractiveTerminal = () => Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+const runCommandCapture = async (command, args) => await new Promise((resolve) => {
+	const child = spawn(command, args, { stdio: [
+		"ignore",
+		"pipe",
+		"pipe"
+	] });
+	let stdout = "";
+	let stderr = "";
+	let spawnError = null;
+	child.stdout?.on("data", (chunk) => {
+		stdout += chunk.toString();
+	});
+	child.stderr?.on("data", (chunk) => {
+		stderr += chunk.toString();
+	});
+	child.once("error", (error) => {
+		spawnError = error.message;
+	});
+	child.once("close", (code) => {
+		resolve({
+			ok: spawnError === null && code === 0,
+			stdout: stdout.trim(),
+			stderr: stderr.trim(),
+			...spawnError ? { error: spawnError } : {}
+		});
+	});
+});
+const runCommandInherit = async (command, args) => await new Promise((resolve) => {
+	const child = spawn(command, args, { stdio: "inherit" });
+	child.once("error", () => resolve(1));
+	child.once("close", (code) => resolve(code ?? 1));
+});
+const extractCommandFailureDetails = (result) => result.error || result.stderr || result.stdout || void 0;
+const isCommandAvailable = async (commandName) => {
+	return (await runCommandCapture("sh", ["-lc", `command -v ${commandName} >/dev/null 2>&1`])).ok;
+};
+const parseSystemctlEnabledState = (output) => {
+	const normalized = output.trim().toLowerCase();
+	if ([
+		"enabled",
+		"enabled-runtime",
+		"static",
+		"indirect",
+		"generated"
+	].includes(normalized)) return "enabled";
+	if ([
+		"disabled",
+		"masked",
+		"not-found",
+		"linked",
+		"linked-runtime"
+	].includes(normalized)) return "disabled";
+	return "unknown";
+};
+const applyEnvAssignments = (raw) => {
+	const lines = raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+	for (const line of lines) {
+		const match = line.match(/^([A-Z0-9_]+)=(.*);?$/);
+		if (!match) continue;
+		const key = match[1];
+		const value = match[2].replace(/;$/, "");
+		if (key) process.env[key] = value;
+	}
+};
+const checkGnomeKeyringRunning = async () => {
+	if (await isCommandAvailable("ps")) {
+		const psResult = await runCommandCapture("ps", [
+			"-A",
+			"-o",
+			"args="
+		]);
+		if (psResult.ok) {
+			if (psResult.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).some((line) => GNOME_KEYRING_CMDLINE_PATTERN.test(line))) return { ok: true };
+			return {
+				ok: false,
+				details: "No gnome-keyring-daemon process found."
+			};
+		}
+	}
+	if (await isCommandAvailable("pgrep")) {
+		const pgrepResult = await runCommandCapture("pgrep", ["-f", "gnome-keyring-daemon"]);
+		if (pgrepResult.ok) return { ok: true };
+		return {
+			ok: false,
+			details: extractCommandFailureDetails(pgrepResult) ?? "No gnome-keyring-daemon process found."
+		};
+	}
+	return {
+		ok: false,
+		details: "Neither ps nor pgrep is available to check gnome-keyring-daemon."
+	};
+};
+const getLinuxGnomeKeyringAutoStartStatus = async () => {
+	if (!await isCommandAvailable("systemctl")) return {
+		state: "unknown",
+		details: "systemctl is not available; autostart detection depends on your desktop/session config."
+	};
+	const units = ["gnome-keyring-daemon.socket", "gnome-keyring-daemon.service"];
+	let sawDisabled = false;
+	const details = [];
+	for (const unit of units) {
+		const result = await runCommandCapture("systemctl", [
+			"--user",
+			"is-enabled",
+			unit
+		]);
+		const state = parseSystemctlEnabledState(result.stdout || result.stderr);
+		if (state === "enabled") return {
+			state: "enabled",
+			details: `${unit} is enabled (${result.stdout || "enabled"}).`
+		};
+		if (state === "disabled") {
+			sawDisabled = true;
+			details.push(`${unit}: ${result.stdout || result.stderr || "disabled"}`);
+			continue;
+		}
+		const maybeDetail = extractCommandFailureDetails(result);
+		if (maybeDetail) details.push(`${unit}: ${maybeDetail}`);
+	}
+	if (sawDisabled) return {
+		state: "disabled",
+		details: details.join("; ")
+	};
+	return {
+		state: "unknown",
+		details: details.join("; ") || "Unable to determine gnome-keyring autostart state."
+	};
+};
+const startGnomeKeyringNow = async () => {
+	const directStart = await runCommandCapture("gnome-keyring-daemon", ["--start", "--components=secrets"]);
+	if (directStart.ok) {
+		applyEnvAssignments(directStart.stdout);
+		const runningCheck = await checkGnomeKeyringRunning();
+		if (runningCheck.ok) return { ok: true };
+		return {
+			ok: false,
+			details: runningCheck.details ?? "gnome-keyring-daemon start command succeeded, but process was not detected afterwards."
+		};
+	}
+	if (await isCommandAvailable("systemctl")) {
+		const serviceStart = await runCommandCapture("systemctl", [
+			"--user",
+			"start",
+			"gnome-keyring-daemon.service"
+		]);
+		if (serviceStart.ok) {
+			const runningCheck = await checkGnomeKeyringRunning();
+			if (runningCheck.ok) return { ok: true };
+			return {
+				ok: false,
+				details: runningCheck.details ?? "systemctl start succeeded, but gnome-keyring-daemon was not detected afterwards."
+			};
+		}
+		return {
+			ok: false,
+			details: extractCommandFailureDetails(directStart) ?? extractCommandFailureDetails(serviceStart) ?? "Failed to start gnome-keyring-daemon."
+		};
+	}
+	return {
+		ok: false,
+		details: extractCommandFailureDetails(directStart) ?? "Failed to start gnome-keyring-daemon."
+	};
+};
+const detectLinuxDistro = async () => {
+	try {
+		const pairs = (await readFile("/etc/os-release", "utf8")).split(/\r?\n/).map((line) => line.trim()).filter(Boolean).filter((line) => !line.startsWith("#")).map((line) => {
+			const idx = line.indexOf("=");
+			if (idx === -1) return null;
+			const key = line.slice(0, idx);
+			let value = line.slice(idx + 1);
+			value = value.replace(/^"|"$/g, "");
+			return {
+				key,
+				value
+			};
+		}).filter((entry) => Boolean(entry));
+		const map = new Map(pairs.map((entry) => [entry.key, entry.value]));
+		const id = (map.get("ID") ?? "unknown").toLowerCase();
+		return {
+			id,
+			idLike: (map.get("ID_LIKE") ?? "").toLowerCase().split(/\s+/).map((item) => item.trim()).filter(Boolean),
+			prettyName: map.get("PRETTY_NAME") ?? map.get("NAME") ?? id
+		};
+	} catch {
+		return {
+			id: "unknown",
+			idLike: [],
+			prettyName: "Unknown Linux"
+		};
+	}
+};
+const isDebianUbuntuMint = (distro) => {
+	if ([
+		"debian",
+		"ubuntu",
+		"linuxmint",
+		"mint"
+	].includes(distro.id)) return true;
+	return distro.idLike.some((item) => [
+		"debian",
+		"ubuntu",
+		"linuxmint",
+		"mint"
+	].includes(item));
+};
+const printChecklist = (title, items) => {
+	process.stdout.write(`${title}:\n`);
+	let passed = 0;
+	items.forEach((item, index) => {
+		if (item.ok) {
+			passed += 1;
+			process.stdout.write(`  ${index + 1}. ${item.question}: yes\n`);
+			return;
+		}
+		process.stdout.write(`  ${index + 1}. ${item.question}: no\n`);
+		if (item.details) process.stdout.write(`     details: ${item.details}\n`);
+		if (item.hint) process.stdout.write(`     hint: ${item.hint}\n`);
+	});
+	process.stdout.write(`  Summary: ${passed}/${items.length} checks passed.\n`);
+	return passed;
+};
+const runLinuxKeyringCheck = async (options = {}) => {
+	const distro = await detectLinuxDistro();
+	process.stdout.write("\nLinux keyring diagnostics:\n");
+	process.stdout.write(`  Distro: ${distro.prettyName} (id=${distro.id})\n`);
+	process.stdout.write(`  DBUS_SESSION_BUS_ADDRESS: ${process.env.DBUS_SESSION_BUS_ADDRESS ?? "<unset>"}\n`);
+	process.stdout.write(`  XDG_RUNTIME_DIR: ${process.env.XDG_RUNTIME_DIR ?? "<unset>"}\n`);
+	const gnomeKeyringInstalled = await isCommandAvailable("gnome-keyring-daemon");
+	const secretToolInstalled = await isCommandAvailable("secret-tool");
+	const xdgOpenInstalled = await isCommandAvailable("xdg-open");
+	const dbusSendInstalled = await isCommandAvailable("dbus-send");
+	const running = await checkGnomeKeyringRunning();
+	const autostart = await getLinuxGnomeKeyringAutoStartStatus();
+	const checklistPassed = printChecklist("\nDependency and runtime checks", [
+		{
+			question: "gnome-keyring-daemon installed",
+			ok: gnomeKeyringInstalled,
+			hint: "Install package: gnome-keyring"
+		},
+		{
+			question: "secret-tool installed",
+			ok: secretToolInstalled,
+			hint: "Install package: libsecret-tools"
+		},
+		{
+			question: "dbus-send installed",
+			ok: dbusSendInstalled,
+			hint: "Install package: dbus"
+		},
+		{
+			question: "xdg-open installed",
+			ok: xdgOpenInstalled,
+			hint: "Install package: xdg-utils"
+		},
+		{
+			question: "gnome-keyring-daemon running",
+			ok: running.ok,
+			details: running.details,
+			hint: "Start daemon: gnome-keyring-daemon --start --components=secrets"
+		}
+	]);
+	process.stdout.write("\nAutostart status:\n");
+	process.stdout.write(`  gnome-keyring autostart: ${autostart.state}`);
+	if (autostart.details) process.stdout.write(` (${autostart.details})`);
+	process.stdout.write("\n");
+	if (options.allowInteractiveStart !== false && isInteractiveTerminal() && gnomeKeyringInstalled && !running.ok) {
+		const shouldStart = await p.confirm({
+			message: "gnome-keyring-daemon is not running. Start it now for this session?",
+			initialValue: true
+		});
+		if (!p.isCancel(shouldStart) && shouldStart) {
+			const started = await startGnomeKeyringNow();
+			if (started.ok) process.stdout.write("  Started gnome-keyring-daemon for this session.\n");
+			else process.stdout.write(`  Failed to start gnome-keyring-daemon (${started.details ?? "unknown error"}).\n`);
+		}
+	}
+	process.stdout.write("\nSecret-store write/read/delete probe:\n");
+	const probeResult = await runSecretStoreWriteReadProbe(createRuntimeSecretStoreAdapter("linux"));
+	if (probeResult.ok) process.stdout.write("  write/read/delete probe: OK\n");
+	else {
+		process.stdout.write(`  ${probeResult.stage} failed: ${probeResult.error.message}\n`);
+		process.stdout.write("  Suggested fix: ensure Secret Service is running and unlocked (gnome-keyring + secret-tool), then run `cdx keyring check` again.\n");
+	}
+	const checksOk = checklistPassed === 5 && probeResult.ok;
+	process.stdout.write(`\nResult: ${checksOk ? "OK" : "NOT READY"}\n\n`);
+	return checksOk;
+};
+const runLinuxKeyringInstall = async (options) => {
+	const distro = await detectLinuxDistro();
+	process.stdout.write("\nLinux keyring setup:\n");
+	process.stdout.write(`  Distro: ${distro.prettyName} (id=${distro.id})\n`);
+	if (!isDebianUbuntuMint(distro)) {
+		process.stdout.write("\nAutomatic install is currently only implemented for Debian/Ubuntu/Mint.\n");
+		process.stdout.write("Install these packages manually, then run `cdx keyring check`:\n");
+		process.stdout.write("  - gnome-keyring\n");
+		process.stdout.write("  - libsecret-tools\n");
+		process.stdout.write("  - dbus-user-session\n");
+		process.stdout.write("  - xdg-utils\n");
+		process.stdout.write("  - libpam-gnome-keyring (optional, for PAM auto-unlock)\n\n");
+		return;
+	}
+	process.stdout.write("\nInstall command:\n");
+	process.stdout.write(`  ${APT_INSTALL_COMMAND}\n`);
+	let shouldRun = true;
+	if (!options.yes) {
+		if (!isInteractiveTerminal()) {
+			process.stdout.write("\nNon-interactive terminal detected. Re-run with --yes to execute install automatically.\n\n");
+			return;
+		}
+		const confirmed = await p.confirm({
+			message: "Run this install command now?",
+			initialValue: true
+		});
+		shouldRun = !p.isCancel(confirmed) && confirmed;
+	}
+	if (!shouldRun) {
+		process.stdout.write("\nInstall skipped.\n\n");
+		return;
+	}
+	const exitCode = await runCommandInherit("sh", ["-lc", APT_INSTALL_COMMAND]);
+	if (exitCode !== 0) throw new Error(`Install command failed with exit code ${exitCode}.`);
+	process.stdout.write("\nInstall completed.\n");
+	if (!options.skipCheck) {
+		if (!await runLinuxKeyringCheck({ allowInteractiveStart: true })) process.exitCode = 1;
+	} else process.stdout.write("Run `cdx keyring check` to verify setup.\n\n");
+};
+const registerKeyringCommand = (program) => {
+	const keyring = program.command("keyring").description("Setup and diagnose Linux gnome-keyring/Secret Service support");
+	keyring.command("check").description("Run focused Linux keyring dependency and probe checks").action(async () => {
+		try {
+			if (process.platform !== "linux") {
+				process.stdout.write("This command currently targets Linux only.\n\n");
+				return;
+			}
+			if (!await runLinuxKeyringCheck({ allowInteractiveStart: true })) process.exitCode = 1;
+		} catch (error) {
+			exitWithCommandError(error);
+		}
+	});
+	keyring.command("install").description("Install gnome-keyring dependencies on Debian/Ubuntu/Mint").option("--yes", "Run installation without interactive confirmation").option("--skip-check", "Skip automatic post-install verification").action(async (options) => {
+		try {
+			if (process.platform !== "linux") {
+				process.stdout.write("This command currently targets Linux only.\n\n");
+				return;
+			}
+			await runLinuxKeyringInstall(options);
+		} catch (error) {
+			exitWithCommandError(error);
+		}
+	});
+};
 //#endregion
 //#region lib/commands/label.ts
 const registerLabelCommand = (program) => {
@@ -3231,7 +3803,6 @@ const registerLabelCommand = (program) => {
 		}
 	});
 };
-
 //#endregion
 //#region lib/commands/login.ts
 const registerLoginCommand = (program, deps = {}) => {
@@ -3247,7 +3818,6 @@ const registerLoginCommand = (program, deps = {}) => {
 		}
 	});
 };
-
 //#endregion
 //#region lib/secrets/migrate.ts
 const asErrorMessage = (error) => error instanceof Error ? error.message : String(error);
@@ -3330,7 +3900,6 @@ const migrateLegacyMacOSSecrets = async (options = {}) => {
 		accountResults
 	};
 };
-
 //#endregion
 //#region lib/commands/migrate-secrets.ts
 const statusPrefix = (result) => {
@@ -3360,7 +3929,6 @@ const registerMigrateSecretsCommand = (program) => {
 		}
 	});
 };
-
 //#endregion
 //#region lib/commands/output.ts
 const formatCodexMark = (result) => {
@@ -3384,7 +3952,6 @@ const writeUpdatedAuthSummary = (result) => {
 	process.stdout.write(`  Pi Agent:  ${piMark}\n`);
 	process.stdout.write(`  Codex CLI: ${codexMark}\n`);
 };
-
 //#endregion
 //#region lib/commands/refresh.ts
 const registerReloginCommand = (program) => {
@@ -3420,7 +3987,6 @@ const registerReloginCommand = (program) => {
 		}
 	});
 };
-
 //#endregion
 //#region lib/usage.ts
 const USAGE_ENDPOINT = "https://chatgpt.com/backend-api/wham/usage";
@@ -3577,7 +4143,6 @@ const formatUsageOverview = (entries) => {
 	}
 	return lines.join("\n");
 };
-
 //#endregion
 //#region lib/commands/status.ts
 const registerStatusCommand = (program) => {
@@ -3636,7 +4201,6 @@ const registerStatusCommand = (program) => {
 		}
 	});
 };
-
 //#endregion
 //#region lib/commands/switch.ts
 const switchNext = async () => {
@@ -3671,7 +4235,6 @@ const registerSwitchCommand = (program) => {
 		}
 	});
 };
-
 //#endregion
 //#region lib/commands/usage.ts
 const registerUsageCommand = (program) => {
@@ -3711,7 +4274,6 @@ const registerUsageCommand = (program) => {
 		}
 	});
 };
-
 //#endregion
 //#region lib/runtime/update-manager.ts
 const detectRuntime = (input = {}) => {
@@ -3793,7 +4355,6 @@ const buildUpdateInstallCommand = (manager, packageName) => {
 		]
 	};
 };
-
 //#endregion
 //#region lib/commands/update-self.ts
 const PACKAGE_NAME = "@bjesuiter/codex-switcher";
@@ -3939,7 +4500,6 @@ const registerUpdateSelfCommand = (program) => {
 		}
 	});
 };
-
 //#endregion
 //#region lib/commands/version.ts
 const registerVersionCommand = (program, version) => {
@@ -3947,7 +4507,6 @@ const registerVersionCommand = (program, version) => {
 		process.stdout.write(`${version}\n`);
 	});
 };
-
 //#endregion
 //#region cdx.ts
 const interactiveMode = runInteractiveMode;
@@ -4056,6 +4615,7 @@ const createProgram = (deps = {}) => {
 	registerSwitchCommand(program);
 	registerLabelCommand(program);
 	registerMigrateSecretsCommand(program);
+	registerKeyringCommand(program);
 	registerStatusCommand(program);
 	registerDoctorCommand(program);
 	registerUsageCommand(program);
@@ -4079,6 +4639,5 @@ const main = async () => {
 if (import.meta.main) main().catch((error) => {
 	exitWithCommandError(error);
 });
-
 //#endregion
-export { createProgram, createRuntimeSecretStoreAdapter, createSecretStoreAdapterFromSelection, createTestPaths, getMacOSKeychainPromptWarning, getPaths, getSecretStoreAdapter, interactiveMode, loadConfig, resetPaths, resetSecretStoreAdapter, resolveMacOSCrossKeychainBackendId, runInteractiveMode, saveConfig, setPaths, setSecretStoreAdapter, switchNext, switchToAccount, writeAllAuthFiles, writeAuthFile, writeCodexAuthFile, writePiAuthFile };
+export { createProgram, createRuntimeSecretStoreAdapter, createSecretStoreAdapterFromSelection, createTestPaths, getMacOSKeychainPromptWarning, getPaths, getSecretStoreAdapter, interactiveMode, loadConfig, resetPaths, resetSecretStoreAdapter, resolveMacOSCrossKeychainBackendId, runInteractiveMode, saveConfig, setPaths, setSecretStoreAdapter, switchNext, switchToAccount, writeAllAuthFiles, writeAuthFile, writeCodexAuthFile, writePiAuthFile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bjesuiter/codex-switcher",
-  "version": "1.8.4",
+  "version": "1.8.6",
   "type": "module",
   "description": "CLI tool to switch between multiple OpenAI accounts for OpenCode",
   "bin": {
@@ -21,8 +21,8 @@
   "author": "bjesuiter",
   "dependencies": {
     "@bjesuiter/cross-keychain": "1.1.0-jb.0",
-    "@bomb.sh/tab": "^0.0.13",
-    "@clack/prompts": "^1.0.0",
+    "@bomb.sh/tab": "^0.0.14",
+    "@clack/prompts": "^1.1.0",
     "@openauthjs/openauth": "^0.4.3",
     "age-encryption": "^0.3.0",
     "commander": "^14.0.3"