Unlock AI-Powered Coding with OpenAI Codex CLI: Full Installation and Usage Guide

What is Codex CLI?

Codex CLI is an OpenAI‑provided command‑line AI programming assistant. It can generate code, explain snippets, fix bugs, refactor projects, and create shell scripts from natural‑language prompts. Unlike a regular ChatGPT chat, Codex can read, modify, and execute files in the local project after the user approves each action.

Prerequisite: Node.js

Codex CLI requires Node.js version 20 or newer. Verify the installation:

node -v
npm -v

If the version is lower than 20, install or upgrade Node.js.

Installing Node.js

macOS : Use the official installer or Homebrew: brew install node Linux (Ubuntu/Debian) :

sudo apt update
sudo apt install -y nodejs npm

For flexible version management, install nvm and use the LTS release:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm install --lts
nvm use --lts

Windows : Download the Windows installer, enable “Add to PATH”, and verify with node -v.

Installing Codex CLI

After Node.js is ready, install Codex CLI globally: npm install -g @openai/codex macOS/Linux users can also install via Homebrew: brew install codex Verify the installation: codex --version If the command is not found, ensure the global npm bin directory is in PATH or restart the terminal. As an alternative, download the binary from the GitHub releases page (e.g., codex-aarch64-apple-darwin.tar.gz for Apple Silicon or codex-x86_64-unknown-linux-musl.tar.gz for Linux) and place it in /usr/local/bin.

Authentication

The first run of codex prompts for login. Two methods are supported:

ChatGPT account (recommended) : OAuth login opens a browser for authorization and uses any active ChatGPT Plus/Pro/Enterprise subscription.

API key : Create ~/.codex/auth.json with the content {"OPENAI_API_KEY": "sk-your-api-key-here"} and set preferred_auth_method = "apikey" in ~/.codex/config.toml. Restart the terminal after editing.

Core Commands

codex

– launches an interactive TUI for chat, code generation, bug fixing, etc. codex exec "prompt" – non‑interactive mode; writes the result to stdout. Use --json for JSON output or --output-last-message file.txt to save the response. codex resume --last or codex resume <session-id> – restores a previous conversation. codex completion bash|zsh|fish – generates shell completion scripts.

Common Parameters for Efficiency

-m/--model

– specify the model (e.g., gpt-5-codex or gpt-4). -a/--ask-for-approval – approval mode with values untrusted, on-failure, on-request, never. --full-auto – fully automatic mode: generate code, install dependencies, run tests, and commit without further interaction. -i/--image – upload screenshots for UI debugging or error analysis. -C/--cd – set the working directory without changing the shell’s current directory. --sandbox – restrict permissions ( read-only, workspace-write, danger-full-access). --add-dir – grant access to additional directories.

Configuration Files

Two files control Codex behavior: ~/.codex/config.toml – global settings such as default model, approval mode, telemetry, and MCP server definitions. AGENTS.md (global or project‑level) – defines project‑specific instructions, coding standards, and commit conventions that Codex reads on startup.

Model Context Protocol (MCP) Integration

MCP allows Codex to connect to external tools and services. List configured servers: codex mcp list Add a new server, for example SQLite:

codex mcp add sqlite "npx" "-y" "@modelcontextprotocol/server-sqlite"

Community‑provided MCP servers exist for GitHub, file systems, databases, and generic APIs.

Practical Use‑Cases

Analyze a legacy codebase:

codex "Analyze the project structure, tech stack, main modules, and data flow"

Generate unit tests for a directory:

codex "Generate unit tests for all modules in the auth directory"

Refactor a React component:

codex "Convert this class component to a functional component with Hooks and use React 18 features"

Fix a bug using a screenshot: codex -i error-screenshot.png "Fix this error" Scaffold a REST API with full automation:

codex --full-auto "Create an Express + TypeScript CRUD API for users"

Run a security audit and output a report:

codex "Audit the codebase for security vulnerabilities and output a report"

FAQ / Common Issues

Command not found : Verify the global npm prefix with npm config get prefix and add its bin directory to PATH.

Connection timeout : Configure a proxy or correct base_url in config.toml, then restart the terminal.

EACCES errors : Install with sudo or configure npm to use a user‑local directory (e.g., ~/.npm-global).

401 Unauthorized : Ensure auth.json is valid JSON and that preferred_auth_method = "apikey" is set in config.toml. Restart the terminal after changes.

Updating Codex : Run npm update -g @openai/codex or npm i -g @openai/codex@latest.

Missing .codex folder on Windows : Show hidden files in Explorer or open %USERPROFILE% to locate the .codex directory.

Advanced Git Workflow

Before invoking Codex, create a Git checkpoint: git add -A && git commit -m "codex before task" If the result is unsatisfactory, revert to the previous state:

git checkout .
git reset --soft HEAD^

Conclusion

Codex CLI integrates into daily development workflows, handling code generation, testing, debugging, and refactoring with minimal friction. Combining it with version‑control checkpoints and appropriate configuration provides a safe, repeatable way to accelerate development while retaining the ability to roll back changes.