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