add-manual-login-mode-for-headless-auth-flows

Author: ndycode

docs/reference/commands.md

@@ -45,6 +45,7 @@ Compatibility aliases are supported:
 
 | Flag | Applies to | Meaning |
 | --- | --- | --- |
+| `--manual`, `--no-browser` | login | Skip browser launch and use manual callback flow |
 | `--json` | verify-flagged, forecast, report, fix, doctor | Print machine-readable output |
 | `--live` | forecast, report, fix | Use live probe before decisions/output |
 | `--dry-run` | verify-flagged, fix, doctor | Preview without writing storage |
@@ -60,6 +61,7 @@ Compatibility aliases are supported:
 - `codex` remains the primary wrapper entrypoint. It routes `codex auth ...` and the compatibility aliases to the multi-auth runtime, and forwards every other command to the official `@openai/codex` CLI.
 - In non-TTY or host-managed sessions, including `CODEX_TUI=1`, `CODEX_DESKTOP=1`, `TERM_PROGRAM=codex`, or `ELECTRON_RUN_AS_NODE=1`, auth flows degrade to deterministic text behavior.
 - The non-TTY fallback keeps `codex auth login` predictable: it defaults to add-account mode, skips the extra "add another account" prompt, and auto-picks the default workspace selection when a follow-up choice is needed.
+- `codex auth login --manual` keeps the login flow usable in browser-restricted shells by printing the OAuth URL and accepting manual callback input instead of trying to open a browser.
 
 ---
 

index.ts

@@ -34,7 +34,7 @@ import {
         REDIRECT_URI,
 } from "./lib/auth/auth.js";
 import { queuedRefresh } from "./lib/refresh-queue.js";
