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 OpenAI authentication. Your credentials are stored locally.

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 Codex model to use, such as gpt-5.3-codex, gpt-5.2-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, or gpt-5.2
• sandbox_mode: Controls what Codex can do (read-only, workspace-write, etc.)
• approval_policy: When to ask permission before actions

Understanding sandbox modes

• read-only: no writes without approval.
• workspace-write: writes limited to the current workspace.
• danger-full-access: unrestricted access.

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 depend on your auth provider. Check your CLI docs for the current list.

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 rate limits per profile (Pro).

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