ndycode · ndycode · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026
@@ -7,13 +7,13 @@
 
 Multi-account OAuth for the official `@openai/codex` CLI.
 
-`codex-multi-auth` adds a local account manager, `codex auth ...` workflow, and recovery tooling on top of the official Codex CLI. It keeps the normal `codex` command path intact, makes account switching explicit, and can optionally power a plugin runtime with account rotation and failover.
+`codex-multi-auth` adds a local account manager, `codex auth ...` workflow, backup and recovery tooling, and a productized settings surface on top of the official Codex CLI. It keeps the normal `codex` command path intact, makes account switching explicit, and can optionally power a plugin runtime with account rotation and failover.
 
 - Uses the official `@openai/codex` CLI instead of replacing it
 - Adds `codex auth login`, `list`, `switch`, `check`, `forecast`, `report`, `fix`, and `doctor`
 - Stores accounts locally, including project-scoped account pools for repo-specific workflows
-- Provides an interactive terminal dashboard for login, switching, and settings
-- Includes recovery and health tooling for stale tokens, bad sync state, and routing problems
+- Provides an interactive terminal dashboard for login, restore, switching, sync preview, and settings
+- Includes recovery and diagnostics tooling for stale tokens, backup restore, bad sync state, and routing problems
 
 ## Quick Example
 
@@ -52,8 +52,10 @@ This project wraps the official `codex` binary and intercepts the account-manage
 That gives you a stable workflow for:
 
 - signing into more than one ChatGPT-authenticated Codex account
+- restoring recoverable named backups before starting a fresh login
 - switching the active account by index instead of by hidden state
 - checking account health before a session
+- previewing Codex CLI account sync before applying one-way changes
 - repairing common local auth and storage problems
 - keeping separate project-level account pools when needed
 
@@ -64,10 +66,13 @@ The official Codex CLI is the right base tool, but a single opaque auth state is
 ## Features
 
 - Multi-account OAuth login through the official browser-based flow
+- Backup restore manager for recoverable named backups in `~/.codex/multi-auth/backups/`
 - Canonical `codex auth ...` command family for day-to-day account operations
-- Interactive dashboard with quick switch, search, and settings
+- Interactive dashboard with quick switch, search, restore, sync center, and settings
 - Project-scoped storage under `~/.codex/multi-auth/projects/<project-key>/...`
+- Startup recovery prompt that offers restore before OAuth when recoverable named backups are available
 - Health checks, flagged-account verification, live forecast, JSON reports, and safe repair commands
+- Settings split into stable everyday preferences and advanced operator controls
 - Optional plugin runtime for request transformation, token refresh, retry, failover, session affinity, and quota-aware account selection
 
 ## Example Usage
