Codex CLI features

Codex ships with a rich set of workflows that go beyond a simple chat interface. Use this guide to understand what each experience unlocks and how to make the most of them.

Running in interactive mode

Codex launches into a full-screen terminal UI that can read your repository, make edits, and run commands as you iterate together. Use it whenever you want a conversational workflow where you can review Codex’s actions in real time.

codex

Once the session is open you can:

• Send prompts, code snippets, or screenshots (see image inputs) directly into the composer.
• Watch Codex explain its plan before making a change, and approve or reject steps inline.
• Press Ctrl+C or use /exit to close the interactive session when you’re done.

Resuming conversations

Codex stores your transcripts locally so you can pick up where you left off instead of repeating context. Use the resume subcommand when you want to reopen an earlier thread with the same repository state and instructions.

• codex resume launches a picker of recent interactive sessions. Highlight a run to see its summary and press Enter to reopen it.
• codex resume --last skips the picker and jumps straight to your most recent session.
• codex resume <SESSION_ID> targets a specific run. You can copy the ID from the picker, /status, or the files under ~/.codex/sessions/.

Non-interactive automations can resume too:

codex exec resume --last "Fix the race conditions you found"
codex exec resume 7f9f9a2e-1b3c-4c7a-9b0e-.... "Implement the plan"

Each resumed run keeps the original transcript, plan history, and approvals, so Codex can use prior context while you supply new instructions. Override the working directory with --cd or add extra roots with --add-dir if you need to steer the environment before resuming.

Models & reasoning

Codex defaults to gpt-5-codex on macOS and Linux, and gpt-5 on Windows. Switch models mid-session with the /model command, or specify one when launching the CLI.

codex --model gpt-5-codex

GPT-5-Codex

gpt-5-codex is optimized for agentic coding in Codex, with deeper tool use and repository awareness. It automatically adapts how long it thinks based on the difficulty of your task, so we recommend using the default reasoning level: medium. For especially hard tasks you can try to bump reasoning to high using the /model slash command in the middle of a conversation.

GPT-5-Codex-Mini

gpt-5-codex-mini model is a more cost efficient, but slightly less capable version of gpt-5-codex that can give you approximately 4x more usage.

Using other models

Codex works best with gpt-5-codex and gpt-5-codex-mini.

If you’re authenticating Codex with an API key, you can also point Codex at any model and provider that supports either the Chat Completions or Responses APIs to fit your specific use case.

Image inputs

Attach screenshots or design specs so Codex can read the pixels alongside your prompt. You can paste images into the interactive composer or provide files on the command line.

codex -i screenshot.png "Explain this error"

codex --image img1.png,img2.jpg "Summarize these diagrams"

Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for multiple images, and combine them with text instructions to provide additional context.

Running local code review

Type /review in the CLI to open Codex’s review presets. The CLI launches a dedicated reviewer that reads the diff you select and reports prioritized, actionable findings without touching your working tree.

• Review against a base branch lets you pick a local branch; Codex finds the merge base against its upstream, diffs your work, and highlights the biggest risks before you open a pull request.
• Review uncommitted changes inspects everything that’s staged, unstaged, or untracked so you can address issues before committing.
• Review a commit lists recent commits and has Codex read the exact change set for the SHA you choose.
• Custom review instructions accepts your own wording (for example, “Focus on accessibility regressions”) and runs the same reviewer with that prompt.

Each run shows up as its own turn in the transcript, so you can rerun reviews as the code evolves and compare the feedback.

Web search

Codex ships with a first-party web search tool that stays disabled until you opt in. Enable it in ~/.codex/config.toml (or pass the --search flag) and optionally allow network access if you’re running in the default sandbox:

[features]
web_search_request = true

[sandbox_workspace_write]
network_access = true

Once enabled, Codex can call the search tool when it needs fresh context. You’ll see web_search items in the transcript or codex exec --json output whenever Codex looks something up.

