OpenAI Codex field guide
OpenAI Codex Command Cheatsheet and CLI Guide
Find the command, slash action, permission setting, configuration path, or workflow you need—then copy it without breaking your flow.
Updated July 29, 2026 · Release-dependent features are marked “Check locally”.
01 / Choose the right surface
Match the interface to the job
Start with the smallest Codex surface that gives the task enough context, control, and visibility.Interactive CLI
Explore, discuss, and iterateUse the terminal interface when the task needs conversation, approvals, or course correction.
Exec
Script a bounded taskUse non-interactive execution for repeatable checks, CI steps, and output pipelines.
Review
Inspect a diffUse the dedicated review command for working-tree, branch, or commit-focused feedback.
Sessions
Continue or branch workResume saved context or fork a session when you want to explore another route.
Extensions
Connect trusted toolsUse MCP, skills, and plugins when the task genuinely needs external capabilities.
02 / Search the command graph
Commands, flags, shortcuts, paths, and concepts
Search the full reference, filter by purpose, and pin the cards you reach for most.
/
03 / Set a clear operating boundary
Safe launch builder
Choose what the task needs and get a conservative starting command with the tradeoff explained.04 / Turn intent into a testable brief
Codex prompt builder
Give Codex an outcome, evidence, boundaries, and a definition of done.Attach only the files and external tools the task actually needs. Narrow context usually produces clearer evidence and easier review.
05 / Put durable context in the right place
Codex path map
Separate personal defaults, repository guidance, scoped overrides, and reusable workflows.User defaults~/.codex/config.toml
Default model, sandbox, approvals, web search, interface settings, and MCP servers for the current user.
Named profile$CODEX_HOME/<name>.config.toml
A focused configuration layer activated with --profile, useful for review, automation, or restricted workflows.
Repository guidanceAGENTS.md
Project build commands, conventions, architectural boundaries, and verification requirements that travel with the repository.
Scoped overrideAGENTS.override.md
Directory-specific guidance that takes priority within its scope. Keep overrides narrow and deliberate.
Repository skill.agents/skills/<name>/SKILL.md
A reusable project workflow with optional scripts, references, and assets.
Personal skill~/.agents/skills/<name>/SKILL.md
A reusable workflow available across repositories for the current user.
06 / Build context deliberately
Context decision ladder
Start with the repository and expand only when the result lacks the evidence it needs.- 1Working directory
Start Codex in the smallest relevant project root.
- 2
@file mentionsAttach the known entry point, failing test, or configuration file.
- 3
AGENTS.mdUse durable repository guidance for commands, conventions, and boundaries.
- 4
--add-dirGrant a specific adjacent directory only when the task truly crosses roots.
- 5Web, MCP, apps
Connect external information last, after reviewing permissions and data boundaries.
07 / Follow a reliable route
Practical Codex workflows
Each route keeps scope, action, and verification visible from the first command to the final diff.Understand a repository
Build an evidence-based map before requesting changes.
- Root
Start with inspection-only access in the repository root.
- Ask
Request a concrete map instead of a generic summary.
- Attach
Mention the entry file or failing test when you know it.
- Check
Confirm model, permissions, writable roots, and context state.
Implement a focused change
Make a bounded edit with explicit constraints and verification.
- Scope
Allow edits only inside the working directory.
- Brief
State what may change and what must remain stable.
- Steer
Inject an urgent correction or queue the next instruction while work runs.
- Verify
Inspect every changed file, then run focused tests.
Review before merge
Find actionable defects in the exact change set.
- Choose
Compare the branch with the merge target.
- Focus
Name the defect classes that matter.
- Verify
Review local follow-up edits before committing.
- Decide
Combine agent review with deterministic project checks.
Automate structured analysis
Produce machine-readable output while keeping access narrow.
- Isolate
Avoid edits and session persistence for a temporary audit.
- Shape
Define the expected final response structure.
- Stream
Capture event JSONL and the final message separately.
- Fail
Catch unsupported configuration before CI work begins.
08 / Before Codex acts
Keep powerful workflows reviewable
- Start narrow: use read-only for discovery and workspace-write for bounded implementation.
- Inspect commands: review installers, package scripts, migrations, and destructive operations before approval.
- Review the diff: agent summaries are useful, but the changed files and test output are the evidence.
- Protect secrets: do not place credentials in prompts, checked-in instructions, screenshots, or command history.
- Vet extensions: MCP servers, apps, plugins, hooks, and skills can expand access and shape future behavior.
- Isolate unattended work: never disable both approvals and sandboxing unless a dedicated external sandbox provides the boundary.
Fast local checks