@@ -95,6 +100,11 @@ codex auth fix --live --model gpt-5-codex
 codex auth doctor --fix
 ```
 
+Open the interactive restore and sync workflows:
+
+- `codex auth login` -> `Restore From Backup`
+- `codex auth login` -> `Settings` -> `Codex CLI Sync`
+
 ## Architecture / How It Works
 
 1. `scripts/codex.js` becomes the `codex` wrapper entrypoint.
@@ -108,10 +118,12 @@ For a short public overview, see [docs/architecture.md](docs/architecture.md). F
 ## Common Workflows
 
 - First login: `codex auth login`
+- Restore recoverable named backups before a fresh login: `codex auth login`, then confirm the startup restore prompt or choose `Restore From Backup`
 - Review the saved account pool: `codex auth list`
 - Verify account health before coding: `codex auth check`
 - Choose the best account for the next run: `codex auth forecast --live`
 - Switch the active account explicitly: `codex auth switch <index>`
+- Preview one-way Codex CLI sync with rollback context: `codex auth login` -> `Settings` -> `Codex CLI Sync`
 - Gather machine-readable diagnostics: `codex auth report --live --json`
 - Repair local state safely: `codex auth fix --dry-run` or `codex auth doctor --fix`
 
@@ -180,6 +192,7 @@ Common first-run issues:
 - OAuth callback on port `1455` fails: free the port and retry `codex auth login`
 - The wrong account stays active after a switch: rerun `codex auth switch <index>` and restart the session
 - A worktree asks you to log in again: run `codex auth list` once in that worktree to trigger repo-shared storage migration
+- You expected a restore prompt but got OAuth instead: place named backup files in `~/.codex/multi-auth/backups/`, then rerun `codex auth login` in an interactive terminal
 
 Full recovery guidance lives in [docs/troubleshooting.md](docs/troubleshooting.md).
 

@@ -17,13 +17,13 @@ Public documentation for `codex-multi-auth`.
 
 | Document | Focus |
 | --- | --- |
-| [index.md](index.md) | Daily-use landing page for common `codex auth ...` workflows |
-| [getting-started.md](getting-started.md) | Install, first login, and first health check |
+| [index.md](index.md) | Daily-use landing page for login, restore, sync, and diagnostics workflows |
+| [getting-started.md](getting-started.md) | Install, first login, startup restore prompt, and first health check |
 | [faq.md](faq.md) | Short answers to common adoption questions |
 | [architecture.md](architecture.md) | Public system overview of the wrapper, storage, and optional plugin runtime |
-| [features.md](features.md) | User-facing capability map |
+| [features.md](features.md) | User-facing capability map, including backup restore, sync center, and settings split |
 | [configuration.md](configuration.md) | Stable defaults, precedence, and environment overrides |
-| [troubleshooting.md](troubleshooting.md) | Recovery playbooks for install, login, switching, and stale state |
+| [troubleshooting.md](troubleshooting.md) | Recovery playbooks for install, login, restore, sync, and stale state |
 | [privacy.md](privacy.md) | Data handling and local storage behavior |
 | [upgrade.md](upgrade.md) | Migration from legacy package and path history |
 | [releases/v0.1.7.md](releases/v0.1.7.md) | Stable release notes |
@@ -37,8 +37,8 @@ Public documentation for `codex-multi-auth`.
 
 | Document | Focus |
 | --- | --- |
-| [reference/commands.md](reference/commands.md) | Commands, flags, and hotkeys |
-| [reference/settings.md](reference/settings.md) | Dashboard and runtime settings |
+| [reference/commands.md](reference/commands.md) | Commands, flags, hotkeys, and interactive entry points |
+| [reference/settings.md](reference/settings.md) | Everyday settings, sync center, and advanced operator controls |
 | [reference/storage-paths.md](reference/storage-paths.md) | Canonical and compatibility storage paths |
 | [reference/public-api.md](reference/public-api.md) | Public API stability and semver contract |
 | [reference/error-contracts.md](reference/error-contracts.md) | CLI, JSON, and helper error semantics |

@@ -9,6 +9,8 @@ User-facing capability map for `codex-multi-auth`.
 | Capability | What it gives you | Primary entry |
 | --- | --- | --- |
 | Multi-account dashboard login | Add and manage multiple OAuth identities from one terminal flow | `codex auth login` |
+| Startup recovery prompt | Offer restore before OAuth when recoverable named backups are found and no active accounts exist | `codex auth login` |
+| Backup restore manager | Review named backups, merge with dedupe, and skip invalid or over-limit restores | `codex auth login` -> `Restore From Backup` |
 | Account dedupe and identity normalization | Avoid duplicate saved account rows | login flow |
 | Explicit active-account switching | Pick the current account by index instead of relying on hidden state | `codex auth switch <index>` |
 | Fast and deep health checks | See whether the current pool is usable before a coding session | `codex auth check` |
@@ -32,6 +34,7 @@ User-facing capability map for `codex-multi-auth`.
 | --- | --- | --- |
 | Safe repair workflow | Detects and repairs known local storage inconsistencies | `codex auth fix` |
 | Diagnostics with optional repair | One command to inspect and optionally fix common failures | `codex auth doctor` |
+| JSON diagnostics pack | Machine-readable state for support, bug reports, and deeper inspection | `codex auth report --live --json` |
 | Backup and WAL recovery | Safer persistence when local writes are interrupted or partially applied | storage runtime |
 
 ---
@@ -53,6 +56,8 @@ 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 |
+| Productized settings split | Keeps `Everyday Settings` separate from `Advanced & Operator` controls |
+| Preview-first sync center | Shows one-way Codex CLI sync results and rollback context before apply |
 | 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 |
 

@@ -49,6 +49,8 @@ Expected flow:
 4. Return to the terminal when the browser step completes.
 5. Confirm the account appears in the saved account list.
 
+If you have named backups in `~/.codex/multi-auth/backups/` and no active accounts, the login flow can prompt you to restore before opening OAuth. Confirm to open `Restore From Backup`, review the recoverable backup list, and restore the entries you want. Skip the prompt to continue with a fresh login.
+
 Verify the new account:
 
 ```bash
@@ -70,6 +72,29 @@ codex auth forecast --live
 
 ---
 
