0
# OpenAI Codex CLI
1
2
OpenAI Codex CLI is a lightweight coding agent from OpenAI that runs locally on your computer. It provides multimodal inputs (text, screenshots, diagrams), a rich approvals workflow with three distinct modes, and runs entirely in your terminal for quick iteration without switching contexts.
3
4
## Package Information
5
6
- **Package Name**: @openai/codex
7
- **Package Type**: npm
8
- **Language**: Node.js (wrapper for Rust binary)
9
- **Installation**: `npm install -g @openai/codex` or `brew install codex`
10
- **Binary Name**: `codex`
11
12
## Core Usage
13
14
```bash
15
# Interactive mode (default)
16
codex
17
18
# Non-interactive execution
19
codex exec "implement a new feature"
20
codex e "fix this bug"
21
22
# With configuration
23
codex -m gpt-4
24
codex -c key=value
25
```
26
27
## Basic Usage
28
29
The Codex CLI supports both interactive and non-interactive modes:
30
31
```bash
32
# Start interactive session
33
codex
34
35
# Execute a prompt non-interactively
36
codex exec "Create a Python script that sorts a list of numbers"
37
38
# Run with specific model
39
codex -m gpt-4 exec "Refactor this code for better performance"
40
41
# Full automation mode with sandbox
42
codex exec --full-auto "Fix all linting errors in the project"
43
```
44
45
## Architecture
46
47
The Codex CLI is built as a multi-tool with distinct operational modes:
48
49
- **Interactive Mode**: Terminal UI for conversational coding sessions
50
- **Exec Mode**: Non-interactive command execution
51
- **Protocol Mode**: JSON-line communication for integration
52
- **MCP Integration**: Model Context Protocol server support
53
- **Sandboxed Execution**: Platform-specific security controls
54
55
## Capabilities
56
57
### Interactive Terminal Interface
58
59
The default interactive mode provides a rich terminal experience with conversation management and real-time AI assistance.
60
61
```bash { .api }
62
codex [OPTIONS]
63
```
64
65
[Interactive Mode](./interactive-mode.md)
66
67
### Non-Interactive Execution
68
69
Execute AI prompts directly from the command line without entering interactive mode.
70
71
```bash { .api }
72
codex exec [OPTIONS] <PROMPT>
73
codex e [OPTIONS] <PROMPT>
74
```
75
76
[Execution Mode](./execution-mode.md)
77
78
### Authentication Management
79
80
Handle login and logout operations with support for ChatGPT accounts and API keys.
81
82
```bash { .api }
83
codex login [OPTIONS] [SUBCOMMAND]
84
codex logout [OPTIONS]
85
```
86
87
[Authentication](./authentication.md)
88
89
### Model Context Protocol (MCP) Server Management
90
91
Add, remove, and manage MCP servers for extended functionality.
92
93
```bash { .api }
94
codex mcp [OPTIONS] [SUBCOMMAND]
95
```
96
97
[MCP Management](./mcp-management.md)
98
99
### Protocol Communication
100
101
Run Codex as a protocol server for programmatic integration via stdin/stdout JSON-line communication.
102
103
```bash { .api }
104
codex proto [OPTIONS]
105
codex p [OPTIONS]
106
```
107
108
[Protocol Mode](./protocol-mode.md)
109
110
### Session Management
111
112
Resume previous interactive sessions by ID or continue the most recent session.
113
114
```bash { .api }
115
codex resume [OPTIONS] [SESSION_ID]
116
```
117
118
[Session Management](./session-management.md)
119
120
### Development Utilities
121
122
Additional tools for shell completion, debugging, and patch application.
123
124
```bash { .api }
125
codex completion <SHELL>
126
codex debug <SUBCOMMAND>
127
codex apply [OPTIONS]
128
```
129
130
[Development Utilities](./development-utilities.md)
131
132
## Global Configuration Options
133
134
All commands support the following global configuration options:
135
136
```bash { .api }
137
-p, --profile <PROFILE> # Use specific config profile
138
-c, --config <KEY=VALUE> # Runtime configuration overrides (repeatable)
139
```
140
141
Configuration is stored in `~/.codex/config.toml` and can be overridden via command-line flags or environment variables.
142
143
## Exit Codes
144
145
- `0`: Success
146
- `1`: General error
147
- `128 + signal`: Process terminated by signal (Unix only)
148
149
## Environment Variables
150
151
- `CODEX_HOME`: Override default configuration directory (~/.codex)
152
- `PROJECT_NAME`: Specify project context
153
- `PROJECT_VERSION`: Specify project version