codex-multi-auth 2.1.5 → 2.1.6

package/README.md

@@ -1,11 +1,15 @@
-# codex-multi-auth
+# codex-multi-auth: multi-account OAuth for the official Codex CLI
 
 [![npm version](https://img.shields.io/npm/v/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
 [![npm downloads](https://img.shields.io/npm/dw/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
+[![CI](https://github.com/ndycode/codex-multi-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/ndycode/codex-multi-auth/actions/workflows/ci.yml)
+[![MIT license](https://img.shields.io/npm/l/codex-multi-auth.svg)](LICENSE)
 
-Codex CLI-first multi-account OAuth manager for the official Codex CLI. The package installs conflict-free alongside official `codex` installs; use `codex-multi-auth ...` for account management or `codex-multi-auth-codex ...` when you explicitly want the forwarding wrapper.
+`codex-multi-auth` is a multi-account OAuth manager for the official `@openai/codex` CLI. It gives Codex CLI users explicit ChatGPT account login, account switching, health checks, local diagnostics, project-scoped storage, and default-on runtime Responses rotation without taking over the official `codex` binary. Use `codex-multi-auth ...` for account management, or `codex-multi-auth-codex ...` only when you intentionally want the optional forwarding wrapper.
 
-<img width="1270" height="729" alt="2026-02-28 12_54_58-prompt txt ‎- Notepads" src="https://github.com/user-attachments/assets/0cecb77e-a6d3-432a-ba48-3577db0c7093" />
+Use it when you need a local Codex CLI multi-account workflow with visible account state, safer recovery commands, and a loopback-only runtime rotation proxy for request-bearing forwarded Codex sessions.
+
+<img width="1270" height="729" alt="codex-multi-auth terminal dashboard for Codex CLI multi-account OAuth account status" src="https://github.com/user-attachments/assets/0cecb77e-a6d3-432a-ba48-3577db0c7093" />
 
 
 
@@ -15,23 +19,41 @@ Codex CLI-first multi-account OAuth manager for the official Codex CLI. The pack
 
 ## What You Get
 
-- Conflict-free `codex-multi-auth ...` workflow for account login, switching, checks, and diagnostics
-- Official Codex CLI forwarding for all non-auth commands
-- Multi-account OAuth pool with health-aware selection and automatic failover
-- Project-scoped account storage under `~/.codex/multi-auth/projects/<project-key>/...`
-- Interactive dashboard for account actions and settings
-- Experimental settings tab for staged sync, backup, and refresh-guard controls
-- Forecast, report, fix, and doctor commands for operational safety
-- Local usage ledger, budgets, account policy controls, routing profiles, and monitor views for local governance
+- Codex CLI multi-account OAuth management with a dedicated `codex-multi-auth ...` command family
+- Explicit ChatGPT account login, saved-account listing, account switching, health checks, and diagnostics
+- Optional `codex-multi-auth-codex ...` forwarding wrapper for official Codex CLI commands when you choose wrapper-launched sessions
+- Health-aware account selection, quota forecasting, automatic failover, and flagged-account recovery
+- Project-scoped account storage under `~/.codex/multi-auth/projects/<project-key>/...` for repo-specific workflows
+- Interactive terminal dashboard for account actions, settings, search, and hotkeys
+- Forecast, report, fix, doctor, verify, monitor, and rotation commands for operational confidence
+- Local usage ledger, budget guards, account policy controls, routing profiles, and model/account capability views
 - Runtime counters, budget/cooldown state, and multi-auth probe visibility in `codex-multi-auth status` / `codex-multi-auth report`
-- Default-on runtime Responses proxy for live account rotation inside forwarded Codex CLI/app sessions
+- Default-on loopback Responses proxy for live account rotation inside forwarded Codex CLI/app sessions
 - Optional loopback-only local bridge for `/health`, `/v1/models`, and `/v1/responses`, protected by hashed local client tokens
-- Reversible packaged Codex app bind and user-level launcher routing helpers
-- Flagged account verification and restore flow
-- Session affinity and live account sync controls
-- Proactive refresh and preemptive quota deferral controls
-- Codex-oriented request/prompt compatibility with strict runtime handling
-- Stable docs set for install, config, troubleshooting, and upgrade paths
+- Reversible packaged Codex app bind and user-level launcher routing helpers that do not patch official app binaries
+- Session affinity, live account sync, proactive refresh, and preemptive quota deferral controls
+- Codex-oriented request/prompt compatibility with strict runtime handling and documented error contracts
+- Stable docs for install, configuration, troubleshooting, upgrade, public API, storage paths, and release notes
+
+---
+
+## Why Developers Use It
+
+`codex-multi-auth` makes local Codex account state visible and recoverable. Instead of one opaque auth file, you get a named account pool, deterministic account switching, health-aware selection, JSON diagnostics for automation, and safe repair commands for stale or damaged local state. The architecture is designed for personal development workflows: credentials stay local, runtime rotation is loopback-only, and official Codex install paths keep owning the `codex` command.
+
+---
+
+## Current Architecture At A Glance
+
+`codex-multi-auth` now ships three distinct global binaries:
+
+| Binary | Purpose |
+| --- | --- |
+| `codex-multi-auth` | Primary account manager; accepts bare auth subcommands such as `login`, `status`, `switch`, `forecast`, and `rotation status` |
+| `codex-multi-auth-codex` | Optional wrapper that handles `auth ...` locally and forwards every other command to the official Codex CLI |
+| `codex-multi-auth-app-launcher` | Optional desktop launcher helper for supported user-level shortcuts and wrapper apps |
+
+The package does not publish a global `codex` binary. Keep `codex` owned by the official OpenAI install path and use `codex-multi-auth-codex ...` only when you intentionally want this package's forwarding wrapper.
 
 ---
 
@@ -312,7 +334,7 @@ codex-multi-auth login
 <details>
 <summary><b>Common symptoms</b></summary>
 
-- `codex auth` unrecognized: run `where codex` or `which codex`, then follow `docs/troubleshooting.md` for routing fallback commands
+- `codex-multi-auth` unrecognized: run `where codex-multi-auth` or `which codex-multi-auth`, then follow `docs/troubleshooting.md` for install checks
 - Switch succeeds but wrong account appears active: run `codex-multi-auth switch <index>`, then restart session
 - Requests fail fast with a pool cooldown message: wait for the cooldown window or inspect `codex-multi-auth status`
 - Requests fail fast after repeated upstream 5xx errors: inspect `codex-multi-auth report --json` for runtime traffic and cooldown details
@@ -360,8 +382,10 @@ codex-multi-auth doctor --json
 
 ## Release Notes
 
-- Current stable: [docs/releases/v2.1.4.md](docs/releases/v2.1.4.md)
-- Previous stable: [docs/releases/v2.1.3.md](docs/releases/v2.1.3.md)
+- Current stable: [docs/releases/v2.1.6.md](docs/releases/v2.1.6.md)
+- Previous stable: [docs/releases/v2.1.5.md](docs/releases/v2.1.5.md)
+- Earlier stable: [docs/releases/v2.1.4.md](docs/releases/v2.1.4.md)
+- Earlier stable: [docs/releases/v2.1.3.md](docs/releases/v2.1.3.md)
 - Earlier stable: [docs/releases/v2.1.2.md](docs/releases/v2.1.2.md)
 - Earlier stable: [docs/releases/v2.1.1.md](docs/releases/v2.1.1.md)
 - Earlier stable: [docs/releases/v2.1.0.md](docs/releases/v2.1.0.md)

package/config/README.md

@@ -1,6 +1,6 @@
 # Config Templates
 
-These files are optional model/provider templates for host/plugin configurations that still load `codex-multi-auth` directly. The normal wrapper workflow uses `codex auth ...` and does not require these templates.
+These files are optional model/provider templates for host/plugin configurations that still load `codex-multi-auth` directly. The normal account-manager workflow uses `codex-multi-auth ...` and does not require these templates.
 
 ## Primary (Codex-named)
 
@@ -13,7 +13,7 @@ These files are optional model/provider templates for host/plugin configurations
 ## Notes
 
 - These templates are optional for the OAuth account manager flow and the runtime rotation proxy.
-- Core auth commands use `codex auth login`.
+- Core account-manager commands use `codex-multi-auth login`.
 
 ## Defaults Included
 
@@ -27,4 +27,3 @@ These files are optional model/provider templates for host/plugin configurations
 - [`../docs/configuration.md`](../docs/configuration.md)
 - [`../docs/getting-started.md`](../docs/getting-started.md)
 - [`../docs/reference/settings.md`](../docs/reference/settings.md)
-

package/dist/index.js

@@ -438,7 +438,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                         await accountManager.saveToDisk();
                     }
                     if (accountManager.getAccountCount() === 0) {
-                        logDebug(`[${PLUGIN_NAME}] No OAuth accounts available (run codex login)`);
+                        logDebug(`[${PLUGIN_NAME}] No OAuth accounts available (run codex-multi-auth login)`);
                         return {};
                     }
                     // Extract user configuration (global + per-model options)
@@ -679,7 +679,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                     };
                                     return new Response(JSON.stringify({
                                         error: {
-                                            message: `The account pool is cooling down after recent rate-limit exhaustion. Try again in ${formatWaitTime(poolCooldownRemainingMs)} or inspect \`codex auth status\`.`,
+                                            message: `The account pool is cooling down after recent rate-limit exhaustion. Try again in ${formatWaitTime(poolCooldownRemainingMs)} or inspect \`codex-multi-auth status\`.`,
                                         },
                                     }), {
                                         status: 429,
@@ -701,7 +701,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                     };
                                     return new Response(JSON.stringify({
                                         error: {
-                                            message: `Multiple accounts recently failed with upstream server errors. Try again in ${formatWaitTime(serverBurstCooldownRemainingMs)} or inspect \`codex auth report --json\`.`,
+                                            message: `Multiple accounts recently failed with upstream server errors. Try again in ${formatWaitTime(serverBurstCooldownRemainingMs)} or inspect \`codex-multi-auth report --json\`.`,
                                         },
                                     }), {
                                         status: 503,
@@ -862,7 +862,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                                 accountManager.removeAccount(account);
                                                 sessionAffinityStore?.reindexAfterRemoval(removedIndex);
                                                 accountManager.saveToDiskDebounced();
-                                                await showRuntimeToast(client, `Removed ${accountLabel} after ${failures} consecutive auth failures. Run 'codex login' to re-add.`, "error", { duration: toastDurationMs * 2 });
+                                                await showRuntimeToast(client, `Removed ${accountLabel} after ${failures} consecutive auth failures. Run 'codex-multi-auth login' to re-add.`, "error", { duration: toastDurationMs * 2 });
                                                 continue;
                                             }
                                             if (typeof authFailurePolicy.cooldownMs === "number" &&
@@ -1634,7 +1634,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                                                 syncRuntimeObservability(requestTraceId);
                                                                 return new Response(JSON.stringify({
                                                                     error: {
-                                                                        message: `Upstream server failures were observed across multiple accounts. Pausing retries for ${formatWaitTime(serverBurstCooldownUntil - Date.now())}. Check \`codex auth report --json\` for runtime metrics.`,
+                                                                        message: `Upstream server failures were observed across multiple accounts. Pausing retries for ${formatWaitTime(serverBurstCooldownUntil - Date.now())}. Check \`codex-multi-auth report --json\` for runtime metrics.`,
                                                                     },
                                                                 }), {
                                                                     status: 503,
@@ -1728,10 +1728,10 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                         ? formatWaitTime(effectiveWaitMs)
                                         : "a bit";
                                     const message = count === 0
-                                        ? "No Codex accounts configured. Run `codex login`."
+                                        ? "No Codex accounts configured. Run `codex-multi-auth login`."
                                         : effectiveWaitMs > 0
-                                            ? `All ${count} account(s) are rate-limited. A short pool cooldown is now active for ${waitLabel}. Try again later or inspect \`codex auth status\`.`
-                                            : `All ${count} account(s) failed (server errors or auth issues). Check account health with \`codex auth report --json\`.`;
+                                            ? `All ${count} account(s) are rate-limited. A short pool cooldown is now active for ${waitLabel}. Try again later or inspect \`codex-multi-auth status\`.`
+                                            : `All ${count} account(s) failed (server errors or auth issues). Check account health with \`codex-multi-auth report --json\`.`;
                                     runtimeMetrics.failedRequests++;
                                     runtimeMetrics.lastError = message;
                                     syncRuntimeObservability(requestTraceId);
@@ -2210,7 +2210,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                 ...formatUiHeader(ui, "Codex accounts"),
                                 "",
                                 formatUiItem(ui, "No accounts configured.", "warning"),
-                                formatUiItem(ui, "Run: codex login", "accent"),
+                                formatUiItem(ui, "Run: codex-multi-auth login", "accent"),
                                 formatUiKeyValue(ui, "Storage", storePath, "muted"),
                             ].join("\n");
                         }
@@ -2218,7 +2218,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                             "No Codex accounts configured.",
                             "",
                             "Add accounts:",
-                            "  codex login",
+                            "  codex-multi-auth login",
                             "",
                             `Storage: ${storePath}`,
                         ].join("\n");
@@ -2267,7 +2267,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                         });
                         lines.push("");
                         lines.push(...formatUiSection(ui, "Commands"));
-                        lines.push(formatUiItem(ui, "Add account: codex login", "accent"));
+                        lines.push(formatUiItem(ui, "Add account: codex-multi-auth login", "accent"));
                         lines.push(formatUiItem(ui, "Switch account: codex-switch <index>"));
                         lines.push(formatUiItem(ui, "Detailed status: codex-status"));
                         lines.push(formatUiItem(ui, "Health check: codex-health"));
@@ -2305,7 +2305,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                     lines.push(`Storage: ${storePath}`);
                     lines.push("");
                     lines.push("Commands:");
-                    lines.push("  - Add account: codex login");
+                    lines.push("  - Add account: codex-multi-auth login");
                     lines.push("  - Switch account: codex-switch");
                     lines.push("  - Status details: codex-status");
                     lines.push("  - Health check: codex-health");
@@ -2328,10 +2328,10 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                 ...formatUiHeader(ui, "Switch account"),
                                 "",
                                 formatUiItem(ui, "No accounts configured.", "warning"),
-                                formatUiItem(ui, "Run: codex login", "accent"),
+                                formatUiItem(ui, "Run: codex-multi-auth login", "accent"),
                             ].join("\n");
                         }
-                        return "No Codex accounts configured. Run: codex login";
+                        return "No Codex accounts configured. Run: codex-multi-auth login";
                     }
                     const targetIndex = Math.floor((index ?? 0) - 1);
                     if (!Number.isFinite(targetIndex) ||
@@ -2401,10 +2401,10 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                 ...formatUiHeader(ui, "Account status"),
                                 "",
                                 formatUiItem(ui, "No accounts configured.", "warning"),
-                                formatUiItem(ui, "Run: codex login", "accent"),
+                                formatUiItem(ui, "Run: codex-multi-auth login", "accent"),
                             ].join("\n");
                         }
-                        return "No Codex accounts configured. Run: codex login";
+                        return "No Codex accounts configured. Run: codex-multi-auth login";
                     }
                     const now = Date.now();
                     const activeIndex = resolveActiveIndex(storage, "codex");
@@ -2632,10 +2632,10 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                 ...formatUiHeader(ui, "Health check"),
                                 "",
                                 formatUiItem(ui, "No accounts configured.", "warning"),
-                                formatUiItem(ui, "Run: codex login", "accent"),
+                                formatUiItem(ui, "Run: codex-multi-auth login", "accent"),
                             ].join("\n");
                         }
