Codex CLI Cheatsheet: config, commands, AGENTS.md, + best practices

Codex CLI is OpenAI’s terminal-based coding agent and alternative to Claude Code. The harness itself is really fast, as it’s built in Rust.

It runs locally, reads your repo, makes code changes, and runs shell commands (all based on how you manage approvals). This cheat sheet covers installation through some more advanced config.

Getting started

Prereqs: Node.js 18+, macOS or Linux (Windows via WSL, experimental)

Install

npm i -g @openai/codex

Auth

On first launch, auth in via ChatGPT OAuth (browser flow) or pipe in an API key:

export OPENAI_API_KEY="YOUR_API_KEY"
codex

ChatGPT authentication gives you access to the latest models. API key access has delayed access to new models but is better for CI automation.

Plans

Codex CLI doesn’t have a free tier. Most devs using it for casual/light assistance will benefit from the Plus plan. API ends up being more expensive than a subscription for normal to high use, so you might want to reserve it for CI tasks.

Basic usage

Launch and use Codex CLI from your terminal.

Interactive TUI:

codex
codex "refactor this module for clarity"

Non-interactive / scripting:

codex exec "update the changelog for this diff"
codex e "run tests and fix any failures"   # short form

Resume a session:

codex resume           # shows picker
codex resume --last    # most recent

When you exit a Codex session, launching Codex will set you into a fresh session by default.

Models

Switch models with --model/-m or set a default in config.toml. You can change this mid-session with /model.

Codex also supports any model with a Chat Completions or Responses API endpoint.

Configuration

The main config file lives at ~/.codex/config.toml. Flags and -c key=value overrides take priority over context/config files.

Example ~/.codex/config.toml:

model = "gpt-5.3-codex"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[features]
multi_agent = true
shell_tool = true

Basic config fields

Named profiles let you switch between configs per-project or per-task:

[profiles.ci]
approval_policy = "never"
sandbox_mode = "workspace-write"

[profiles.paranoid]
approval_policy = "untrusted"
sandbox_mode = "read-only"

Load with codex --profile ci.

Project trust:

[projects."/home/user/work/my-repo"]
trust_level = "trusted"

Admin enforcement (requirements.toml) lets ops teams constrain approval policy, sandbox mode, and MCP server allowlists across an org.

See the full config reference and advanced config docs.

AGENTS.md

AGENTS.md is Codex’s equivalent of CLAUDE.md, which is a set of project instructions loaded before any task. Files are prioritized in this order:

1. ~/.codex/AGENTS.override.md
2. ~/.codex/AGENTS.md
3. Git root → current directory: AGENTS.override.md, then AGENTS.md, then fallback filenames

Files closer to the working directory take priority. When adding/editing, you might exceed the context cap, which is defined by project_doc_max_bytes (32 KiB default).

Generate a scaffold:

> /init

Example ~/.codex/AGENTS.md:

## Working agreements
- Always run `pnpm test` after modifying source files
- Prefer `pnpm` when installing dependencies
- Follow the ESLint config; do not disable rules inline

Example project-level AGENTS.md:

## Architecture
- Frontend: Next.js + TypeScript
- API: FastAPI (Python 3.12)
- DB: PostgreSQL via SQLAlchemy

## Conventions
- Use snake_case for Python, camelCase for TypeScript
- New endpoints need a corresponding integration test

Subsystem override (services/payments/AGENTS.override.md) overrides broader rules for that directory, which you might use for stricter rules.

You can also use TEAM_GUIDE.md or .agents.md as fallbacks by setting project_doc_fallback_filenames in config.toml.

See OpenAI’s AGENTS.md guide.

CLI flags

Use these flags outside a Codex CLI session to change its config.

Global flags

These flags apply to all subcommands.

Codex exec flags

Add these flags to the codex exec command.

Resume from exec:

codex exec resume --last        # resume most recent
codex exec resume SESSION_ID    # resume by ID

Codex feature flags

You can manage optional feature flags (from codex features) persistently in config.toml:

codex features list
codex features enable multi_agent
codex features disable apply_patch_freeform

Interactive slash commands

Type / during a Codex session to access these.

Session

Config

Dev tools

Other

Approval modes + sandbox

These modes are important for managing permissions, including Codex’s access to your filesystem. LLMs can hallucinate and delete files, install vulnerable packages, edit system files, etc. so make sure you review all agent actions. You can take more risks in sandboxes.

Approval policy

Sets when Codex pauses before executing:

Sandbox mode

Sets filesystem and shell access:

Combine --add-dir to grant access to specific directories instead of reaching for danger-full-access.

MCP integration

Extend Codex with Model Context Protocol servers. Configure them in config.toml:

[mcp_servers.my-db]
command = "/usr/local/bin/my-mcp-server"
env = { DB_URL = "postgres://..." }
timeout_secs = 30

List connected tools in-session with /mcp. Browse available connectors with /apps.

Here are some useful MCP servers that can make Codex more capable.

Scripting + CI

The exec subcommand runs Codex non-interactively (without the TUI or prompts, so final output will be stdout).

Pipe into a script:

codex exec "update CHANGELOG.md based on git log since last tag"

JSON output for CI parsing:

codex exec --json "run tests, summarize test failures" | jq '.message'

Save final response to file:

codex exec -o summary.md "generate a release summary for this diff"

In GitHub Actions:

- name: Auto-fix lint errors
  run: codex exec --full-auto "fix any ESLint errors, don't change logic"
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Sample workflows

Here are a few simple, common tasks that you can use Codex to tackle.

Code review

> /review
# or target a specific commit:
> review the changes in the last commit against main

Debug from a screenshot

codex -i error-screenshot.png "this UI is broken, investigate and fix it"

Refactor with guardrails

codex --full-auto -s workspace-write "migrate all fetch() calls to use the apiClient wrapper"

Feature from a design spec

codex -i figma-export.png "implement this component in React matching the design exactly"

Changelog automation

codex exec "write a CHANGELOG entry for the commits since v2.4.0 and append it to CHANGELOG.md"

Resources

• Codex CLI docs
• CLI reference
• Slash commands
• Config reference
• AGENTS.md guide

Need real environments to test and preview the features you write with Codex CLI? Try Shipyard free for 30 days.