+## Restore Or Start Fresh
+
+Use the restore path when you already have named backup files and want to recover account state before creating new OAuth sessions.
+
+- Automatic path: run `codex auth login`, then confirm the startup restore prompt when it appears
+- Manual path: run `codex auth login`, then choose `Restore From Backup`
+- Backup location: `~/.codex/multi-auth/backups/<name>.json`
+
+The restore manager shows each backup name, account count, freshness, and whether the restore would exceed the account limit before it lets you apply anything.
+
+---
+
+## Sync And Settings
+
+The settings flow is split into two productized sections:
+
+- `Everyday Settings` for list appearance, details line, results and refresh behavior, and colors
+- `Advanced & Operator` for `Codex CLI Sync` and backend tuning
+
+Use `Codex CLI Sync` when you want to preview one-way sync from official Codex CLI account files before applying it. The sync screen shows source and target paths, preview summary, destination-only preservation, and backup rollback paths before apply.
+
+---
+
 ## Day-1 Command Pack
 
 ```bash
@@ -119,6 +144,12 @@ codex auth doctor --fix
 codex auth check
 ```
 
+If you need a broader diagnostics snapshot:
+
+```bash
+codex auth report --live --json
+```
+
 ---
 
 ## Next

@@ -1,6 +1,6 @@
 # codex-multi-auth Docs
 
-Daily-use guide for the `codex auth ...` workflow.
+Daily-use guide for the `codex auth ...` workflow, including restore, sync, and diagnostics.
 
 ---
 
@@ -12,6 +12,8 @@ codex auth list
 codex auth check
 ```
 
+If login detects recoverable named backups before OAuth, confirm the prompt to open `Restore From Backup` first.
+
 If you are choosing an account for the next session:
 
 ```bash
@@ -39,6 +41,12 @@ codex auth report --live --json
 codex auth doctor --fix
 ```
 
+Interactive workflows that ship in the dashboard:
+
+- backup restore: `codex auth login` -> `Restore From Backup`
+- sync preview and apply: `codex auth login` -> `Settings` -> `Codex CLI Sync`
+- settings split: `codex auth login` -> `Settings` -> `Everyday Settings` or `Advanced & Operator`
+
 ---
 
 ## Canonical Policy

@@ -20,7 +20,7 @@ Compatibility aliases are supported:
 
 | Command | Description |
 | --- | --- |
-| `codex auth login` | Open interactive auth dashboard |
+| `codex auth login` | Open interactive auth dashboard, including login, restore, settings, and diagnostics entry points |
 | `codex auth list` | List saved accounts and active account |
 | `codex auth status` | Print short runtime/account summary |
 | `codex auth switch <index>` | Set active account by index |
@@ -94,6 +94,16 @@ Compatibility aliases are supported:
 
 ## Workflow Packs
 
+Interactive dashboard workflows:
+
+- Backup restore: `codex auth login` -> `Restore From Backup`
+- Startup recovery prompt: `codex auth login`, then confirm restore when recoverable named backups are found before OAuth
+- Sync preview and apply: `codex auth login` -> `Settings` -> `Codex CLI Sync`
+- Stable settings path: `codex auth login` -> `Settings` -> `Everyday Settings`
+- Advanced settings path: `codex auth login` -> `Settings` -> `Advanced & Operator`
+
+---
+
 Health and planning:
 
 ```bash

@@ -21,7 +21,7 @@ When `CODEX_MULTI_AUTH_DIR` is set, this root moves accordingly.
 
 ## Everyday Settings
 
-The top-level settings flow now separates everyday dashboard preferences from advanced operator controls.
+The shipped settings menu starts with `Everyday Settings` and keeps the stable dashboard path separate from advanced operator controls. This is the default path for most users.
 
 ### List Appearance
 
@@ -65,9 +65,11 @@ Controls display style:
 
 ## Advanced and Operator Controls
 
+The second top-level section is `Advanced & Operator`. It holds the sync workflow and backend tuning that are useful when you need to inspect or change lower-level behavior.
+
 ### Codex CLI Sync
 
-The advanced section includes a preview-first sync center for Codex CLI account sync.
+`Codex CLI Sync` is a preview-first sync center for Codex CLI account sync.
 
 Before applying sync, it shows:
 
@@ -78,11 +80,18 @@ Before applying sync, it shows:
 - destination-only preservation behavior
 - backup and rollback context (`.bak`, `.bak.1`, `.bak.2`, `.wal`)
 