-                        return "No Codex accounts configured. Run: codex login";
+                        return "No Codex accounts configured. Run: codex-multi-auth login";
                     }
                     const results = ui.v2Enabled
                         ? []
@@ -2772,7 +2772,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                     formatUiItem(ui, `${getStatusMarker(ui, "ok")} Removed: ${label}`, "success"),
                                     remaining > 0
                                         ? formatUiKeyValue(ui, "Remaining accounts", String(remaining))
-                                        : formatUiItem(ui, "No accounts remaining. Run: codex login", "warning"),
+                                        : formatUiItem(ui, "No accounts remaining. Run: codex-multi-auth login", "warning"),
                                 ].join("\n");
                             }
                             return [
@@ -2780,7 +2780,7 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                 "",
                                 remaining > 0
                                     ? `Remaining accounts: ${remaining}`
-                                    : "No accounts remaining. Run: codex login",
+                                    : "No accounts remaining. Run: codex-multi-auth login",
                             ].join("\n");
                         },
                     }),
@@ -2796,10 +2796,10 @@ export const OpenAIOAuthPlugin = async ({ client }) => {
                                         ...formatUiHeader(ui, "Refresh accounts"),
                                         "",
                                         formatUiItem(ui, "No accounts configured.", "warning"),
-                                        formatUiItem(ui, "Run: codex login", "accent"),
+                                        formatUiItem(ui, "Run: codex-multi-auth login", "accent"),
                                     ].join("\n");
                                 }
-                                return "No Codex accounts configured. Run: codex login";
+                                return "No Codex accounts configured. Run: codex-multi-auth login";
                             }
                             const results = ui.v2Enabled
                                 ? []