Codex usage basics: commands, examples, pitfalls
The Codex CLI is an AI coding agent that runs in your terminal. This guide covers Codex usage essentials: installation, authentication, and the commands you will actually use.
Installation
Choose your preferred installation method:
Authentication
The first time you run codex, it opens a browser for ChatGPT authentication. Your credentials are
stored locally.
Alternative: API key authentication
If you have an OpenAI API key, you can use that instead of ChatGPT login:
Basic Codex commands
Interactive mode
Just run codex to start an interactive session:
Non-interactive (exec mode)
Use codex exec for single tasks, great for scripting:
Codex configuration
Codex configuration controls model selection, sandbox mode, and approval policy. Key settings include:
- model: Which AI model to use (default: gpt-5.1-codex-max)
- sandbox_mode: Controls what Codex can do (read-only, workspace-write, etc.)
- approval_policy: When to ask permission before actions
Understanding sandbox modes
| Mode | Can read files | Can write files | Network access |
|---|---|---|---|
read-only |
Yes (all) | No (asks permission) | No |
workspace-write |
Yes (all) | Yes (current directory) | No |
danger-full-access |
Yes (all) | Yes (anywhere) | Yes |
Common Codex usage patterns
Code explanation
Refactoring
Bug fixing
Test generation
Common Codex usage pitfalls
1. Wrong model name
If you specify a model that does not exist, Codex will error. Valid models include gpt-5.1-codex-max, gpt-4o, o3, and o4-mini.
2. Sandbox blocking needed operations
If Codex cannot write files or access the network when you expect it to, check your sandbox_mode setting.
3. Rate limits with no warning
The CLI does not show remaining quota. You only know you are rate-limited when you hit a 429 error. CodexUse can help by monitoring usage across accounts.
4. Single account limitation
The CLI only supports one account at a time. To manage multiple accounts without constant re-authentication, use CodexUse.
How to log out of Codex
To log out of Codex CLI, you can remove the stored auth credentials. With CodexUse, you can simply switch to a different profile instead of fully logging out.
Tips for effective Codex usage
- Be specific: "Fix the bug" is worse than "Fix the null pointer exception in handleSubmit"
- Point to files: "Look at validator.ts and add email validation" is better than "add email validation somewhere"
- Use AGENTS.md: Create a file at your project root with context about your codebase
- Check changes: Review the diff before accepting
Related
How do I install the Codex CLI?
Use npm install -g @openai/codex or brew install codex on macOS.
What is the difference between interactive and exec mode?
Interactive mode (codex) is for conversation-style work. Exec mode (codex exec)
runs a single task and exits.
How do I log out of Codex?
Remove the stored auth credentials, or use CodexUse to switch profiles instead.