Codex CLI

OpenAI Codex CLI (v0.116+) is an open-source AI coding agent that reads, edits, and runs code directly in your terminal. See the official docs (developers.openai.com).

Star on GitHub
...
Follow us on X
Buy Me a Coffee

#Getting Started

#Install & Run

$ npm install -g @openai/codex
$ npm install -g @openai/codex@latest   # upgrade

#Homebrew (macOS)

$ brew install codex

#First run

$ codex                          # launch interactive TUI
$ codex "Explain this codebase"  # with initial prompt

On first run you'll be prompted to sign in via ChatGPT or an API key.

#Shell completions

# Zsh – add to ~/.zshrc
$ eval "$(codex completion zsh)"

# Bash – add to ~/.bashrc
$ eval "$(codex completion bash)"

# Fish
$ codex completion fish | source

#Platform Support

Platform Status
macOS Stable
Linux Stable
Windows (WSL) Recommended
Windows (native) Experimental

#Authentication

$ codex login                # ChatGPT OAuth
$ codex login --device-auth  # device flow
# Pipe API key from env
$ printenv OPENAI_API_KEY | codex login --with-api-key
$ codex login status         # check auth state
$ codex logout               # remove credentials

#Subcommands

#Command Reference

Command Alias Status Description
codex Stable Launch interactive TUI
codex exec codex e Stable Run non-interactively (scripting)
codex review Stable Non-interactive code review
codex resume Stable Resume a previous session
codex fork Stable Fork a session into new thread
codex apply codex a Stable Apply Cloud task diff locally
codex login Stable Authenticate Codex
codex logout Stable Remove stored credentials
codex completion Stable Generate shell completions
codex features Stable Manage feature flags
codex app Stable Launch Codex desktop app
codex mcp Experimental Manage MCP servers
codex mcp-server Experimental Run Codex as an MCP server
codex cloud Experimental Browse and exec Cloud tasks
codex sandbox Experimental Run cmds inside sandbox
codex debug Experimental Debugging tools

#Exec (Non-interactive)

# Basic non-interactive run
$ codex exec "Fix the race condition"
$ codex e "Add unit tests for utils"

# Prompt from stdin
$ echo "Explain main.go" | codex exec -

# Prompt-plus-stdin (0.118+): pipe data AND pass a prompt
$ cat error.log | codex exec "Diagnose this log" -

# Output options
$ codex exec --json "Audit security"
$ codex exec -o last.txt "Summarize"

# Resume a previous exec session
$ codex exec resume --last "Fix the bugs"
$ codex exec resume <SESSION_ID> "Implement"

#Global Options

#All Flags

Flag Values Description
-m, --model string Model override (e.g. gpt-5.4)
-s, --sandbox see below Sandbox policy
-a, --ask-for-approval see below Approval policy
--full-auto flag workspace-write + on-request
--yolo flag Bypass all approvals/sandbox
-i, --image path Attach image(s) to initial prompt
-c, --config key=val Override a config value
-C, --cd path Agent working directory
-p, --profile string Config profile name
--search flag Enable live web search
--add-dir path Grant extra directory write access
--oss flag Use local OSS provider
--local-provider lmstudio/ollama Specify OSS provider
--enable feature Enable a feature flag
--disable feature Disable a feature flag
--no-alt-screen flag Inline TUI mode (no alt screen)
--remote ws://host:port Connect to remote app server
--remote-auth-token-env ENV_VAR Bearer token env var for remote WS
-V, --version Print version
-h, --help Print help

#Usage Examples

# Specify model
$ codex -m gpt-5.4 "Refactor the auth module"

# Auto mode (low friction)
$ codex --full-auto "Run tests and fix failures"

# Attach a screenshot
$ codex -i mockup.png "Implement this UI"

# Override config inline
$ codex -c model="gpt-5.4-mini" "Quick scan"

# Live web search
$ codex --search "Find the latest async syntax"

# Set working directory
$ codex -C ~/projects/api "Review this codebase"

#Sandbox & Approvals

#Sandbox Modes

Mode Description
read-only Inspect only, no edits without approval
workspace-write Edit workspace + run local commands
danger-full-access No restrictions (use in hardened envs)

#Approval Policies

Policy Description
untrusted Ask before all non-trusted commands
on-request Ask when going beyond sandbox boundary
never Never ask; all commands run automatically

#Presets

Preset Equivalent setting
--full-auto workspace-write + on-request
--yolo No sandbox + No approvals

Use /permissions in the TUI to change modes mid-session.

#Slash Commands

#Session Control

Command Description
/model Switch model / reasoning effort
/fast Toggle GPT-5.4 Fast mode
/permissions Adjust approval mode
/personality Set response style
/plan Enter planning mode
/status Show model, tokens, config
/compact Summarize to free context
/clear Clear chat + start fresh
/new New chat, keep CLI session
/fork Fork current conversation
/resume Resume saved session
/exit / /quit Exit the CLI

#Review & Code

Command Description
/review Launch code reviewer
/diff Show Git diff
/copy Copy latest Codex output
/mention Attach file to conversation
/init Generate AGENTS.md scaffold

#Tools & Debug

Command Description
/agent Switch active agent thread
/mcp List MCP tools
/apps Browse connector apps
/experimental Toggle experimental features
/statusline Configure TUI footer
/ps Show background terminals
/sandbox-add-read-dir Add readable dir (Windows)
/feedback Send logs to maintainers
/plugins Browse and manage plugins
/title Set terminal title for session
/debug-config Print config diagnostics
/logout Sign out of Codex

