OpenAI Codex reference
OpenAI Codex commands and CLI guide
Look up Codex CLI commands, slash actions, permission settings, configuration paths, and common workflows. Copy an entry, then check release-specific options in your local installation.
Updated July 29, 2026. Release-dependent features are marked "Check locally".
01 / Choose the right surface
Match the interface to the job
Choose the Codex interface that gives your task the context and controls it needs.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 reference, filter by purpose, or pin entries you use often.
/
03 / Set a clear operating boundary
Safe launch builder
Select the access and workspace options you need, then review the suggested command and its trade-offs.04 / Turn intent into a testable brief
Codex prompt builder
Describe the result you want, the evidence to use, and any limits the task should follow.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
See where to put personal settings, repository instructions, scoped rules, 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 relevant project files. Add more context only when the task needs it.- 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 crosses roots.
- 5Web, MCP, apps
Connect external information last, after reviewing permissions and data boundaries.
07 / Follow a reliable route
Practical Codex workflows
These workflows show the commands and checks involved, from the first request through 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