-import { openBrowserUrl } from "./lib/auth/browser.js";
+import { isBrowserLaunchSuppressed, openBrowserUrl } from "./lib/auth/browser.js";
 import { startLocalOAuthServer } from "./lib/auth/server.js";
 import { promptAddAnotherAccount, promptLoginMode } from "./lib/cli.js";
 import {
@@ -2386,9 +2386,10 @@ while (attempted.size < Math.max(1, accountCount)) {
 
 							const accounts: TokenSuccessWithAccount[] = [];
 							const noBrowser =
+								inputs?.manual === "true" ||
 								inputs?.noBrowser === "true" ||
 								inputs?.["no-browser"] === "true";
-							const useManualMode = noBrowser;
+							const useManualMode = noBrowser || isBrowserLaunchSuppressed();
 							const explicitLoginMode =
 								inputs?.loginMode === "fresh" || inputs?.loginMode === "add"
 									? inputs.loginMode

lib/auth/browser.ts

@@ -8,6 +8,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { PLATFORM_OPENERS } from "../constants.js";
 
+const BROWSER_DISABLED_VALUES = new Set(["0", "false", "no", "off", "none"]);
+
 /**
  * Gets the platform-specific command to open a URL in the default browser
  * @returns Browser opener command for the current platform
@@ -19,6 +21,16 @@ export function getBrowserOpener(): string {
 	return PLATFORM_OPENERS.linux;
 }
 
+export function isBrowserLaunchSuppressed(): boolean {
+	const explicitNoBrowser = (process.env.CODEX_AUTH_NO_BROWSER ?? "").trim().toLowerCase();
+	if (explicitNoBrowser === "1" || BROWSER_DISABLED_VALUES.has(explicitNoBrowser)) {
+		return true;
+	}
+
+	const browserSetting = (process.env.BROWSER ?? "").trim().toLowerCase();
+	return BROWSER_DISABLED_VALUES.has(browserSetting);
+}
+
 /**
  * Determines whether a given command name exists on the system PATH.
  *
@@ -92,6 +104,10 @@ function commandExists(command: string): boolean {
  */
 export function openBrowserUrl(url: string): boolean {
 	try {
+		if (isBrowserLaunchSuppressed()) {
+			return false;
+		}
+
 		// Windows: use PowerShell Start-Process to avoid cmd/start quirks with URLs containing '&' or ':'
 		if (process.platform === "win32") {
 			if (!commandExists("powershell.exe")) {

lib/codex-manager.ts

@@ -9,7 +9,7 @@ import {
 	REDIRECT_URI,
 } from "./auth/auth.js";
 import { startLocalOAuthServer } from "./auth/server.js";
-import { copyTextToClipboard, openBrowserUrl } from "./auth/browser.js";
+import { copyTextToClipboard, isBrowserLaunchSuppressed, openBrowserUrl } from "./auth/browser.js";
 import { promptAddAnotherAccount, promptLoginMode, type ExistingAccountInfo } from "./cli.js";
 import {
 	extractAccountEmail,
@@ -291,7 +291,7 @@ function printUsage(): void {
 			"Codex Multi-Auth CLI",
 			"",
 			"Usage:",
-			"  codex auth login",
+			"  codex auth login [--manual|--no-browser]",
 			"  codex auth list",
 			"  codex auth status",
 			"  codex auth switch <index>",
@@ -311,6 +311,37 @@ function printUsage(): void {
 	);
 }
 
+type AuthLoginOptions = {
+	manual: boolean;
+};
+
+type ParsedAuthLoginArgs =
+	| { ok: true; options: AuthLoginOptions }
+	| { ok: false; message: string };
+
+function parseAuthLoginArgs(args: string[]): ParsedAuthLoginArgs {
+	const options: AuthLoginOptions = {
+		manual: false,
+	};
+
+	for (const arg of args) {
+		if (arg === "--manual" || arg === "--no-browser") {
+			options.manual = true;
+			continue;
+		}
+		if (arg === "--help" || arg === "-h") {
+			printUsage();
+			return { ok: false, message: "" };
+		}
+		return {
+			ok: false,
+			message: `Unknown login option: ${arg}`,
+		};
+	}
+
+	return { ok: true, options };
+}
+
 interface ImplementedFeature {
 	id: number;
 	name: string;
@@ -1095,16 +1126,22 @@ function applyTokenAccountIdentity(
 	return true;
 }
 
-async function promptManualCallback(state: string): Promise<string | null> {
-	if (!input.isTTY || !output.isTTY) {
+async function promptManualCallback(
+	state: string,
+	options: { allowNonTty?: boolean } = {},
+): Promise<string | null> {
+	const useInteractivePrompt = input.isTTY && output.isTTY;
+	if (!useInteractivePrompt && !options.allowNonTty) {
 		return null;
 	}
 
 	const rl = createInterface({ input, output });
 	try {
-		console.log("");
-		console.log(stylePromptText(UI_COPY.oauth.pastePrompt, "accent"));
-		const answer = await rl.question("◆  ");
+		if (useInteractivePrompt) {
+			console.log("");
+			console.log(stylePromptText(UI_COPY.oauth.pastePrompt, "accent"));
+		}
+		const answer = await rl.question(useInteractivePrompt ? "◆  " : "");
 		if (answer.includes("\u001b")) {
 			return null;
 		}
@@ -1425,12 +1462,21 @@ async function runActionPanel(
 	}
 }
 
-async function runOAuthFlow(forceNewLogin: boolean): Promise<TokenResult> {
+async function runOAuthFlow(
+	forceNewLogin: boolean,
+	options: AuthLoginOptions = { manual: false },
+): Promise<TokenResult> {
 	const { pkce, state, url } = await createAuthorizationFlow({ forceNewLogin });
-	const oauthServer = await startLocalOAuthServer({ state });
+	const preferManualMode = options.manual || isBrowserLaunchSuppressed();
+	let oauthServer: Awaited<ReturnType<typeof startLocalOAuthServer>> | null = null;
+	try {
+		oauthServer = await startLocalOAuthServer({ state });
+	} catch {
+		oauthServer = null;
+	}
 	let code: string | null = null;
 	try {
-		const signInMode = await promptOAuthSignInMode();
+		const signInMode = preferManualMode ? "manual" : await promptOAuthSignInMode();
 		if (signInMode === "cancel") {
 			return {
 				type: "failed",
@@ -1465,18 +1511,23 @@ async function runOAuthFlow(forceNewLogin: boolean): Promise<TokenResult> {
 			);
 		}
 
-		if (oauthServer.ready) {
+		if (oauthServer?.ready) {
 			console.log(stylePromptText(UI_COPY.oauth.waitingCallback, "muted"));
 			const callbackResult = await oauthServer.waitForCode(state);
 			code = callbackResult?.code ?? null;
 		}
 
 		if (!code) {
-			console.log(stylePromptText(UI_COPY.oauth.callbackMissed, "warning"));
-			code = await promptManualCallback(state);
+			console.log(
+				stylePromptText(
+					oauthServer?.ready ? UI_COPY.oauth.callbackMissed : UI_COPY.oauth.callbackUnavailable,
+					"warning",
+				),
+			);
+			code = await promptManualCallback(state, { allowNonTty: preferManualMode });
 		}
 	} finally {
-		oauthServer.close();
+		oauthServer?.close();
 	}
 
 	if (!code) {
@@ -4099,7 +4150,7 @@ async function handleManageAction(
 		const existing = storage.accounts[idx];
 		if (!existing) return;
 
-		const tokenResult = await runOAuthFlow(true);
+		const tokenResult = await runOAuthFlow(true, { manual: false });
 		if (tokenResult.type !== "success") {
 			console.error(`Refresh failed: ${tokenResult.message ?? tokenResult.reason ?? "unknown error"}`);
 			return;
@@ -4112,7 +4163,18 @@ async function handleManageAction(
 	}
 }
 
-async function runAuthLogin(): Promise<number> {
+async function runAuthLogin(args: string[]): Promise<number> {
+	const parsedArgs = parseAuthLoginArgs(args);
+	if (!parsedArgs.ok) {
+		if (parsedArgs.message) {
+			console.error(parsedArgs.message);
+			printUsage();
+			return 1;
+		}
+		return 0;
+	}
+
+	const loginOptions = parsedArgs.options;
 	setStoragePath(null);
 	let pendingMenuQuotaRefresh: Promise<void> | null = null;
 	let menuQuotaRefreshStatus: string | undefined;
@@ -4231,7 +4293,7 @@ async function runAuthLogin(): Promise<number> {
 		const existingCount = refreshedStorage?.accounts.length ?? 0;
 		let forceNewLogin = existingCount > 0;
 		while (true) {
-			const tokenResult = await runOAuthFlow(forceNewLogin);
+			const tokenResult = await runOAuthFlow(forceNewLogin, loginOptions);
 			if (tokenResult.type !== "success") {
 				if (isUserCancelledOAuth(tokenResult)) {
 					if (existingCount > 0) {
@@ -4719,7 +4781,7 @@ export async function runCodexMultiAuthCli(rawArgs: string[]): Promise<number> {
 		return 0;
 	}
 	if (command === "login") {
-		return runAuthLogin();
+		return runAuthLogin(rest);
 	}
 	if (command === "list" || command === "status") {
 		await showAccountStatus();

lib/ui/copy.ts

@@ -42,6 +42,7 @@ export const UI_COPY = {
 		browserOpened: "Browser opened.",
 		browserOpenFail: "Could not open browser. Use this link:",
 		waitingCallback: "Waiting for login callback on localhost:1455...",
+		callbackUnavailable: "Callback listener unavailable. Paste the callback URL manually.",
 		callbackMissed: "No callback received. Paste manually.",
 		cancelled: "Sign-in cancelled.",
 		cancelledBackToMenu: "Sign-in cancelled. Going back to menu.",

test/browser.test.ts

@@ -1,7 +1,12 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { spawn } from "node:child_process";
 import fs from "node:fs";
-import { getBrowserOpener, openBrowserUrl, copyTextToClipboard } from "../lib/auth/browser.js";
+import {
+	getBrowserOpener,
+	isBrowserLaunchSuppressed,
+	openBrowserUrl,
+	copyTextToClipboard,
+} from "../lib/auth/browser.js";
 import { PLATFORM_OPENERS } from "../lib/constants.js";
 
 vi.mock("node:child_process", () => ({
@@ -37,6 +42,7 @@ describe("auth browser utilities", () => {
 	const originalPlatform = process.platform;
 	const originalPath = process.env.PATH;
 	const originalPathExt = process.env.PATHEXT;
+	const originalNoBrowser = process.env.CODEX_AUTH_NO_BROWSER;
 
 	beforeEach(() => {
 		vi.clearAllMocks();
@@ -53,6 +59,8 @@ describe("auth browser utilities", () => {
 		else process.env.PATH = originalPath;
 		if (originalPathExt === undefined) delete process.env.PATHEXT;
 		else process.env.PATHEXT = originalPathExt;
+		if (originalNoBrowser === undefined) delete process.env.CODEX_AUTH_NO_BROWSER;
+		else process.env.CODEX_AUTH_NO_BROWSER = originalNoBrowser;
 	});
 
 	it("returns platform opener command", () => {
@@ -65,6 +73,14 @@ describe("auth browser utilities", () => {
 	});
 
 	describe("openBrowserUrl", () => {
+		it("returns false when browser launch is suppressed by environment", () => {
+			process.env.CODEX_AUTH_NO_BROWSER = "1";
+
+			expect(isBrowserLaunchSuppressed()).toBe(true);
+			expect(openBrowserUrl("https://example.com")).toBe(false);
+			expect(mockedSpawn).not.toHaveBeenCalled();
+		});
+
 		it("returns false on win32 when powershell.exe is unavailable", () => {
 			Object.defineProperty(process, "platform", { value: "win32" });
 			process.env.PATH = "C:\\missing";