#Models

#Available Models

Model Speed Best for
gpt-5.4 ★★★ Default – coding + reasoning + workflows
gpt-5.4-mini ★★★★★ Subagents, light tasks, higher limits
gpt-5.3-codex ★★★★ Complex software engineering
gpt-5.3-codex-spark ★★★★★ Near-instant iteration (Pro only)

#Select a Model

$ codex -m gpt-5.4 "Your prompt"
$ codex -m gpt-5.4-mini "Quick task"
$ codex --oss    # local Ollama / LM Studio
# Mid-session: type /model in the TUI

#Configuration

#config.toml Keys

# ~/.codex/config.toml

# Model settings
model = "gpt-5.4"
model_provider = "openai"
model_reasoning_effort = "medium"  # low | medium | high

# Sandbox & approvals
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# Web search: cached | live | disabled
web_search = "cached"

# Review model override
review_model = "gpt-5.4"

# TUI appearance
[tui]
theme = "dark"
alternate_screen = true

# Profile example
[profile.ci]
model = "gpt-5.4-mini"
approval_policy = "never"
sandbox_mode = "workspace-write"

Use -p ci to activate a profile.

#Feature Flags

$ codex features list
$ codex features enable unified_exec
$ codex features disable shell_snapshot

# Per-session (not persisted)
$ codex --enable unified_exec
$ codex --disable shell_snapshot

#Config Locations

File Purpose
~/.codex/config.toml Global defaults
~/.codex/AGENTS.md Personal instructions
~/.agents/skills/ Personal skills
.agents/skills/ Repo-level skills
AGENTS.md Repo instructions

#Customization

#AGENTS.md

Persistent repo instructions, checked in alongside code:

## Build & test commands

- Install: `npm install`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions

- TypeScript strict mode
- No PII in logs
- Auth middleware on all routes

## Review guidelines

- Flag unhandled promise rejections

When to add rules:

  • Repeated agent mistakes
  • Recurring PR review feedback
  • Tag @codex add to AGENTS.md in GitHub

#Skills

Reusable workflows packaged as SKILL.md:

my-skill/
  SKILL.md      ← metadata + instructions
  scripts/      ← optional helper scripts
  references/   ← optional documentation
  assets/       ← optional templates

Example SKILL.md:

---
name: commit
description: Stage and commit changes
  in semantic groups.
---

1. Stage files in logical groups.
2. Group: feat → test → docs → chore
3. Write concise commit messages.

#MCP Servers

# Add a stdio server
$ codex mcp add myserver -- npx my-mcp-server

# Add an HTTP server
$ codex mcp add myserver \
    --url https://api.example.com/mcp

# With auth token
$ codex mcp add myserver \
    --url https://api.example.com/mcp \
    --bearer-token-env-var MY_TOKEN

# List / remove
$ codex mcp list
$ codex mcp remove myserver

# Run Codex itself as MCP server
$ codex mcp-server

#Session Management

#Resume Sessions

$ codex resume           # session picker
$ codex resume --last    # most recent session
$ codex resume --all     # across all directories
$ codex resume <ID> "Continue fixing tests"

Sessions stored at ~/.codex/sessions/

#Fork a Session

$ codex fork             # fork from picker
$ codex fork --last      # fork most recent
$ codex fork <SESSION_ID> "New direction"

Forking preserves the original transcript while starting a new branch.

#Image Inputs

# Single image
$ codex -i screenshot.png "Fix this error"

# Multiple images
$ codex --image img1.png,img2.jpg "Compare"

# Or drag images into the TUI composer

Supported: PNG, JPEG and other common formats.

#Cloud & GitHub

#Cloud Tasks

# Browse cloud environments
$ codex cloud

# Submit a cloud task
$ codex cloud exec --env <ENV_ID> "Fix bug"

# With multiple attempts (best-of-N)
$ codex cloud exec --env <ENV_ID> \
    --attempts 3 "Write failing tests"

# List recent tasks
$ codex cloud list

# Check task status
$ codex cloud status <TASK_ID>

# Show diff for a task
$ codex cloud diff <TASK_ID>

# Apply diff to local working tree
$ codex apply <TASK_ID>

#GitHub Integration

# In a PR comment – trigger code review:
@codex review

# Custom focus:
@codex review for security regressions

# Delegate any task using PR as context:
@codex fix the CI failures
@codex add tests for the new endpoint

Enable in Codex Settings → Code review → your repo. Turn on Automatic reviews to review every new PR.

#Subagent Workflows

#Subagents Guide

Offload noisy work to parallel agents to avoid context pollution and context rot:

codex "Review this branch with parallel agents.
Spawn one for security risks, one for test gaps,
and one for maintainability. Wait for all three,
then summarize findings with file references."
  • Use for: exploration, tests, triage, log analysis
  • Avoid parallel write-heavy work (conflicts)
  • Each subagent consumes extra tokens

Subagent model guide:

Role Model Reasoning
Main coordinator gpt-5.4 medium
Fast exploration gpt-5.4-mini low
Security / logic review gpt-5.4 high

#Reasoning Effort

Level Use when
high Complex logic, security audits
medium General tasks (default)
low Simple or speed-critical tasks

Set in config.toml:

model_reasoning_effort = "medium"

Or inline: -c model_reasoning_effort="high"

#Also See