Using Codex CLI
Everyday use, passing flags to Codex, switching between subscriptions, upgrading gcodex, and what it changes.
gcodex is a launcher for the official Codex CLI: it handles sign-in and forwarding, and what opens is still the official codex. Your MCP servers, skills, global instructions, profiles and session history in ~/.codex all keep working.
Everyday use
--model, --profile and -c flags after -- are passed to Codex unchanged, but -c can't override model_provider, openai_base_url, chatgpt_base_url or cli_auth_credentials_store. The following would bypass ReCodex and are therefore rejected: --remote, --oss, --local-provider, and gcodex agents.
Common commands
| Command | What it does |
|---|---|
gcodex | Open Codex CLI (starts the background service on first run) |
gcodex login | Authorize this computer in your browser; add --no-browser to print the link without opening a browser |
gcodex status | Show the background service, subscription status and Codex path |
gcodex sub list | List all your subscriptions and which ones are bound on this computer |
gcodex sub bind <subscription ID> | Bind another subscription on this computer (approve it in the browser) |
gcodex sub use <subscription ID> | Switch the subscription this computer uses by default (must be bound here) |
gcodex logs -f | Follow the background service log, handy when troubleshooting |
gcodex stop | Stop the background service; running Codex CLI / Desktop sessions are interrupted |
gcodex update | Download or update the official codex (see "Upgrade" below) |
gcodex logout | Sign out of every subscription on this computer and restore ~/.codex to how it was before |
gcodex version | Show the gcodex version |
gcodex help <command> | Show detailed help for a command |
gcodex logout only cleans up this computer; it doesn't free the device slot in the console. To free it, revoke the device on the Devices page.
Switch between subscriptions
You can also pick the subscription for a single launch with gcodex --subscription <subscription ID> (it must also be bound on this computer). Note that the CLI and Desktop share one sign-in configuration: after launching with a different subscription, restart any Codex CLI / Desktop that is already running.
To switch to another ReCodex account, run gcodex logout, then complete gcodex login in the browser with the other account.
Upgrade gcodex
Run the install command again; it upgrades to the latest version:
curl -fsSL https://recodex.cc/install.sh | bash && . "$HOME/.recodex/env"- A background service that is already running doesn't switch to the new version by itself. Finish your current sessions, run
gcodex stop, and the next launch uses the new version; check withgcodex version. - On Windows the installer refuses to upgrade while a gcodex session is running; finish it first.
- The first
gcodex desktop runafter an upgrade asks for administrator authorization once more.
Upgrading gcodex and upgrading Codex are different things
The commands above only upgrade gcodex. After you've run gcodex update, gcodex (and the codex command in macOS / Linux terminals) prefers the copy it downloaded to ~/.recodex/bin/codex, so keep updating it with gcodex update. If you'd rather use the version installed via npm or Homebrew, don't run gcodex update; if you already did, delete ~/.recodex/bin/codex.
What it changes
- Configuration and sign-in in
~/.codex: the firstgcodex loginfully backs up~/.codex/config.tomlandauth.json(to~/.recodex-desktop/backup/), then writes ReCodex's managed settings and a placeholder sign-in. MCP servers, skills, global instructions, profiles and session history are not affected. - Settings with the same name are replaced: the top-level
model,model_provider,openai_base_url,chatgpt_base_urlandcli_auth_credentials_storeinconfig.tomlare replaced by managed values (the originals are backed up). To change the model, usegcodex -- --model …or a profile. - Running the official codex directly: while managed, running
codexdirectly or opening Desktop from the Dock uses the placeholder sign-in, not your own ChatGPT account. To restore everything, rungcodex logout; uninstalling ReCodex also restores it. - Environment of the Codex process: Codex launched through gcodex doesn't read
OPENAI_API_KEY,OPENAI_BASE_URL,CODEX_HOMEor similar variables from your shell, and proxy variables are replaced with the local ReCodex proxy. Scripts or MCP servers run inside Codex can't reachapi.openai.com.
Account, subscriptions & codes
Redeem codes, read subscription status, manage devices, and use messages, points and support tickets in the recodex.cc console.
Using Codex Desktop
Open the official Codex Desktop through ReCodex, see what it changes and how it affects the whole computer, and restore everything afterwards.