add manual login mode for headless auth flows

README.md

@@ -109,6 +109,21 @@ codex auth fix --dry-run
 codex auth doctor --fix
 ```
 
+If the shell should not launch a browser, use the manual callback flow:
+
+```bash
+codex auth login --manual
+CODEX_AUTH_NO_BROWSER=1 codex auth login
+```
+
+In non-TTY/manual shells, provide the full redirect URL on stdin instead of waiting for a browser callback:
+
+```bash
+echo "http://127.0.0.1:1455/auth/callback?code=..." | codex auth login --manual
+```
+
+No new npm scripts or storage migration steps are required for this login-flow update.
+
 ---
 
 ## Command Toolkit
@@ -234,6 +249,7 @@ codex auth login
 - `codex auth` unrecognized: run `where codex`, then follow `docs/troubleshooting.md` for routing fallback commands
 - Switch succeeds but wrong account appears active: run `codex auth switch <index>`, then restart session
 - OAuth callback on port `1455` fails: free the port and re-run `codex auth login`
+- Browser launch is blocked or you are in a headless shell: re-run `codex auth login --manual` or set `CODEX_AUTH_NO_BROWSER=1`
 - `missing field id_token` / `token_expired` / `refresh_token_reused`: re-login affected account
 
 </details>

docs/features.md

@@ -54,7 +54,9 @@ User-facing capability map for `codex-multi-auth`.
 | Quick switch and search hotkeys | Faster navigation in the dashboard |
 | Account action hotkeys | Per-account set, refresh, toggle, and delete shortcuts |
 | In-dashboard settings hub | Runtime and display tuning without editing files directly |
-| Browser-first OAuth with manual fallback | Works in normal and constrained terminal environments |
+| Browser-first OAuth with manual fallback | `codex auth login` stays browser-first, while `--manual`, `--no-browser`, and `CODEX_AUTH_NO_BROWSER=1` keep login usable in browser-restricted shells |
+
+Manual/non-TTY login accepts the full callback URL on stdin, so automation and host-managed shells can complete auth without relying on a local browser handoff.
 
 ---
 

docs/getting-started.md

@@ -56,6 +56,21 @@ codex auth list
 codex auth check
 ```
 
+If browser launch is blocked or you want to handle the callback manually:
+
+```bash
+codex auth login --manual
+CODEX_AUTH_NO_BROWSER=1 codex auth login
+```
+
+In non-TTY/manual shells, provide the full redirect URL on stdin:
+
+```bash
+echo "http://127.0.0.1:1455/auth/callback?code=..." | codex auth login --manual
+```
+
+`codex auth login` remains browser-first by default. No new npm scripts or storage migration steps are required for this auth-flow update.
+
 ---
 
 ## Add More Accounts
@@ -111,6 +126,7 @@ If the OAuth callback on port `1455` fails:
 
 - stop the process using port `1455`
 - rerun `codex auth login`
+- if browser launch is unavailable, rerun `codex auth login --manual`
 
 If account state looks stale:
 

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 |
@@ -55,11 +56,23 @@ Compatibility aliases are supported:
 
 ---
 
+## Upgrade Notes
+
+- `codex auth login` remains browser-first by default.
+- `codex auth login --manual` and `codex auth login --no-browser` force the manual callback flow instead of launching a browser.
+- `CODEX_AUTH_NO_BROWSER=1` suppresses browser launch for automation/headless sessions. False-like values such as `0` and `false` do not disable browser launch by themselves.
+- In non-TTY/manual shells, pass the full redirect URL on stdin, for example: `echo "http://127.0.0.1:1455/auth/callback?code=..." | codex auth login --manual`.
+- No new npm scripts or storage migration steps were introduced for this auth-flow update.
+
+---
+
 ## Compatibility and Non-TTY Behavior
 
 - `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.
+- In non-TTY/manual shells, provide the full redirect URL on stdin, for example: `echo "http://127.0.0.1:1455/auth/callback?code=..." | codex auth login --manual`.
 
 ---
 

docs/upgrade.md

@@ -49,6 +49,18 @@ codex auth forecast --live --model gpt-5-codex
 
 ---
 
+## Login Flow Upgrade Notes
+
+- `codex auth login` remains the default browser-first path.
+- `codex auth login --manual` and `codex auth login --no-browser` force manual callback handling for browser-restricted shells.
+- `CODEX_AUTH_NO_BROWSER=1` suppresses browser launch for automation/headless sessions. False-like values such as `0` and `false` no longer force manual mode.
+- In non-TTY/manual shells, provide the full redirect URL on stdin, for example: `echo "http://127.0.0.1:1455/auth/callback?code=..." | codex auth login --manual`.
+- No new npm scripts, storage migrations, or extra upgrade steps were introduced for this auth-flow change.
+
+For the full command/behavior reference, see [reference/commands.md](reference/commands.md).
+
+---
+
 ## Configuration Upgrade Notes
 
 During upgrades, runtime config source precedence is:

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,9 @@ 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"]);
+const NO_BROWSER_TRUTHY_VALUES = new Set(["1", "true", "yes", "on"]);
+
 /**
  * Gets the platform-specific command to open a URL in the default browser
  * @returns Browser opener command for the current platform
@@ -19,6 +22,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.length > 0) {
+		return NO_BROWSER_TRUTHY_VALUES.has(explicitNoBrowser);
+	}
+
+	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 +105,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")) {