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:

Mode	Flag	Config value	Behavior
`untrusted`	`-a untrusted`	`approval_policy = "untrusted"`	Max caution — approves almost everything
`on-request`	`-a on-request`	`approval_policy = "on-request"`	Asks on sensitive actions (default for auto)
`never`	`-a never`	`approval_policy = "never"`	Never asks — runs fully automated
`reject`	`-a reject`	`approval_policy = "reject"`	Blocks all tool use

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:

Mode	Flag	Access
`read-only`	`-s read-only`	Read files only, no writes
`workspace-write`	`-s workspace-write`	Write within working directory only
`danger-full-access`	`-s danger-full-access`	Full system access (use with caution)

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)

CLI flags (--model, -c key=value)
Project config: .codex/config.toml in project root (trusted projects only)
User config: ~/.codex/config.toml
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

Command	Effect
`/status`	Show model, approval policy, token usage, workspace roots
`/permissions`	Change approval mode interactively
`/model`	Switch model mid-session
`/clear`	Clear transcript, start fresh conversation
`/copy`	Copy latest Codex output to clipboard
`/plan`	Enter plan mode
`/review`	Review changes in working tree
`/mcp`	List available MCP tools
`/agent`	Switch between agent threads
`/feedback`	Submit feedback
`/logout`	Clear stored credentials

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

Problem	Fix
Approval prompts won't stop	Check `/status`, restart with explicit `-a` flag or profile
Network access denied	Add `-c 'sandbox_workspace_write.network_access=true'`
Sandbox ENOENT on macOS	Run `xcode-select --install`, check dir permissions
Landlock error on Linux/WSL	Update WSL2 or use `--dangerously-bypass-approvals-and-sandbox` in isolated env
Auth loop / browser keeps opening	Run `codex logout`, then `rm -f ~/.codex/auth.json`, use `OPENAI_API_KEY`
Settings reset after reconnect	Use a named profile in `config.toml`

Key Flags Reference

Flag	Short	Description
`--ask-for-approval`	`-a`	Approval mode: `untrusted`, `on-request`, `never`, `reject`
`--sandbox`	`-s`	Sandbox mode: `read-only`, `workspace-write`, `danger-full-access`
`--full-auto`		Shortcut: `-a on-request -s workspace-write`
`--dangerously-bypass-approvals-and-sandbox`	`--yolo`	No restrictions (isolated envs only)
`--model`	`-m`	Override model for this run
`--profile`	`-p`	Load named profile from config.toml
`--cd`		Set working directory without cd
`--config`	`-c`	Override any config key: `-c model=gpt-4.1`
`--json`		Output newline-delimited JSON events
`--oss`		Use local Ollama provider
`--images`		Attach images to prompt (comma-separated paths)
`--live-search`		Enable live web search
`--resume`		Resume previous session by ID
`--no-persist`		Don't write session rollout files to disk

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

codex-cli