Codex Auth: Command Line Tool Providing Multi-Account Switching and Limit Monitoring

Codex Auth is a third-party command line (CLI) enhancement tool developed for OpenAI Codex users, with the core purpose of solving the cumbersome multi-account management and request limitation issues that developers face when using AI programming assistants.OpenAI Codex, as a powerful Agentic programming partner, has limitations in its native system in terms of multi-environment authentication and quota status display. Codex Auth fills this gap by allowing users to centrally manage and seamlessly switch between multiple credentials on the local device.

Designed with “result-oriented” and “automation” in mind, the tool is not just a toggle switch, but also a visual scheduling center. Through the intuitive terminal interactive interface (TUI), developers can grasp in real-time each account's package type (e.g., Pro, Team, Pro Lite), 5-hour high-frequency usage, and weekly total usage consumption ratio. On top of that, the tool provides an innovative “Auto-switch” feature - when an active account hits a customized utilization threshold, it is automatically switched to a backup account in the background to ensure that the AI programming mindstream is not interrupted. Codex Auth is fully compatible with Windows, macOS, and Linux, and works seamlessly with the Codex CLI, desktop apps, and VS Code plug-ins, making it an indispensable performance infrastructure for enterprise-level teams and heavy AI developers.

Function List

• Interactive multi-account switching: Built-in Terminal Interactive Interface (TUI) that supports quickly performing seamless switching of identity credentials between multiple Codex accounts via up and down keys, line numbers, or custom aliases.
• Real-time usage and package monitoringIt supports real-time display of the subscription plan an account is on, as well as the current account's 5-hour call rate and weekly utilization status by capturing local security logs or directly calling the underlying API.
• Auto-switching in the backgroundThe system automatically monitors and seamlessly switches to the next available account in the background to avoid interruptions triggered by the official flow limiting mechanism.
• Flexible Login Authentication Integration: Deep integration of the underlying login logic, support for invoking standard web page authorization (Web Auth) and remote headless server device code authorization (Device Auth), automatically archived to the management library after entry.
• Batch import and cleanup maintenance: Supports intelligent batch import (Import) of single-file and multi-file directories, fast synchronization of forensic files shared by the team; and provides interactive cleanup of redundant and outdated files.
• Multi-client and platform compatibilityThe authentication statuses generated are served directly to the Codex CLI (@openai/codex), the VS Code plugin, and the Codex App client, and are fully compatible with Windows, macOS, and Linux architectures.

Using Help

Welcome to Codex Auth! To ensure that you can smoothly maximize the value of this tool in your real-world development workflow, please read the detailed operation and configuration guide below. The system is strictly modular, and both basic local deployment and advanced automated resource scheduling can be accomplished from a simple command line.

I. Operating environment preparation and installation process

Codex Auth runs on the Node.js runtime environment, and the underlying logic needs to be compatible with the native official Codex CLI Client fit.

Step 1: Install the predecessor dependencies
Make sure you have Node.js installed on your operating system (version 22+ recommended). Next, it is highly recommended that you first install the official Codex CLI tool to automatically generate the default environment directory and dependency credentials configuration.

npm install -g @openai/codex

Step 2: Install Codex Auth
You can install the tool globally on your operating system via the npm package manager, so you can use it directly in any project folder. codex-auth Command:

npm install -g @loongphy/codex-auth

