Codex CLI

Codex CLI Skill

OpenAI Codex CLI (@openai/codex) is a lightweight, open-source AI coding agent that runs locally in the terminal. It can read, edit, and execute code in your project directory using GPT-5 models.

Quick Reference

Installation

npm install -g @openai/codex
# Authenticate (browser or API key)
codex           # launches TUI with browser auth
export OPENAI_API_KEY="sk-..."  # or use API key

Basic Usage

codex                              # Interactive TUI
codex "Fix the TypeScript errors"  # TUI with pre-filled prompt
codex exec "Run tests and fix failures"   # Non-interactive (CI/scripts)
codex e "Update CHANGELOG"         # Short alias for exec

Core Concepts

Approval Modes (-a / --ask-for-approval)

Controls when Codex pauses to ask before executing. The ONLY valid values are:

Note: --full-auto is a CLI-only shortcut (equivalent to -a on-request -s workspace-write). It is NOT a valid approval_policy config value. Values like "suggest", "auto-edit", or "full-auto" do not exist as config values.

Sandbox Modes (-s / --sandbox)

Controls filesystem and network access. The ONLY valid values are:

Note: There is no --no-sandbox flag or sandbox = "none" config option. To bypass the sandbox entirely, use --dangerously-bypass-approvals-and-sandbox (alias --yolo).

Common Combinations

# Safe daily development (recommended)
codex --full-auto "task"
# Equivalent to: -a on-request -s workspace-write

# Full automation (CI/scripts)
codex -a never -s workspace-write "task"

# Audit / review only
codex -s read-only "Review the codebase"

# Unrestricted (isolated environments ONLY)
codex --dangerously-bypass-approvals-and-sandbox "task"
# Alias: --yolo

Configuration (~/.codex/config.toml)

Config uses TOML format (not JSON). The file is config.toml, never config.json.

Minimal config

model = "gpt-5-codex"
approval_policy = "on-request"

Full config example

model = "gpt-5-codex"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false   # true to allow network

[features]
shell_snapshot = true    # faster repeated commands

[tui]
alternate_screen = "auto"
animations = true

Profiles (for different workflows)

Profiles use [profiles.<name>] (plural "profiles", not singular "profile"):

[profiles.ci]
model = "gpt-5-codex"
approval_policy = "never"

[profiles.review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "untrusted"

Use a profile: codex --profile ci "task" or codex -p ci "task", or set profile = "ci" at the top level as default.

Config precedence (highest → lowest)

1. CLI flags (--model, -c key=value)
2. Project config: .codex/config.toml in project root (trusted projects only)
3. User config: ~/.codex/config.toml
4. System/built-in defaults

Non-Interactive Mode (codex exec)

For CI pipelines and shell scripts, always use codex exec (not bare codex). The exec subcommand runs non-interactively and exits when done:

# Basic
codex exec "Update the CHANGELOG for v2.1.0"

# With options
codex exec \
  --full-auto \
  --model gpt-5-codex \
  --path /my/project \
  "Fix all TypeScript type errors"

# JSON output (for parsing)
codex exec --json "Find all TODO comments"

# Resume previous session
codex exec --resume <session-id> "Continue where we left off"

GitHub Actions example

- name: Run Codex
  run: |
    npm i -g @openai/codex
    codex exec --full-auto "Update CHANGELOG"
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

TUI Slash Commands

Keyboard shortcuts:

• Enter while running → inject new instructions
• Tab → queue follow-up for next turn
• Esc Esc → edit previous message / fork from that point
• !command → run local shell command, result feeds Codex

MCP Servers

Add third-party tools to Codex via Model Context Protocol:

# ~/.codex/config.toml
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "$GITHUB_TOKEN" }

[mcp_servers.my-api]
url = "https://my-server.example.com/mcp"

Run Codex itself as an MCP server (for other agents to consume) using the mcp subcommand (not a flag):

codex mcp
# Note: this is a subcommand, NOT "codex --mcp-server"

Network Access

By default, network is disabled in sandbox:

# Enable network for one run
codex -s workspace-write \
  -c 'sandbox_workspace_write.network_access=true' \
  "npm install and run tests"

Agent Skills (.codex/skills/)

Codex supports reusable skill bundles. Reference with $skill-name syntax in the TUI:

.codex/
  skills/
    my-skill/
      skill.md   # instructions for this skill

Usage in TUI: Use $my-skill to generate a new module

Troubleshooting

Key Flags Reference

For detailed reference, see: https://developers.openai.com/codex/cli/reference/