codex-multi-auth

1.3.2 verified Sat Apr 25 auth: no javascript

Multi-account OAuth manager and auth wrapper for the official OpenAI Codex CLI (v1.3.2, stable). Provides account switching, health-aware failover, proactive token refresh, and diagnostics (forecast, report, fix, doctor). Ships TypeScript types, ESM-only, requires Node >=18.0.0 and TypeScript ^5 as peer dependency. Differentiates from raw @openai/codex by adding multi-account pool management, circuit-breaker logic, and recovery tools without altering the core CLI interface. Maintained actively with frequent patches.

Common errors

error SyntaxError: Cannot use import statement outside a module ↓

cause Trying to import in a CommonJS file.

fix

Add 'type': 'module' to package.json or rename file to .mjs.

error Error: Cannot find module 'codex-multi-auth' ↓

cause Package not installed globally or not on PATH.

fix

Run npm i -g codex-multi-auth.

error TypeError: codexMultiAuth is not a function ↓

cause Using default import when package only exports named exports.

fix

Use import { AuthManager } from 'codex-multi-auth' instead of default import.

Warnings

breaking Legacy scoped package @ndycode/codex-multi-auth is migration-only; new installs must use codex-multi-auth. ↓

fix npm uninstall -g @ndycode/codex-multi-auth && npm i -g codex-multi-auth

deprecated CJS require() will fail in v1.3+; project is ESM-only. ↓

fix Use import statements and set 'type': 'module' in package.json.

gotcha Interactive Codex runs after GPT-5.5 rollout broke in v1.3.1; fixed in v1.3.2 by preserving TTY stdio. ↓

fix Upgrade to v1.3.2.

gotcha Node.js <18.0.0 not supported; engines field enforced with warning. ↓

fix Upgrade Node.js to >=18.0.0.

Install

npm install codex-multi-auth

yarn add codex-multi-auth

pnpm add codex-multi-auth

Imports

default

wrong

const codexMultiAuth = require('codex-multi-auth')

correct

import codexMultiAuth from 'codex-multi-auth'

ESM-only; CJS require will fail.

AuthManager

wrong

import { AuthManager } from 'codex-multi-auth/dist'

correct

import { AuthManager } from 'codex-multi-auth'

Named export; no subpath needed.

Account

wrong

import { Account } from 'codex-multi-auth'

correct

import type { Account } from 'codex-multi-auth'

Account is a type-only export; use import type to avoid runtime error.

Quickstart

Install globally, log in, verify status, list accounts, switch account, and preview routing decision.

npm i -g @openai/codex
npm i -g codex-multi-auth
codex auth login
codex auth status
codex auth list
codex auth switch 2
codex auth forecast --live