Running with an input prompt

When you just need a quick answer, run Codex with a single prompt and skip the interactive UI.

codex "explain this codebase"

Codex will read the working directory, craft a plan, and stream the response back to your terminal before exiting. Pair this with flags like --path to target a specific directory or --model to dial in the behavior up front.

Shell completions

Speed up everyday usage by installing the generated completion scripts for your shell:

codex completion bash
codex completion zsh
codex completion fish

Eval the completion script in your shell configuration file to set up the completions for new sessions. For example if you use zsh, you can add the following to the end of your ~/.zshrc file:

# ~/.zshrc
eval "$(codex completion zsh)"

Start a new session, type codex and press Tab to see the completions. If you see a command not found: compdef error, you need to enable compdef by adding autoload -Uz compinit && compinit to your ~/.zshrc file before the eval "$(codex completion zsh)" line and then restarting your shell.

Approval modes

Approval modes define how much Codex can do without stopping for confirmation. Use /approvals inside an interactive session to switch modes as your comfort level changes.

• Auto (default) lets Codex read files, edit, and run commands within the working directory. It still asks before touching anything outside that scope or using the network.
• Read Only keeps Codex in a consultative mode. It can browse files but won’t make changes or execute commands until you approve a plan.
• Full Access grants Codex the ability to work across your machine, including network access, without asking. Use it sparingly and only when you trust the repository and task.

Codex always surfaces a transcript of its actions, so you can review or roll back changes with your usual git workflow.

Scripting Codex

Automate workflows or wire Codex into your existing scripts with the exec subcommand. This runs Codex non-interactively, piping the final plan and results back to stdout.

codex exec "fix the CI failure"

Combine exec with shell scripting to build custom workflows, such as automatically updating changelogs, triaging issues, or enforcing editorial checks before a PR ships.

Working with Codex Cloud

The codex cloud command lets you triage and launch Codex Cloud tasks without leaving the terminal. Run it with no arguments to open an interactive picker, browse active or finished tasks, and apply the changes to your local project.

Alternatively you can start a task directly from the terminal:

codex cloud exec --env ENV_ID "Summarize open bugs"

Add --attempts (1–4) to request best-of-N runs when you want Codex Cloud to generate multiple solutions. For example, codex cloud exec --env ENV_ID --attempts 3 "Summarize open bugs".

Environment IDs come from your Codex Cloud configuration—use codex cloud and press Ctrl+O to choose an environment or the web dashboard to confirm the exact value. Authentication follows your existing CLI login, and the command exits non-zero if submission fails so you can wire it into scripts or CI safely.

Slash commands

Slash commands give you quick access to specialized workflows like /review, /plan, or your own reusable prompts. Codex ships with a curated set of built-ins, and you can create custom ones for team-specific tasks or personal shortcuts.

See the slash commands guide to browse the catalog of built-ins, learn how to author custom commands, and understand where they live on disk.

Model Context Protocol (MCP)

Connect Codex to additional tools by configuring Model Context Protocol servers. Add STDIO or streamable HTTP servers in ~/.codex/config.toml, or manage them with the codex mcp CLI commands—Codex launches them automatically when a session starts and exposes their tools next to the built-ins. You can even run Codex itself as an MCP server when you need it inside another agent.

See Model Context Protocol for example configs, supported auth flows, and a deeper walkthrough.

Tips & shortcuts

• Type @ in the composer to open a fuzzy file search over the workspace root; press Tab or Enter to drop the highlighted path into your message.
• Tap Esc twice while the composer is empty to edit your previous user message. Continue pressing Esc to walk further back in the transcript, then hit Enter to fork from that point.
• Launch Codex from any directory using codex --cd <path> to set the working root without running cd first. The active path is echoed in the TUI header.
• Expose additional writable roots with --add-dir (e.g., codex --cd apps/frontend --add-dir ../backend --add-dir ../shared) when you need to coordinate changes across multiple projects.