codex

Run Codex interactively with optional initial prompt

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.

Related Commands

• codex exec - Non-interactive execution for automation
• codex resume - Continue a previous session
• codex fork - Fork a previous session