Skip to main content

​
Prerequisites

Before installing Codex Multi-Auth, ensure you have:
  • Node.js 18+ - Check your version with node --version
  • Active ChatGPT plan - With access to the models you intend to use
  • Official Codex CLI - The @openai/codex package (installed in the next step)

​
Standard installation

1

Install the official Codex CLI

First, install the official @openai/codex package globally:
npm i -g @openai/codex
2

Install Codex Multi-Auth

Next, install the codex-multi-auth package globally:
npm i -g codex-multi-auth
3

Verify installation

Confirm that the codex command is available and wired correctly:
codex --version
Then verify the auth plugin is loaded:
codex auth status
You should see output indicating the plugin is active, even if no accounts are configured yet.

​
Migrate from legacy package

If you previously installed the scoped prerelease package @ndycode/codex-multi-auth, follow these steps:
1

Uninstall the legacy package

Remove the old scoped package:
npm uninstall -g @ndycode/codex-multi-auth
2

Install the new package

Install the current codex-multi-auth package:
npm i -g codex-multi-auth
Your existing account data and settings will be preserved automatically. The migration is seamless.
3

Verify migration

Confirm your accounts are still accessible:
codex auth list
codex auth check

​
Verification checklist

After installation, verify your setup with these commands: 
# Confirm Codex CLI version
codex --version

# Check auth plugin status
codex auth status

# List configured accounts (may be empty on first install)
codex auth list

# Test health check command
codex auth check
If codex auth is not recognized, try using the compatibility alias codex multi auth status or check your global npm installation path.

​
Troubleshooting installation

​
Command not found

If you see “command not found” errors after installation:
  1. Check your global npm path 
    npm config get prefix
    Ensure this directory is in your PATH environment variable.
  2. Try alternative command formats 
    codex multi auth status
codex multi-auth status
codex multiauth status
  3. Find the Codex binary location 
    # On Unix/macOS
which codex

# On Windows
where codex

​
Permission errors

If you encounter EACCES permission errors on Unix/macOS: 
# Option 1: Use a Node version manager (recommended)
nvm use 18  # or your preferred version

# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

​
OAuth callback port conflict

The OAuth flow uses port 1455 by default. If you see port binding errors:
  1. Find and stop the process using port 1455: 
    # On Unix/macOS
lsof -ti:1455 | xargs kill

# On Windows
netstat -ano | findstr :1455
  2. Retry the installation or login flow

​
Next steps

Quickstart

Add your first account and run health checks

Configuration

Customize settings and environment variables

Build docs developers (and LLMs) love

Get started for freeTalk to us