+Workflow notes:
+
+- refresh recomputes the read-only preview from Codex CLI source files
+- apply writes the preview result into the target path
+- sync is one-way, it is not a bidirectional merge
+- target-only accounts are preserved rather than deleted
+
 ---
 
 ### Advanced Backend Controls
 
-Expert backend controls stay available without changing the saved settings schema. They are grouped into categories so the default path can stay simpler for day-to-day use.
+`Advanced Backend Controls` stay available without changing the saved settings schema. They are grouped into categories so the everyday path can stay simpler for day-to-day use.
 
 ## Backend Categories
 
@@ -175,6 +184,7 @@ For most environments:
 
 - smart sort enabled
 - auto-fetch limits enabled
+- storage backups enabled when you want rollback context for sync and recovery flows
 - live sync enabled
 - session affinity enabled
 - preemptive quota deferral enabled

@@ -1,6 +1,6 @@
 # Troubleshooting
 
-Recovery guide for install, login, switching, worktree storage, and stale local auth state.
+Recovery guide for install, login, backup restore, sync preview, worktree storage, and stale local auth state.
 
 ---
 
@@ -18,6 +18,10 @@ If the account pool is still not usable:
 codex auth login
 ```
 
+If `codex auth login` starts with no saved accounts and named backups are present, you will be prompted to restore before OAuth. This prompt only appears in interactive terminals and is skipped after intentional reset flows.
+
+If you want to inspect backup options yourself instead of taking the prompt immediately, open `codex auth login` and choose `Restore From Backup`.
+
 ---
 
 ## Verify Install And Routing
@@ -55,6 +59,17 @@ npm i -g codex-multi-auth
 
 ---
 
+## Backup Restore Problems
+
+| Symptom | Likely cause | Action |
+| --- | --- | --- |
+| You expected a restore prompt but went straight to OAuth | No recoverable named backups were found, the terminal is non-interactive, or the flow is skipping restore after an intentional reset | Put named backup files in `~/.codex/multi-auth/backups/`, then rerun `codex auth login` in an interactive terminal |
+| `Restore From Backup` says no backups were found | The named backup directory is empty or the files are elsewhere | Place backup files in `~/.codex/multi-auth/backups/` and retry |
+| A backup is listed but cannot be selected | The backup is invalid or would exceed the account limit | Trim current accounts first or choose a different backup |
+| Restore succeeded but some rows were skipped | Deduping kept the existing matching account state | Run `codex auth list` and `codex auth check` to review the merged result |
+
+---
+
 ## Switching And State Problems
 
 | Symptom | Likely cause | Action |
@@ -65,6 +80,19 @@ npm i -g codex-multi-auth
 
 ---
 
+## Codex CLI Sync Problems
+
+Use `codex auth login` -> `Settings` -> `Codex CLI Sync` when you want to inspect sync state before applying it.
+
+| Symptom | Likely cause | Action |
+| --- | --- | --- |
+| Sync preview looks one-way | This is the shipped behavior | Review the preview, then apply only if the target result is what you want |
+| A target-only account would be lost | The sync center preserves destination-only accounts instead of deleting them | Recheck the preview summary before apply |
+| You want rollback context before syncing | Backup support is disabled in current settings | Enable storage backups in advanced settings, then refresh the sync preview |
+| Active selection does not match expectation | Preview kept the newer local choice or updated from Codex CLI based on selection precedence | Refresh preview and review the selection summary before apply |
+
+---
+
 ## Worktrees And Project Storage
 
 | Symptom | Likely cause | Action |
@@ -87,6 +115,11 @@ codex auth report --live --json
 codex auth doctor --json
 ```
 
+Interactive diagnostics path:
+
+- `codex auth login` -> `Settings` -> `Codex CLI Sync` for preview-based sync diagnostics
+- `codex auth login` -> `Settings` -> `Advanced Backend Controls` for sync, retry, quota, recovery, and timeout tuning
+
 ---
 
 ## Reset Options

@@ -26,6 +26,10 @@ export function isNonInteractiveMode(): boolean {
 	return false;
 }
 
+export function isInteractiveLoginMenuAvailable(): boolean {
+	return !isNonInteractiveMode() && isTTY();
+}
+
 export async function promptAddAnotherAccount(
 	currentCount: number,
 ): Promise<boolean> {
@@ -251,7 +255,7 @@ export async function promptLoginMode(
 		return { mode: "add" };
 	}
 
-	if (!isTTY()) {
+	if (!isInteractiveLoginMenuAvailable()) {
 		return promptLoginModeFallback(existingAccounts);
 	}