Codex CLI Guide

Codex CLI is OpenAI's lightweight local coding agent. It runs in your terminal, reads your codebase, edits files, and executes commands. Part of ChatGPT Plus/Pro/Business plans or usable with an API key.

Official docs: https://developers.openai.com/codex GitHub: https://github.com/openai/codex

Installation

# macOS / Linux (recommended)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Homebrew
brew install --cask codex

# npm (global)
npm install -g @openai/codex

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Authentication

codex   # On first run, select "Sign in with ChatGPT"

With API key instead:

export OPENAI_API_KEY=sk-...
codex

For full auth options: https://developers.openai.com/codex/auth

Basic Usage

# Start interactive session in current directory
codex

# One-shot task (non-interactive)
codex "add input validation to the login form"

# Quiet mode (minimal output)
codex -q "fix the TypeScript errors"

# Full auto mode (no confirmations — use carefully)
codex --approval-mode full-auto "refactor the API layer"

Approval Modes

Mode	Behavior
`suggest` (default)	Shows proposed changes, waits for approval
`auto-edit`	Edits files automatically, asks before shell commands
`full-auto`	Runs everything without asking (use in sandboxed environments)

codex --approval-mode auto-edit "clean up unused imports"
codex --approval-mode full-auto "run tests and fix failures"

Key Flags

Flag	Description
`--model <model>`	Specify model (`o4-mini`, `o3`, etc.)
`--approval-mode <mode>`	Set approval level
`-q` / `--quiet`	Minimal output
`--no-project-doc`	Ignore `AGENTS.md` / `CODEX.md`
`--project-doc <file>`	Use custom instructions file
`--full-stdout`	Show all shell output (not truncated)

AGENTS.md / CODEX.md (Project Instructions)

Codex automatically reads AGENTS.md from the project root (and parent directories). Put project-specific instructions there:

# Project Instructions
- Use TypeScript strict mode
- Run `npm test` to verify changes
- Never modify files in /dist directly

In this environment, AGENTS.md is already used by Silma's workspace. For a client project, create one in the repo root.

Using with Local LLMs

Codex CLI supports OpenAI-compatible endpoints:

# Point at local llama.cpp (Gemma models on Tabitha)
OPENAI_BASE_URL=http://localhost:8080/v1 \
OPENAI_API_KEY=local \
codex --model gemma-4-e4b "explain this codebase"

See tools/local-llm.llm.md for available local models and endpoints.

Working with This Environment

# Clone from Gitea first, then run codex in the repo
git clone http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git
cd aarete-doczyai-app
codex

# Load credentials before running if the task touches AWS/GitHub
source /Users/Tabitha/.openclaw/workspace/credentials/secrets.env
codex "deploy the latest build to Amplify"

IDE Integration

Codex also works as a VS Code / Cursor / Windsurf extension:

VS Code:   https://marketplace.visualstudio.com/items?itemName=OpenAI.codex
Cursor:    Install from Cursor extensions panel (search "Codex")

Tips

Start with suggest mode to review changes before they land
Use full-auto only in throwaway branches or sandboxed environments
For long-running tasks, use the Codex web app at https://chatgpt.com/codex (cloud-based, parallel agents)
Codex reads AGENTS.md — keep it concise and action-oriented

3.7 KiB Raw Blame History