How to Install Codex CLI and Run Your First Task

Codex CLI is a terminal-based coding agent from OpenAI, written in Rust. It runs locally, works with code in your repository, and executes tasks in an isolated environment. You can install it through the standalone installer, npm, Homebrew cask, or a binary from GitHub Releases.

After installation, choose how to connect: official OpenAI authentication through ChatGPT or an OpenAI API key, or a custom BetterToken API provider. Both paths run the same codex command; there is no separate BetterToken edition of Codex to install.

What You Need Before Installing

Baseline system requirements from the official installation guide:

Node.js is required only when installing via npm. The standalone installer, Homebrew cask, and GitHub Releases archive install a ready-to-run executable.

Official ChatGPT sign-in requires a ChatGPT account, while official API access requires a key from platform.openai.com. The BetterToken route requires your own BetterToken account and API key. Node.js is required by the automatic BetterToken provider setup script even if Codex itself was installed another way.

Installing Codex CLI

macOS and Linux — Standalone Installer

The simplest method; Node.js is not required:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

After installation finishes, verify the command:

codex --version

If you see a version number, the command is available.

macOS — Homebrew Cask

brew install --cask codex

npm — macOS, Linux, Windows

Node.js with a working npm is required. Check the minimum Node.js version in the engines field of the package on npmjs.com/@openai/codex.

npm install -g @openai/codex

If the codex command is not found after installation, the global npm directory is not in your PATH. Find the correct path:

npm config get prefix

Compare that directory with your shell's PATH, then restart the terminal. Do not append /bin blindly: the global executable layout depends on the OS and how Node.js was installed.

Linux — Binary from GitHub Releases

Ready-to-use Linux archives are available on github.com/openai/codex/releases:

• codex-x86_64-unknown-linux-musl.tar.gz — for x86_64
• codex-aarch64-unknown-linux-musl.tar.gz — for arm64

Extract the archive, rename the executable to codex, and place it in a directory on your PATH that you can write to.

Windows

Codex CLI can run natively on Windows or inside WSL2. The current Windows documentation recommends Windows 11 for native use; a fully updated Windows 10 installation is supported on a best-effort basis.

Native Windows (PowerShell). Official installer:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

When running natively, Codex isolates task execution through Windows Sandbox. The mode is set in ~/.codex/config.toml:

[windows]
sandbox = "elevated"

WSL2. Install the Linux version of Codex CLI inside WSL2 following the Linux instructions. For Linux tooling, OpenAI recommends keeping the project in the WSL filesystem rather than under /mnt/.

Connect the Same Codex CLI to BetterToken API

BetterToken does not replace Codex CLI with another application. The official codex executable installed above keeps working; only the model provider in config.toml changes. Use this route instead of official OpenAI authentication when model requests should go through BetterToken API.

First, create an BetterToken account and API key. Stop any running Codex process and clear old OpenAI variables that could override config.toml.

macOS and Linux:

unset OPENAI_API_KEY
unset OPENAI_BASE_URL

Windows PowerShell:

Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", $null, "User")
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", $null, "User")

Automatic BetterToken Provider Setup

The script configures only the BetterToken provider; it does not install Codex CLI itself. It requires Node.js. If no API key or model is passed as an argument, the script prompts for them in an interactive terminal, so do not put the secret in the command line.

macOS and Linux:

curl -fsSL https://bettertoken.ai/install-codex-provider.sh | bash

Windows PowerShell:

iwr https://bettertoken.ai/install-codex-provider.ps1 -OutFile "$env:TEMP\install-codex-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-codex-provider.ps1"

Use only the command for your operating system. In the resulting configuration, verify:

• base_url is https://bettertoken.ai/v1;
• wire_api is responses;
• model_provider matches the provider id in [model_providers.custom];
• requires_openai_auth is false;
• model was copied from the current GPT Key group on BetterToken's model page.

If CC Switch manages the configuration, do not replace its generated settings with a manual block from another guide. The official BetterToken Codex guide includes automatic, CC Switch, and manual setup paths.

Official OpenAI Authentication

The commands below apply to the official OpenAI route. With the BetterToken custom provider, codex login status does not verify BetterToken API; run a test task and check the response instead.

Sign In via ChatGPT

Run the command:

codex login

A browser will open — complete sign-in with your ChatGPT account. Codex saves the session locally; you will not need to sign in again on subsequent runs.

If you run codex without arguments before authenticating, the interface will also prompt you to sign in. The primary way to initiate sign-in is codex login.

Sign In via API Key

Do not pass the key as a command argument or print it with echo — the value will end up in your shell history.

Set OPENAI_API_KEY in the current environment or through a secrets manager. Do not put the value in the article, command, or output. Once the variable is set, pass it through stdin:

printenv OPENAI_API_KEY | codex login --with-api-key

The key value is not displayed on screen and does not enter the command history.

Verify Authentication

After signing in, check the status:

codex login status

The command shows the current authentication method or reports that you are not signed in.

If the status shows no authentication, repeat the sign-in using the appropriate method.

To sign out and remove saved credentials:

codex logout

The file ~/.codex/auth.json contains the access token — treat it like a password. Do not delete it manually: always use codex logout to clear it.

Authentication documentation: developers.openai.com/codex/auth. Reference for login subcommands and flags: developers.openai.com/codex/cli/reference.

Your First Task in a Test Repository

Start in a test repository so you do not affect working code. Clone any public repository, for example Codex itself:

git clone https://github.com/openai/codex codex-test
cd codex-test

Run a read-only task:

codex --sandbox read-only "Explain the entry point of this project"

The --sandbox read-only flag limits model-generated commands to reading. If Codex returns a meaningful description of the structure without changing files, the first run is complete.

To continue in the TUI with the same restriction, run:

codex --sandbox read-only

Type in the interface: What files are in this project and what does each do?

If you use the official OpenAI route, confirm that authentication is still active:

codex login status

If you use the BetterToken provider, a normal response confirms the connection. You can also open the BetterToken Dashboard and verify that the request, model, and input/output/cache token usage appear in usage history.

Troubleshooting

codex: command not found After npm install

Run npm config get prefix, compare the result with PATH, and restart the terminal. The exact executable path depends on the OS and how Node.js was installed, so do not append /bin blindly.

Browser Did Not Open When Signing In via ChatGPT

On a remote server without a graphical interface, first try the official device-code flow (beta):

codex login --device-auth

You must first enable it in ChatGPT security settings or workspace permissions. If it is unavailable, use API Key sign-in:

printenv OPENAI_API_KEY | codex login --with-api-key

The official authentication guide covers the callback, device code, and fallback options.

Codex Does Not Respond After Connecting BetterToken

Check five items: base_url is https://bettertoken.ai/v1, wire_api remains responses, the model ID comes from the current GPT Key group, model_provider matches [model_providers.custom], and old OPENAI_API_KEY or OPENAI_BASE_URL variables are not overriding the configuration. After editing config.toml, fully restart Codex in a new terminal.

codex login status Shows Not logged in

• ChatGPT sign-in: run codex login again and complete sign-in in the browser.
• API Key sign-in: make sure OPENAI_API_KEY is set in your working environment, then repeat printenv OPENAI_API_KEY | codex login --with-api-key.
• Do not delete ~/.codex/auth.json manually — use codex logout.

Codex CLI documentation: github.com/openai/codex. Connect the same Codex CLI to BetterToken API: docs.bettertoken.ai/en/ai-tools/codex.