Codex usage basics: commands, examples, pitfalls

The Codex CLI is an AI coding agent that runs in your terminal. This guide covers the essentials: installation, authentication, and the commands you will actually use day to day.

Installation

Pick an installation method:

Authentication

The first time you run codex, it opens a browser for OpenAI authentication and stores your credentials locally.

Basic Codex commands

Interactive mode

Run codex to start an interactive session:

Non-interactive (exec mode)

Use codex exec for single tasks. Ideal 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. To run a model OpenAI does not serve, put it on a custom-provider profile instead.

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 find out you are rate-limited when you hit a 429. CodexUse monitors rate limits live per profile so you see the wall coming.

4. Single account limitation

The CLI handles one account at a time. CodexUse keeps multiple accounts in one app and switches between them instantly, with no re-authentication.

How to log out of Codex

To log out of the Codex CLI, remove the stored auth credentials. In CodexUse, switch to another profile instead of logging out at all.

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