Codex Controller (codexctl)

Codex Controller - Full control plane for Codex CLI

Prerequisite: Requires @openai/codex to be installed first.

Version: 0.10.0 | Author: Bhanu Korthiwada

🔗 Website: codexctl on GitHub
📖 Documentation: See README for usage

---

Why Codex Controller?

Codex Controller starts from a practical limitation in Codex CLI today: there is no native first-class multi-profile workflow. This repo starts with a full end-to-end control plane for profile management, usage visibility, switching, and concurrent terminal usage.

Use it when you need to:

• 🔐 Multi-account management - Switch between work/personal/dev accounts instantly

• 🤖 Automation - Run Codex in CI/CD with specific credentials

• 📊 Usage monitoring - Track quota across teams

• 🌳 Concurrent sessions - Use multiple accounts in parallel

• 🔄 Profile-based workflows - Environment-specific configurations

• 🔐 Securely store multiple Codex CLI profiles with optional encryption

• ⚡ Switch instantly between accounts without re-authenticating

• 🤖 Auto-switch based on quota availability

• 📊 Monitor usage across all your Codex accounts

• 🌳 Use concurrently - different accounts in different terminals

---

Codex vs API (Important)

• ChatGPT/Codex plans and the OpenAI API are separate products with separate billing.
• A ChatGPT plan does not automatically include API usage credits.
• Codex CLI can authenticate with either a ChatGPT account or an API key.
• codexctl usage reads ChatGPT/Codex plan claims from local auth tokens.
• codexctl usage --realtime checks API billing/quota via OpenAI API endpoints.
• codexctl status --json, usage --json, verify --json, and doctor --json provide script-safe structured output.
• References:
  • Codex CLI auth flow: https://developers.openai.com/codex/cli
  • API vs ChatGPT billing separation: https://help.openai.com/en/articles/8156019

---

Features

Multi-Account Management

• 🔐 Secure Profiles - Store multiple Codex credentials with optional encryption
• ⚡ Instant Switching - Switch accounts in < 1 second
• 🔄 Quick Toggle - Toggle between current and previous with codexctl load -
• 🗂️ Full CRUD - Save, load, list, delete, backup profiles

Automation & Control

• 🤖 Auto-Switcher - Automatically pick best profile based on quota
• 📊 Usage Monitoring - Real-time quota and billing data
• ✅ Verify - Validate all profiles' authentication status
• 🌳 Concurrent Sessions - Use multiple accounts in parallel
• 🏃 CI/CD Integration - Run with specific credentials in pipelines

Developer Experience

• 🖥️ Cross-Platform - macOS, Linux, Windows (WSL2)
• 🔧 Shell Completions - Bash, Zsh, Fish, PowerShell
• 🧪 Zero Runtime - Single binary, no Node.js required
• 🐳 Docker - Multi-arch images
• 📦 Import/Export - Transfer profiles between machines

---

Quick Start

Prerequisites

First, install Codex CLI:

# Install Codex CLI (required)
npm install -g @openai/codex

# Verify installation
codex --version

Install codexctl

# Via cargo
cargo install codexctl

# Or via npm
npm install -g codexctl

# Or download binary from GitHub Releases
curl -fsSL https://github.com/repohelper/codexctl/releases

# Or via Homebrew (macOS/Linux)
brew install repohelper/tap/codexctl

First Steps

# Save your current Codex CLI profile
codexctl save work

# Create another profile
# (switch accounts in Codex CLI, then:)
codexctl save personal

# List all profiles
codexctl list

# Switch to a profile
codexctl load work

# Quick-switch to previous profile
codexctl load -

---

Commands

codexctl save <name>              Save current Codex auth as a profile
codexctl load <name>              Load a saved profile and switch to it
codexctl list                     List all saved profiles
codexctl delete <name>            Delete a saved profile
codexctl status                   Show current profile status
codexctl usage                    Show plan claims and API quota context
codexctl verify                   Verify all profiles' authentication status
codexctl backup                   Create a backup of current profile
codexctl run --profile <name> -- <cmd>
                                  Run a command with a specific profile
codexctl env <name>               Export shell commands for concurrent usage
codexctl diff <name1> <name2>     Compare/diff two profiles
codexctl switch                   Switch to a profile interactively (fzf)
codexctl history                  View command history
codexctl doctor                   Run health check on profiles
codexctl completions              Generate shell completions
codexctl import <name> <b64>      Import a profile from another machine
codexctl export <name>            Export a profile for transfer
codexctl setup                    Interactive setup wizard

---

Encryption

# Save with encryption
codexctl save work --passphrase "my-secret"

# Or use environment variable
export CODEXCTL_PASSPHRASE="my-secret"
codexctl save work

# Load encrypted profile
codexctl load work --passphrase "my-secret"

# Run one command with an encrypted profile, then restore original auth
codexctl run --profile work --passphrase "my-secret" -- codex --version

---

Usage And Auto-Switching

Inspect usage directly or let the controller pick the best available profile:

# Show current profile usage details
codexctl usage

# Emit structured JSON for automation
codexctl usage --json

# Compare usage across all saved profiles
codexctl usage --all

# Switch to the profile with the best remaining quota
codexctl load auto

---

Concurrent Usage

Run different Codex identities in separate terminals:

# Print shell exports for a profile
codexctl env work

# Bash/Zsh example
eval "$(codexctl env work)"

# Run one command against a specific profile and restore after
codexctl run --profile work -- codex --version

codexctl load and codexctl run only swap the live auth.json. Existing local sessions, history, memories, and state stay untouched. The automatic backup created during load now captures the live auth.json only, matching the actual mutation surface.

---

Structured Output

For CI, shell pipelines, and editor tooling:

codexctl status --json
codexctl usage --json
codexctl usage --all --json
codexctl verify --json
codexctl doctor --json

---

Shell Completions

source <(codexctl completions bash)

---

Docker

# Run with Docker
docker run -it --rm \
  -v ~/.codexctl:/home/codexctl/.config/codexctl \
  -v ~/.codex:/home/codexctl/.codex \
  ghcr.io/repohelper/codexctl list

---

Configuration

Configuration directory: ~/.config/codexctl/

# ~/.config/codexctl/config.toml
[default]
cli = "codex"  # Default CLI to manage

[auto_switch]
enabled = true
threshold = 80  # Switch when quota below 80%

[encryption]
default_passphrase = false  # Always prompt for passphrase

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Security

For responsible disclosure and supported-version policy, see SECURITY.md.

Support

For usage help and reporting guidance, see SUPPORT.md.

Changelog

Release history is tracked in CHANGELOG.md.

License

MIT License - see LICENSE for details.

---

Built by Bhanu Korthiwada