Skip to main content

​
Syntax

codex [OPTIONS] [PROMPT]

​
Description

The codex command launches the interactive Codex TUI (Terminal User Interface). If you provide a prompt as an argument, Codex starts with that prompt pre-filled. Without arguments, you’ll see an empty prompt where you can type your request.

​
Usage

​
Interactive Mode

Start Codex with an empty prompt: 
codex

​
With Initial Prompt

Start Codex with a specific task: 
codex "refactor the Dashboard component to use React hooks"

​
With Images

Attach images to your prompt: 
codex -i screenshot.png "implement this design"
codex -i mockup1.png,mockup2.png "create a landing page matching these designs"

​
Options

​
PROMPT
string
Initial prompt to send to Codex. If not provided, starts with empty prompt.

​
Model & Provider

​
-m, --model
string
AI model to use (e.g., gpt-4.1, o4-mini). Defaults to configured model.
​
--oss
boolean
Use open-source/local model provider instead of OpenAI.
​
--local-provider
string
Specify OSS provider: ollama, lmstudio. Only valid with --oss.

​
Approval & Sandbox

​
--full-auto
boolean
Run in full-auto mode with workspace-write sandbox. No approvals required for file writes or shell commands.
​
--sandbox
string
Sandbox mode: workspace-write, workspace-read-network-write, read-only, danger-full-access.
​
--ask-for-approval
string
Approval policy: never, on-request, for-risky-ops.
​
--dangerously-bypass-approvals-and-sandbox
boolean
Skip all approval checks and sandbox restrictions. Use with extreme caution.

​
Input

​
-i, --images
string
Comma-separated list of image paths to attach. Supports PNG, JPEG, GIF, WebP.
​
--add-dir
path
Additional directories to make writable in sandbox (repeatable).
​
--search
boolean
Enable web search for this session.

​
Session Management

​
-C, --cwd
path
Working directory for this session.
​
--ephemeral
boolean
Don’t save this session to history.
​
--skip-git-repo-check
boolean
Skip the check for being inside a Git repository.

​
Configuration

​
-p, --profile
string
Use a specific config profile.
​
-c
string
Override config.toml setting (repeatable). Format: key=value or section.key=value.Examples:
  • -c model=gpt-4.1
  • -c permissions.approval_policy=never
​
--enable
string
Enable a feature flag (repeatable). Equivalent to -c features.<name>=true.
​
--disable
string
Disable a feature flag (repeatable). Equivalent to -c features.<name>=false.

​
Examples

​
Basic Usage

# Start interactive session
codex

# Start with a prompt
codex "explain this codebase"

# Use a specific model
codex -m gpt-4.1 "implement OAuth authentication"

​
Full Auto Mode

# Let Codex run autonomously with file write permissions
codex --full-auto "build a REST API with Express"

# With custom sandbox configuration
codex --sandbox workspace-write "create integration tests"

​
With Images

# Implement a design from a mockup
codex -i design-mockup.png "build this UI component"

# Multiple images
codex -i dashboard.png,sidebar.png "recreate this interface"

​
Local/OSS Models

# Use Ollama
codex --oss --local-provider ollama "write unit tests"

# Use LM Studio
codex --oss --local-provider lmstudio -m codellama "refactor this module"

​
Configuration Overrides

# Temporarily change settings
codex -c sandbox_mode=workspace_write "scaffold a new project"

# Multiple overrides
codex -c model=o4 -c web_search=live "research best practices for API design"

# Use a profile
codex -p production "deploy the latest changes"

​
Special Directories

# Run in a different directory
codex -C ~/projects/api "add health check endpoint"

# Add extra writable directories
codex --add-dir /tmp/cache "generate and cache API responses"

​
Terminal Requirements

Codex’s interactive TUI requires a terminal that supports:
  • ANSI escape codes
  • UTF-8 encoding
  • Terminal dimensions (rows/columns)
If TERM=dumb, Codex will warn you and ask for confirmation before starting.