(Installation-free implementation: If you only use the query function occasionally, you can use npx directly for in-memory calls:npx @loongphy/codex-auth list）

II. Basic operation: account access and inquiry

1. Add and log in accounts
Before you can manage multiple identity credentials within the system, you need to enter them. Simply enter them in the terminal:

# 启动标准图形化登录流程
codex-auth login

The system will automatically bring up your browser and guide you through the ChatGPT Account Login. If you are operating on a cloud-based virtual machine that does not have a graphical interface, such as Ubuntu Server, use the device code login mode:

codex-auth login --device-auth

At this time, the terminal will generate a string of verification code, you can enter the code in the browser of the local computer to complete the authorization, and the credentials will be automatically synchronized to the server hub.

2. Access to global account status (core dashboard)
pass (a bill or inspection etc) list command to see at a glance the survival status and load pressure of all hosted accounts. This is the most commonly used check during development:

codex-auth list

In the beautiful data table, you will see that each account number corresponds to the ACCOUNT(email account),PLAN(e.g. Team or Pro Lite packages),5H USAGE(percentage of 5-hour dynamic quota consumption) and WEEKLY USAGE(Percentage of total weekly calls). Followed by --live parameter can force a real-time dosage request to be triggered:

codex-auth list --live

III. Advanced Scheduling: Environment Switching and Automated Anti-Current Limiting

The core claim of multi-account management is to cope with scenarios where a single account runs out of arithmetic power during extensive reconfiguration.

1. Interactive versus directional switching
When your active account (with * (Logo) When the quota alarm appears, enter the following command to activate the TUI selector:

codex-auth switch

The interface will list all current library accounts in a highlighted list. Use the up and down arrows on your keyboard to select a healthy account and enter, the credentials will be replaced immediately.
If you are familiar with the account's list number or a set alias, you can skip the interactive screen to perform a hot swap:

codex-auth switch 02
codex-auth switch work-account

[Key Notes]: Upon completion of the switch, the VS Code native plugin and the desktop application are required due to the runtime mechanismsRestart the clientIt is only then that the authentication file can be re-read. If you want seamless reboot-free switching for code editing, it is highly recommended to uninstall the native CLI and use a modified version of the core dependencies instead:

npm uninstall -g @openai/codex
npm install -g @loongphy/codext

2. Enabling the Auto-switch protection mechanism
Don't let manual switching interrupt your coding mindstream. You can configure Codex Auth to act as a background resident service that monitors when quotas hit the red line and automatically switches to the next healthy account.
First, activate the automatic mode:

codex-auth config auto enable

Next, set the meltdown threshold. For example, we require that the tool automatically performs account rotation when the 5-hour limit is consumed up to 80% or the weekly limit reaches 95%:

codex-auth config auto --5h 80 --weekly 95

This operation is particularly well suited for automated test pipelines and nightly compilation scripts to ensure that the AI Agent has a constant stream of arithmetic support.

IV. Asset maintenance: import and update of account vouchers

1. Introduction of business and team assets
Enterprise IT or R&D team leaders typically issue forensic JSON files in a uniform manner. Use the following command to seamlessly merge into an existing management pool:

# 导入单独的鉴权文件，并指派别名为 team-alpha
codex-auth import /path/to/auth.json --alias team-alpha
# 批量扫描并导入某个目录下的所有合规配置
codex-auth import /path/to/auth_folder/

2. Management of data sources for the refresh mechanism
In order to get the just mentioned 5H USAGE To be precise, Codex Auth polls HTTPS by default using a direct API connection (which consumes some network resources). If you are experiencing network constraints, or if you prefer to be conservative and only read local request logs, you can turn off API polling:

# 开启（默认推荐，数据最精确）
codex-auth config api enable
# 关闭（改为读取 ~/.codex/sessions 本地日志，会有少许延迟）
codex-auth config api disable

Finally, you can always use the codex-auth status command to check the configuration and survival of all background daemons.

application scenario

1. Heavy full-stack development for quota pickups
   When utilizing OpenAI Codex to perform highly concurrent Agent tasks such as whole library code refactoring, full file static type derivation, etc., it is very easy for developers to run out of the current account's 5-hour request limit. By configuring codex-auth config auto With the automatic rotation mechanism, developers can pack 3 to 5 subscription accounts into a single arithmetic pool, ensuring that the code generation process doesn't need to pause to wait for the flow limit to resume.
2. Shared allocation of basic arithmetic resources for development teams
   The project team procured several ChatGPT Team accounts and shared them with junior programmers to perform routine operations such as code reviews. The administrator distributes the authorization file to the team members, who use the codex-auth import Perform a batch import and pass the list The view observes the load of each account in real time, manually avoids congested accounts, and greatly improves resource utilization within the team.
3. Automated Script Escort for Remote Headless Servers
   In CI/CD pipelines or cloud sandboxes such as NVIDIA's Codex instances deployed to run in the background, it is extremely difficult for developers to deal with session expiration by relying on the native client because they are unable to operate the system's graphical interface. Using codex-auth login --device-auth Complete authentication bindings in cloud-native environments while utilizing the command line to enable fast identity switching between multiple versions of test environments, ensuring that continuous integration doesn't crash due to authentication failures.

QA

1. Why is my Usage limits lagging or not updating in the terminal?
   This is usually because the data refresh mode is set to read only local logs (Local-only). Native Codex is often found in the log feeds of new releases rate_limits: null, resulting in local file data that may lag several hours behind what really happened. You can execute the codex-auth config api enable Switch to API live fetch mode to work around this issue.
2. How do I make sure that turning on real-time API fetching won't result in a block?
   Enabling API mode means that the tool will directly extract your Access Token and send a status query request to the official backend endpoint. This action is read by simulating the official interface, and although it satisfies the logic of normal use, it may violate the rules of wind control if it is accessed concurrently with a very high frequency due to human modification. Ordinary intensity of the query within the scope of compliance, the tool itself does not bear the risk of force majeure wind control, the user needs to be reasonable use.
3. After the switchover is complete, why does the Codex App or VS Code still report insufficient credit?
   Native Codex and its official extensions are designed to read the forensics file once at application startup and reside in memory. As a result, when using the codex-auth switch After successfully changing the underlying configuration, you must restart the IDE (VS Code) or desktop application to make it reload the configuration file. If you wish to dispense with the restart, uninstall the native libraries and install a customized version of the @loongphy/codext。
4. Support for purging expired or invalid voucher information?
   Support. Running in a terminal codex-auth remove A graphical multi-select menu will be brought up, where you can check and clean out account profiles that have been invalidated or banned to keep the system environment clean. Alternatively, you can use the codex-auth remove <别名> Directional Deletion.