Codex CLI is OpenAI's open-source coding agent that runs in your terminal. It can read your code, propose and make changes, and run commands, with approval controls you choose.
OpenAI also offers Codex as an IDE extension and in the cloud. This guide focuses on the CLI. Compare every step with the official repository, as installation details can change.
What you need
- macOS or Linux. On Windows, OpenAI recommends using WSL for the best experience
- A ChatGPT plan that includes Codex, or an OpenAI API key
- npm (included with Node.js) or Homebrew on macOS
- Git is recommended so you can review and undo changes
Step-by-step
- 1
Install with npm
Install the Codex CLI globally using npm.
npm install -g @openai/codex - 2
Or install with Homebrew (macOS)
On macOS you can install Codex with Homebrew instead. Check the official README for the current Homebrew command.
brew install --cask codex - 3
Start Codex in your project
Go to your project folder and run codex.
cd path/to/your-project codex - 4
Sign in
Choose "Sign in with ChatGPT" to use your ChatGPT plan, and complete the sign-in in your browser. Alternatively, you can use an OpenAI API key as described in the official docs.
- 5
Understand approval modes
Codex lets you control how much it can do without asking, for example read-only, asking before edits and commands, or more automatic modes. Start with a mode that asks for approval, and review changes before accepting them.
- 6
Try a first task
Ask Codex to explain your repository, then request a small change, such as adding a missing test. Review the proposed diff before approving.
Common errors
npm permission errors when installing globally
Avoid sudo. Configure npm to use a user-owned global directory, or use a Node version manager.
"codex: command not found"
Open a new terminal so your PATH refreshes, and confirm the npm global bin folder is on your PATH.
Sign-in does not complete
Make sure the browser window opened by Codex can reach the local callback. If you are on a remote machine, follow the official docs for headless sign-in or use an API key.
Issues on native Windows
Install and run Codex inside WSL as recommended by OpenAI.
Tips
- Work on a Git branch so you can discard changes you do not like.
- Add an AGENTS.md file to your repository with project instructions Codex should follow.
- Never commit API keys. Store them in environment variables.
Official resources
FAQ
AI Setup Studio is an independent technical services company. We are not affiliated with, endorsed by, or sponsored by OpenAI, Anthropic, Google, Microsoft, GitHub, Cursor, Ollama, n8n, Make, or any other AI tool vendor unless expressly stated. Product names are trademarks of their respective owners and are used only to describe compatibility.