Quick Reference
Reference
intermediate
Codex CLI Quick Reference Card
Getting Started
# Install (pick one)
brew install --cask codex
# or: curl -fsSL https://chatgpt.com/codex/install.sh | sh
# or: npm install -g @openai/codex
# Authenticate (pick one)
codex auth login # ChatGPT account (recommended)
export CODEX_API_KEY="sk-..." # API key (for automation)
# First run
codex "explain what this project does"Approval Policies
| Policy | Command | You Review | Best For |
|---|---|---|---|
| Untrusted (default) | codex "..." |
Before every change | Learning, risky tasks |
| On-request | codex --approval-policy on-request "..." |
Shell commands only | Standard work |
| Never | codex --approval-policy never "..." |
After the fact | Automation, CI/CD |
Command Quick Reference
| Command | Purpose |
|---|---|
codex "prompt" |
Run with a prompt |
codex --model gpt-5.5 "prompt" |
Use specific model |
codex --approval-policy never --sandbox danger-full-access "prompt" |
No approval needed |
codex --approval-policy on-request "prompt" |
Auto-apply, ask to commit |
Configuration Files
| File | Purpose | Scope |
|---|---|---|
AGENTS.md |
Project instructions | Per-project |
~/.codex/instructions.md |
Personal defaults | All projects |
~/.codex/config.toml |
CLI settings | All projects |
AGENTS.md Minimal Template
# Project: [Name]
Stack: [Language] + [Framework]
## Commands
- Build: [command]
- Test: [command]
- Lint: [command]
## Conventions
- [Rule 1]
- [Rule 2]
## Do NOT
- [Constraint 1]
- [Constraint 2]Sandbox Capabilities
| Can Do | Cannot Do |
|---|---|
| Read/write project files | Access network |
| Run local scripts | Access other directories |
| Execute tests | Modify system files |
| Git operations (local) | Push to remote |
| Install packages (cached) | Access databases |
Prompt Formula
[ACTION] + [TARGET] + [CONSTRAINT] + [VERIFICATION]
| Element | Example |
|---|---|
| Action | "Fix", "Add", "Refactor", "Create" |
| Target | "the auth middleware in src/middleware/auth.ts" |
| Constraint | "without changing the public API" |
| Verification | "and run the tests to confirm" |
Effective Prompt Examples
# Bug fix
codex "fix the null pointer in src/utils/parse.ts line 23. Error: Cannot read property 'name' of undefined"
# Feature
codex "add rate limiting to all POST routes in src/api/ - max 10 requests per minute per IP"
# Refactor
codex "extract the validation logic from src/controllers/user.ts into a separate src/validators/user.ts module"
# Tests
codex "write comprehensive tests for src/lib/cart.ts covering empty cart, add, remove, and total calculation"Decision Guide: Which Mode?
Is the task well-understood? ──No──> Suggest mode
│
Yes
│
Does it touch sensitive files? ──Yes──> Suggest mode
│
No
│
Is it a safe, repeatable task? ──Yes──> Full auto
│
No
│
Auto-edit mode
Interactive Session Controls
| Key | Action |
|---|---|
y / Enter |
Accept proposed changes |
n |
Reject changes |
e |
Edit changes before accepting |
q |
Quit the session |
| Ctrl+C | Cancel current operation |
Common Mistakes to Avoid
| Mistake | Better Approach |
|---|---|
| Vague prompts ("make it better") | Specific instructions ("add error handling for null inputs") |
| Huge scope in one prompt | Break into 3-5 focused prompts |
| Skipping review in full-auto | Use auto-edit for unfamiliar tasks |
| Not running tests after | Always verify with npm test |
| No AGENTS.md | Add one with at least conventions + commands |
| Ignoring sandbox limits | Pre-install deps, mock network calls |
Workflow: From Zero to Feature
# 1. Plan
codex "describe how you would implement [feature] given the current codebase"
# 2. Scaffold
codex --approval-policy on-request "create the file structure for [feature]"
# 3. Implement
codex --approval-policy on-request "implement the core logic for [feature] in [file]"
# 4. Test
codex --approval-policy on-request "write tests for [feature]"
# 5. Verify
codex "run all tests and report any failures"