Codex Command Line Tool
Codex CLI is an official command-line tool written in Rust. It is lightweight and efficient, suitable for terminal enthusiasts.
Install CLI
Codex CLI supports macOS, Linux, and Windows (experimental).
npm Install
npm Global Install
npm install -g @openai/codex
# Verify installation
codex --version
Homebrew Install
Homebrew Install
brew install codex
Update CLI
Update Version
npm install -g @openai/codex@latest
# Update via Homebrew
brew upgrade codex
First Time Use
The first time you run Codex, it will guide you through authentication.
Launch Codex
codex
# Or specify an initial task
codex "Explain this project structure"
Codex will open a browser for authentication.
- Log in with ChatGPT account
- Or use OpenAI API Key
- After authorization, return to the terminal to continue.
Interactive TUI
By default, the CLI enters Terminal User Interface (TUI) mode, providing an immersive experience.
TUI Interface Areas
| Area | Function |
|---|---|
| Message Area | Displays conversation history, tool calls, and execution results |
| Input Area | Bottom input box, send Prompt |
| Status Bar | Displays model, context usage, and thread information |
TUI Mode Settings
TUI Configuration
[tui]
# Alternate screen mode
alternate_screen = "auto" # auto | always | never
# Keep scroll history when alternate screen is disabled
# alternate_screen = "never"
Alternate screen mode makes Codex use a separate screen and restores the original terminal state when exiting.
Approval Mode
Approval Mode controls the confirmation behavior before Codex performs actions.
Four Modes
| Mode | Description | Behavior |
|---|---|---|
| suggest | Suggest Mode | Codex provides suggestions but does not execute |
| auto-edit | Auto-edit | Automatically performs file edits, commands require confirmation |
| full-auto | Fully Automatic | Automatically executes all operations (use with caution) |
| interactive | Interactive Mode | Ask before sensitive operations (default) |
Set Approval Mode
codex --approval-mode full-auto
# Or switch in session
/approval full-auto
In full-auto mode, Codex automatically executes all operations, including deleting files. Use with caution.
Sandbox Mode
Sandbox mode restricts Codex's file and command access scope.
| Mode | File modification | Command execution | Network access |
|---|---|---|---|
| read-only | Forbidden | Forbidden | Forbidden |
| workspace-write | Workspace only | Allowed | Forbidden |
| danger-full-access | Allowed | Allowed | Allowed |
Set Sandbox Mode
codex --sandbox read-only
# Workspace write mode (recommended)
codex --sandbox workspace-write
# Full access mode (dangerous)
codex --sandbox danger-full-access
Slash Commands
The CLI provides a rich set of slash commands:
| Command | Function |
|---|---|
/model | Switch model (e.g., /model gpt-5.4-mini) |
/fast | Toggle Fast mode |
/plan | Enter plan mode |
/review | Review code changes |
/new | Start a new session |
/resume | Resume a previous session |
/fork | Clone current session to a new thread |
/compact | Compress context history |
/status | Show session status |
/clear | Clear screen |
/quit | Exit Codex |
Command Usage Examples
Slash Commands
/model gpt-5.4-mini
# Plan mode
/plan implement user authentication system
# View status
/status
Shell Command Execution
Execute shell commands directly in the CLI:
Execute Command
! ls -la
# Execute git command
! git status
# View processes
! ps aux
Command Confirmation
Dangerous commands require confirmation:
- Delete files (rm)
- Terminate processes (kill)
- Modify system configuration
Image Input
The CLI supports attaching images as context:
Attach Image
codex -i screenshot.png
# Attach design mockup
codex --image design.png "Implement the page based on this design"
# Multiple images
codex -i img1.png -i img2.png
Image Usage
- Analyze error messages from screenshots
- Convert UI design mockups to code
- Interpret chart data
Non-interactive Mode (exec)
Use the exec command to run a one-off task, suitable for scripts and CI/CD:
exec Command
codex exec "Review the code and output a report"
# Output to file
codex exec "Generate README" -o README.md
# Use a specific model
codex exec -m gpt-5.4-mini "Analyze project structure"
# Full auto mode
codex exec --full-auto "Run tests and fix failures"
Common exec Parameters
| Parameter | Description |
|---|---|
-m | Specify model |
-o | Output to file |
--full-auto | Full auto execution |
--ephemeral | Do not save session files |
--json | JSON output format |
Keyboard Shortcuts
| Shortcut | Function |
|---|---|
Enter | Send message |
Shift+Enter | New line |
Ctrl+C | Interrupt operation |
Ctrl+C (两次) | Exit Codex |
Ctrl+D | Exit (when input is empty) |
Ctrl+R | Search history |
Up/Down | Browse history |
Tab | Auto-complete |
Esc Esc | Edit last message |
Ctrl+O | Copy last reply |
FAQ
Q: Windows support status?
Windows native support is experimental; WSL2 is recommended for the best experience.
Q: How to disable alternate screen?
Usecodex --no-alt-screenor configurealternate_screen = "never"。
Q: Command not found?
Ensure PATH includes the npm global installation directory, or install using Homebrew.
Q: How to view detailed logs?
Logs are located in~/.codex/log/directory.