The complete reference guide for OpenAI's open-source terminal coding agent. Interactive sessions, sandbox security, local models, MCP integration, and more.
npm i -g @openai/codex · v2026The commands and flags you will reach for most often
01 / Setup
Codex CLI is OpenAI's open-source coding agent built in Rust. It runs locally from your terminal, reads your codebase, makes edits, and executes commands while you review in real time.
You can also download platform-specific binaries directly from github.com/openai/codex/releases.
The first time you run Codex, it will prompt you to sign in. You have two options:
02 / TUI
Codex launches into a full-screen terminal UI where you can converse with the agent, review its actions in real time, and iterate on tasks together.
Type / in the composer to open the slash command popup. These are available during interactive sessions:
| Command | Description |
|---|---|
| /model | Switch between models (gpt-5-codex, gpt-4.1, gpt-4.1-mini, etc.) |
| /review | Launch the code reviewer on current changes or against a branch |
| /mcp | View and manage active MCP servers |
| /resume | Open picker to reload a saved session transcript |
| /fork | Branch a new session from a previous one, leaving the original intact |
| /status | Show current session info (ID, model, sandbox, etc.) |
| /help | List all supported slash commands and shortcuts |
| /exit | Exit the interactive session (also /quit) |
| Key | Action |
|---|---|
| @ | Fuzzy file search over workspace root |
| Up/Down | Navigate draft history in composer |
| Esc x2 | Edit previous user message; keep pressing to walk back |
| Enter | Fork from selected point after Esc walkback |
| Tab/Enter | Select file from @ search results |
| Key | Action |
|---|---|
| Enter | Inject new instructions into current turn |
| Tab | Queue a follow-up prompt for next turn |
| Ctrl+C | Stop current task / close session |
| Alt+M | Cycle through available models |
| Alt+E | Cycle through reasoning effort levels |
03 / Scripting
Use codex exec for scripted or CI-style runs that finish without human interaction. Pipe results to stdout for downstream processing.
--sandbox workspace-write only when the task requires file changes.
A dedicated code review mode that analyzes diffs and reports prioritized, actionable findings without modifying code.
04 / Models
Switch between OpenAI's flagship models, lightweight variants, and open-source models running locally through Ollama or LM Studio.
| Model | Type | Best For |
|---|---|---|
| gpt-5-codex | Flagship | Complex reasoning, large refactors, architecture decisions |
| gpt-5.3-codex | Enhanced | Improved code generation with latest capabilities |
| gpt-4.1 | General | Balanced performance for everyday coding tasks |
| gpt-4.1-mini | Fast | Quick edits, simple tasks, low latency |
| gpt-oss:20b | Local | Local inference, privacy-sensitive codebases |
| gpt-oss:120b | Local | High-quality local inference, larger codebases |
Pass --oss to route inference through a local provider like Ollama or LM Studio. All processing happens on your machine -- no data sent to the cloud.
05 / Security
The OS-enforced sandbox limits what Codex can touch on your filesystem and network. Choose the right level of access for each task.
| Command | Default Sandbox | Reasoning |
|---|---|---|
| codex | workspace-write | Interactive development needs file edits |
| codex exec | read-only | Scripted runs should be minimal-permission |
| codex review | read-only | Reviews should never modify code |
06 / Permissions
Control when Codex must stop and ask for permission before executing commands. Match the policy to your trust level and workflow.
| Policy | Behavior | Best For |
|---|---|---|
| untrusted | Only known-safe read-only commands (ls, cat, sed) auto-run; everything else prompts | Unfamiliar codebases, high-security |
| on-request | Model decides when to ask for approval (default) | Balanced interactive work |
| on-failure | Auto-run all commands in sandbox; prompt only when a command fails | Fast iteration with a safety net |
| never | Never prompt for approval (risky) | CI/CD pipelines, trusted automation |
--full-auto is a convenience flag that combines the safest automatic settings:
--dangerously-bypass-approvals-and-sandbox disables ALL safety checks. Only use when you fully understand the risks and trust the task completely.
07 / Extensibility
Model Context Protocol connects Codex to third-party tools and context -- documentation sites, browsers, databases, design tools, and more.
Codex can itself act as an MCP server, exposing the entire agent as a tool for external applications and multi-agent pipelines.
08 / Sessions
Codex stores session transcripts locally so you can resume, fork, or apply changes across multiple CLI invocations without losing context.
Create a new session branched from a previous one. The original transcript stays untouched while you explore an alternative approach.
Apply generated patches and diffs from Codex output:
Run tasks in the cloud for more compute, longer execution times, and access to larger models:
Sessions are stored as JSONL files at ~/.codex/sessions/. You can inspect, back up, or clean up old sessions manually.
09 / Config
Codex reads its configuration from ~/.codex/config.toml. Use profiles to maintain different setups for different workflows.
Profiles let you define named configuration presets. Load them with --profile or -p.
Feature flags control optional and experimental capabilities. Manage them from the CLI or in config.toml:
10 / Reference
Complete reference of every command-line flag organized by category.
| Flag | Short | Description |
|---|---|---|
| --help | -h | Show help information |
| --version | -V | Display version |
| --model <MODEL> | -m | Override model set in configuration |
| --profile <NAME> | -p | Load configuration profile from config.toml |
| --config <KEY=VALUE> | -c | Override configuration value inline |
| --cd <PATH> | Change working directory before starting |
| Flag | Short | Description |
|---|---|---|
| --sandbox <MODE> | -s | Set sandbox: read-only, workspace-write, danger-full-access |
| --ask-for-approval <POLICY> | -a | Set approval: untrusted, on-request, on-failure, never |
| --full-auto | Convenience: -a on-request -s workspace-write | |
| --dangerously-bypass-approvals-and-sandbox | Disable all safety checks (dangerous) | |
| --add-dir <PATH> | Add extra writable directory to sandbox |
| Flag | Description |
|---|---|
| --oss | Use local open-source provider (Ollama, LM Studio) |
| --provider <NAME> | Specify model provider |
| --local-provider | Use local model provider |
| Flag | Short | Description |
|---|---|---|
| --image <PATH> | -i | Attach image(s) to prompt |
| --json | Output as JSON Lines (JSONL) for scripting | |
| --output-schema <PATH> | Request response conforming to JSON Schema | |
| --search | Enable web search during execution | |
| --no-alt-screen | Disable alternate screen mode for TUI |
| Flag | Description |
|---|---|
| --enable <FEATURE> | Enable a feature flag for this session |
| --disable <FEATURE> | Disable a feature flag for this session |
| --last | Resume or fork the most recent session |
| --all | Show sessions from all directories (with resume) |
| Command | Alias | Description |
|---|---|---|
| codex | Start interactive TUI session | |
| codex exec | codex e | Non-interactive execution |
| codex review | Code review mode | |
| codex resume | Resume a previous session | |
| codex fork | Fork a previous session | |
| codex apply | codex a | Apply diffs and patches |
| codex login | Authenticate with OpenAI | |
| codex logout | Clear authentication | |
| codex mcp | Manage MCP servers (list, get, add, remove) | |
| codex mcp-server | Run Codex as an MCP server | |
| codex features | Manage feature flags (list, enable, disable) | |
| codex completion | Generate shell completion scripts | |
| codex cloud | Cloud task management | |
| codex sandbox | codex debug | Sandbox debugging |
| codex app-server | Run app server mode |
11 / Expert
Patterns, aliases, and workflows used by power users to get the most out of Codex CLI.
-s read-only for analysis, then switch to --full-auto when ready to implement.--cd apps/frontend --add-dir ../backend to coordinate changes across repos.-a on-failure to auto-run everything and only stop when something breaks.--oss -m codellama:34b for sensitive codebases. All inference stays on-device.--sandbox read-only--add-dir instead of danger-full-access~/.codex/sessions/