cli/reference.md Codex Docs, 2026-04-08 18:32 UTC → 2026-05-14 21:00 UTC

1# Command line options1# Command line options

2 2 

3## How to read this reference3export const globalFlagOptions = [

4 4 {

5This page catalogs every documented Codex CLI command and flag. Use the interactive tables to search by key or description. Each section indicates whether the option is stable or experimental and calls out risky combinations.5 key: "PROMPT",

6 6 type: "string",

7The CLI inherits most defaults from <code>~/.codex/config.toml</code>. Any7 description:

8 <code>-c key=value</code> overrides you pass at the command line take8 "Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.",

9 precedence for that invocation. See [Config9 },

10 basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.10 {

11 11 key: "--image, -i",

12## Global flags12 type: "path[,path...]",

13 13 description:

14| Key | Type / Values | Details |14 "Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.",

15| --- | --- | --- |15 },

16| `--add-dir` | `path` | Grant additional directories write access alongside the main workspace. Repeat for multiple paths. |16 {

17| `--ask-for-approval, -a` | `untrusted | on-request | never` | Control when Codex pauses for human approval before running a command. `on-failure` is deprecated; prefer `on-request` for interactive runs or `never` for non-interactive runs. |17 key: "--model, -m",

18| `--cd, -C` | `path` | Set the working directory for the agent before it starts processing your request. |18 type: "string",

19| `--config, -c` | `key=value` | Override configuration values. Values parse as JSON if possible; otherwise the literal string is used. |19 description:

20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |20 "Override the model set in configuration (for example `gpt-5.4`).",

21| `--disable` | `feature` | Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable. |21 },

22| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |22 {

23| `--full-auto` | `boolean` | Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`. |23 key: "--oss",

24| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |24 type: "boolean",

25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |25 defaultValue: "false",

26| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |26 description:

27| `--oss` | `boolean` | Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running. |27 'Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running.',

28| `--profile, -p` | `string` | Configuration profile name to load from `~/.codex/config.toml`. |28 },

29| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Select the sandbox policy for model-generated shell commands. |29 {

30| `--search` | `boolean` | Enable live web search (sets `web_search = "live"` instead of the default `"cached"`). |30 key: "--profile, -p",

31| `PROMPT` | `string` | Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message. |31 type: "string",

32 32 description:

33Key33 "Configuration profile name to load from `~/.codex/config.toml`.",

34 34 },

35`--add-dir`35 {

36 36 key: "--sandbox, -s",

37Type / Values37 type: "read-only | workspace-write | danger-full-access",

38 38 description:

39`path`39 "Select the sandbox policy for model-generated shell commands.",

40 40 },

41Details41 {

42 42 key: "--ask-for-approval, -a",

43Grant additional directories write access alongside the main workspace. Repeat for multiple paths.43 type: "untrusted | on-request | never",

44 44 description:

45Key45 "Control when Codex pauses for human approval before running a command. `on-failure` is deprecated; prefer `on-request` for interactive runs or `never` for non-interactive runs.",

46 46 },

47`--ask-for-approval, -a`47 {

48 48 key: "--dangerously-bypass-approvals-and-sandbox, --yolo",

49Type / Values49 type: "boolean",

50 50 defaultValue: "false",

51`untrusted | on-request | never`51 description:

52 52 "Run every command without approvals or sandboxing. Only use inside an externally hardened environment.",

53Details53 },

54 54 {

55Control when Codex pauses for human approval before running a command. `on-failure` is deprecated; prefer `on-request` for interactive runs or `never` for non-interactive runs.55 key: "--cd, -C",

56 56 type: "path",

57Key57 description:

58 58 "Set the working directory for the agent before it starts processing your request.",

59`--cd, -C`59 },

60 60 {

61Type / Values61 key: "--search",

62 62 type: "boolean",

63`path`63 defaultValue: "false",

64 64 description:

65Details65 'Enable live web search (sets `web_search = "live"` instead of the default `"cached"`).',

66 66 },

67Set the working directory for the agent before it starts processing your request.67 {

68 68 key: "--add-dir",

69Key69 type: "path",

70 70 description:

71`--config, -c`71 "Grant additional directories write access alongside the main workspace. Repeat for multiple paths.",

72 72 },

73Type / Values73 {

74 74 key: "--no-alt-screen",

75`key=value`75 type: "boolean",

76 76 defaultValue: "false",

77Details77 description:

78 78 "Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run).",

79Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.79 },

80 80 {

81Key81 key: "--remote",

82 82 type: "ws://host:port | wss://host:port",

83`--dangerously-bypass-approvals-and-sandbox, --yolo`83 description:

84 84 "Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode.",

85Type / Values85 },

86 86 {

87`boolean`87 key: "--remote-auth-token-env",

88 88 type: "ENV_VAR",

89Details89 description:

90 90 "Read a bearer token from this environment variable and send it when connecting with `--remote`. Requires `--remote`; tokens are only sent over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`.",

91Run every command without approvals or sandboxing. Only use inside an externally hardened environment.91 },

92 92 {

93Key93 key: "--enable",

94 94 type: "feature",

95`--disable`95 description:

96 96 "Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable.",

97Type / Values97 },

98 98 {

99`feature`99 key: "--disable",

100 100 type: "feature",

101Details101 description:

102 102 "Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable.",

103Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable.103 },

104 104 {

105Key105 key: "--config, -c",

106 106 type: "key=value",

107`--enable`107 description:

108 108 "Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.",

109Type / Values109 },

110 110];

111`feature`111 

112 112export const commandOverview = [

113Details113 {

114 114 key: "codex",

115Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable.115 href: "/codex/cli/reference#codex-interactive",

116 116 type: "stable",

117Key117 description:

118 118 "Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.",

119`--full-auto`119 },

120 120 {

121Type / Values121 key: "codex app-server",

122 122 href: "/codex/cli/reference#codex-app-server",

123`boolean`123 type: "experimental",

124 124 description:

125Details125 "Launch the Codex app server for local development or debugging.",

126 126 },

127Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`.127 {

128 128 key: "codex app",

129Key129 href: "/codex/cli/reference#codex-app",

130 130 type: "stable",

131`--image, -i`131 description:

132 132 "Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open.",

133Type / Values133 },

134 134 {

135`path[,path...]`135 key: "codex debug app-server send-message-v2",

136 136 href: "/codex/cli/reference#codex-debug-app-server-send-message-v2",

137Details137 type: "experimental",

138 138 description:

139Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.139 "Debug app-server by sending a single V2 message through the built-in test client.",

140 140 },

141Key141 {

142 142 key: "codex debug models",

143`--model, -m`143 href: "/codex/cli/reference#codex-debug-models",

144 144 type: "experimental",

145Type / Values145 description:

146 146 "Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog.",

147`string`147 },

148 148 {

149Details149 key: "codex apply",

150 150 href: "/codex/cli/reference#codex-apply",

151Override the model set in configuration (for example `gpt-5.4`).151 type: "stable",

152 152 description:

153Key153 "Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.",

154 154 },

155`--no-alt-screen`155 {

156 156 key: "codex cloud",

157Type / Values157 href: "/codex/cli/reference#codex-cloud",

158 158 type: "experimental",

159`boolean`159 description:

160 160 "Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.",

161Details161 },

162 162 {

163Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run).163 key: "codex completion",

164 164 href: "/codex/cli/reference#codex-completion",

165Key165 type: "stable",

166 166 description:

167`--oss`167 "Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.",

168 168 },

169Type / Values169 {

170 170 key: "codex features",

171`boolean`171 href: "/codex/cli/reference#codex-features",

172 172 type: "stable",

173Details173 description:

174 174 "List feature flags and persistently enable or disable them in `config.toml`.",

175Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running.175 },

176 176 {

177Key177 key: "codex exec",

178 178 href: "/codex/cli/reference#codex-exec",

179`--profile, -p`179 type: "stable",

180 180 description:

181Type / Values181 "Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.",

182 182 },

183`string`183 {

184 184 key: "codex execpolicy",

185Details185 href: "/codex/cli/reference#codex-execpolicy",

186 186 type: "experimental",

187Configuration profile name to load from `~/.codex/config.toml`.187 description:

188 188 "Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.",

189Key189 },

190 190 {

191`--sandbox, -s`191 key: "codex login",

192 192 href: "/codex/cli/reference#codex-login",

193Type / Values193 type: "stable",

194 194 description:

195`read-only | workspace-write | danger-full-access`195 "Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.",

196 196 },

197Details197 {

198 198 key: "codex logout",

199Select the sandbox policy for model-generated shell commands.199 href: "/codex/cli/reference#codex-logout",

200 200 type: "stable",

201Key201 description: "Remove stored authentication credentials.",

202 202 },

203`--search`203 {

204 204 key: "codex mcp",

205Type / Values205 href: "/codex/cli/reference#codex-mcp",

206 206 type: "experimental",

207`boolean`207 description:

208 208 "Manage Model Context Protocol servers (list, add, remove, authenticate).",

209Details209 },

210 210 {

211Enable live web search (sets `web_search = "live"` instead of the default `"cached"`).211 key: "codex plugin marketplace",

212 212 href: "/codex/cli/reference#codex-plugin-marketplace",

213Key213 type: "experimental",

214 214 description:

215`PROMPT`215 "Add, upgrade, or remove plugin marketplaces from Git or local sources.",

216 216 },

217Type / Values217 {

218 218 key: "codex mcp-server",

219`string`219 href: "/codex/cli/reference#codex-mcp-server",

220 220 type: "experimental",

221Details221 description:

222 222 "Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.",

223Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.223 },

224 224 {

225Expand to view all225 key: "codex resume",

226 226 href: "/codex/cli/reference#codex-resume",

227These options apply to the base `codex` command and propagate to each subcommand unless a section below specifies otherwise.227 type: "stable",

228When you run a subcommand, place global flags after it (for example, `codex exec --oss ...`) so Codex applies them as intended.228 description:

229 229 "Continue a previous interactive session by ID or resume the most recent conversation.",

230## Command overview230 },

231 231 {

232The Maturity column uses feature maturity labels such as Experimental, Beta,232 key: "codex fork",

233 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to233 href: "/codex/cli/reference#codex-fork",

234 interpret these labels.234 type: "stable",

235 235 description:

236| Key | Maturity | Details |236 "Fork a previous interactive session into a new thread, preserving the original transcript.",

237| --- | --- | --- |237 },

238| [`codex`](https://developers.openai.com/codex/cli/reference#codex-interactive) | Stable | Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments. |238 {

239| [`codex app`](https://developers.openai.com/codex/cli/reference#codex-app) | Stable | Launch the Codex desktop app on macOS, optionally opening a specific workspace path. |239 key: "codex sandbox",

240| [`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server) | Experimental | Launch the Codex app server for local development or debugging. |240 href: "/codex/cli/reference#codex-sandbox",

241| [`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply) | Stable | Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`. |241 type: "experimental",

242| [`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud) | Experimental | Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`. |242 description:

243| [`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion) | Stable | Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell. |243 "Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes.",

244| [`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2) | Experimental | Debug app-server by sending a single V2 message through the built-in test client. |244 },

245| [`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec) | Stable | Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions. |245 {

246| [`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy) | Experimental | Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked. |246 key: "codex update",

247| [`codex features`](https://developers.openai.com/codex/cli/reference#codex-features) | Stable | List feature flags and persistently enable or disable them in `config.toml`. |247 href: "/codex/cli/reference#codex-update",

248| [`codex fork`](https://developers.openai.com/codex/cli/reference#codex-fork) | Stable | Fork a previous interactive session into a new thread, preserving the original transcript. |248 type: "stable",

249| [`codex login`](https://developers.openai.com/codex/cli/reference#codex-login) | Stable | Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin. |249 description:

250| [`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout) | Stable | Remove stored authentication credentials. |250 "Check for and apply a Codex CLI update when the installed release supports self-update.",

251| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |251 },

252| [`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server) | Experimental | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex. |252];

253| [`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume) | Stable | Continue a previous interactive session by ID or resume the most recent conversation. |253 

254| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS seatbelt or Linux sandboxes (Landlock by default, optional bubblewrap pipeline). |254export const execOptions = [

255 255 {

256Key256 key: "PROMPT",

257 257 type: "string | - (read stdin)",

258[`codex`](https://developers.openai.com/codex/cli/reference#codex-interactive)258 description:

259 259 "Initial instruction for the task. Use `-` to pipe the prompt from stdin.",

260Maturity260 },

261 261 {

262Stable262 key: "--image, -i",

263 263 type: "path[,path...]",

264Details264 description:

265 265 "Attach images to the first message. Repeatable; supports comma-separated lists.",

266Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.266 },

267 267 {

268Key268 key: "--model, -m",

269 269 type: "string",

270[`codex app`](https://developers.openai.com/codex/cli/reference#codex-app)270 description: "Override the configured model for this run.",

271 271 },

272Maturity272 {

273 273 key: "--oss",

274Stable274 type: "boolean",

275 275 defaultValue: "false",

276Details276 description:

277 277 "Use the local open source provider (requires a running Ollama instance).",

278Launch the Codex desktop app on macOS, optionally opening a specific workspace path.278 },

279 279 {

280Key280 key: "--sandbox, -s",

281 281 type: "read-only | workspace-write | danger-full-access",

282[`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server)282 description:

283 283 "Sandbox policy for model-generated commands. Defaults to configuration.",

284Maturity284 },

285 285 {

286Experimental286 key: "--profile, -p",

287 287 type: "string",

288Details288 description: "Select a configuration profile defined in config.toml.",

289 289 },

290Launch the Codex app server for local development or debugging.290 {

291 291 key: "--full-auto",

292Key292 type: "boolean",

293 293 defaultValue: "false",

294[`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply)294 description:

295 295 "Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.",

296Maturity296 },

297 297 {

298Stable298 key: "--dangerously-bypass-approvals-and-sandbox, --yolo",

299 299 type: "boolean",

300Details300 defaultValue: "false",

301 301 description:

302Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.302 "Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.",

303 303 },

304Key304 {

305 305 key: "--cd, -C",

306[`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud)306 type: "path",

307 307 description: "Set the workspace root before executing the task.",

308Maturity308 },

309 309 {

310Experimental310 key: "--skip-git-repo-check",

311 311 type: "boolean",

312Details312 defaultValue: "false",

313 313 description:

314Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.314 "Allow running outside a Git repository (useful for one-off directories).",

315 315 },

316Key316 {

317 317 key: "--ephemeral",

318[`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion)318 type: "boolean",

319 319 defaultValue: "false",

320Maturity320 description: "Run without persisting session rollout files to disk.",

321 321 },

322Stable322 {

323 323 key: "--ignore-user-config",

324Details324 type: "boolean",

325 325 defaultValue: "false",

326Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.326 description:

327 327 "Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`.",

328Key328 },

329 329 {

330[`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2)330 key: "--ignore-rules",

331 331 type: "boolean",

332Maturity332 defaultValue: "false",

333 333 description:

334Experimental334 "Do not load user or project execpolicy `.rules` files for this run.",

335 335 },

336Details336 {

337 337 key: "--output-schema",

338Debug app-server by sending a single V2 message through the built-in test client.338 type: "path",

339 339 description:

340Key340 "JSON Schema file describing the expected final response shape. Codex validates tool output against it.",

341 341 },

342[`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec)342 {

343 343 key: "--color",

344Maturity344 type: "always | never | auto",

345 345 defaultValue: "auto",

346Stable346 description: "Control ANSI color in stdout.",

347 347 },

348Details348 {

349 349 key: "--json, --experimental-json",

350Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.350 type: "boolean",

351 351 defaultValue: "false",

352Key352 description:

353 353 "Print newline-delimited JSON events instead of formatted text.",

354[`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy)354 },

355 355 {

356Maturity356 key: "--output-last-message, -o",

357 357 type: "path",

358Experimental358 description:

359 359 "Write the assistant’s final message to a file. Useful for downstream scripting.",

360Details360 },

361 361 {

362Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.362 key: "Resume subcommand",

363 363 type: "codex exec resume [SESSION_ID]",

364Key364 description:

365 365 "Resume an exec session by ID or add `--last` to continue the most recent session from the current working directory. Add `--all` to consider sessions from any directory. Accepts an optional follow-up prompt.",

366[`codex features`](https://developers.openai.com/codex/cli/reference#codex-features)366 },

367 367 {

368Maturity368 key: "-c, --config",

369 369 type: "key=value",

370Stable370 description:

371 371 "Inline configuration override for the non-interactive run (repeatable).",

372Details372 },

373 373];

374List feature flags and persistently enable or disable them in `config.toml`.374 

375 375export const appServerOptions = [

376Key376 {

377 377 key: "--listen",

378[`codex fork`](https://developers.openai.com/codex/cli/reference#codex-fork)378 type: "stdio:// | ws://IP:PORT",

379 379 defaultValue: "stdio://",

380Maturity380 description:

381 381 "Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients.",

382Stable382 },

383 383 {

384Details384 key: "--ws-auth",

385 385 type: "capability-token | signed-bearer-token",

386Fork a previous interactive session into a new thread, preserving the original transcript.386 description:

387 387 "Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup.",

388Key388 },

389 389 {

390[`codex login`](https://developers.openai.com/codex/cli/reference#codex-login)390 key: "--ws-token-file",

391 391 type: "absolute path",

392Maturity392 description:

393 393 "File containing the shared capability token. Required with `--ws-auth capability-token`.",

394Stable394 },

395 395 {

396Details396 key: "--ws-shared-secret-file",

397 397 type: "absolute path",

398Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.398 description:

399 399 "File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.",

400Key400 },

401 401 {

402[`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout)402 key: "--ws-issuer",

403 403 type: "string",

404Maturity404 description:

405 405 "Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.",

406Stable406 },

407 407 {

408Details408 key: "--ws-audience",

409 409 type: "string",

410Remove stored authentication credentials.410 description:

411 411 "Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.",

412Key412 },

413 413 {

414[`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp)414 key: "--ws-max-clock-skew-seconds",

415 415 type: "number",

416Maturity416 defaultValue: "30",

417 417 description:

418Experimental418 "Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.",

419 419 },

420Details420];

421 421 

422Manage Model Context Protocol servers (list, add, remove, authenticate).422export const appOptions = [

423 423 {

424Key424 key: "PATH",

425 425 type: "path",

426[`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server)426 defaultValue: ".",

427 427 description:

428Maturity428 "Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.",

429 429 },

430Experimental430 {

431 431 key: "--download-url",

432Details432 type: "url",

433 433 description:

434Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.434 "Advanced override for the Codex desktop installer URL used during install.",

435 435 },

436Key436];

437 437 

438[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)438export const debugAppServerSendMessageV2Options = [

439 439 {

440Maturity440 key: "USER_MESSAGE",

441 441 type: "string",

442Stable442 description:

443 443 "Message text sent to app-server through the built-in V2 test-client flow.",

444Details444 },

445 445];

446Continue a previous interactive session by ID or resume the most recent conversation.446 

447 447export const debugModelsOptions = [

448Key448 {

449 449 key: "--bundled",

450[`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox)450 type: "boolean",

451 451 defaultValue: "false",

452Maturity452 description:

453 453 "Skip refresh and print only the model catalog bundled with the current Codex binary.",

454Experimental454 },

455 455];

456Details456 

457 457export const resumeOptions = [

458Run arbitrary commands inside Codex-provided macOS seatbelt or Linux sandboxes (Landlock by default, optional bubblewrap pipeline).458 {

459 459 key: "SESSION_ID",

460Expand to view all460 type: "uuid",

461 461 description:

462## Command details462 "Resume the specified session. Omit and use `--last` to continue the most recent session.",

463 463 },

464### `codex` (interactive)464 {

465 465 key: "--last",

466Running `codex` with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use `--search` to switch to live browsing and `--full-auto` to let Codex run most commands without prompts.466 type: "boolean",

467 467 defaultValue: "false",

468### `codex app-server`468 description:

469 469 "Skip the picker and resume the most recent conversation from the current working directory.",

470Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.470 },

471 471 {

472| Key | Type / Values | Details |472 key: "--all",

473| --- | --- | --- |473 type: "boolean",

474| `--listen` | `stdio:// | ws://IP:PORT` | Transport listener URL. `ws://` is experimental and intended for development/testing. |474 defaultValue: "false",

475 475 description:

476Key476 "Include sessions outside the current working directory when selecting the most recent session.",

477 477 },

478`--listen`478];

479 479 

480Type / Values480export const featuresOptions = [

481 481 {

482`stdio:// | ws://IP:PORT`482 key: "List subcommand",

483 483 type: "codex features list",

484Details484 description:

485 485 "Show known feature flags, their maturity stage, and their effective state.",

486Transport listener URL. `ws://` is experimental and intended for development/testing.486 },

487 487 {

488`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior. `--listen ws://IP:PORT` enables WebSocket transport (experimental). If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.488 key: "Enable subcommand",

489 489 type: "codex features enable <feature>",

490### `codex app`490 description:

491 491 "Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.",

492Launch Codex Desktop from the terminal on macOS and optionally open a specific workspace path.492 },

493 493 {

494| Key | Type / Values | Details |494 key: "Disable subcommand",

495| --- | --- | --- |495 type: "codex features disable <feature>",

496| `--download-url` | `url` | Advanced override for the Codex desktop DMG download URL used during install. |496 description:

497| `PATH` | `path` | Workspace path to open in Codex Desktop (`codex app` is available on macOS only). |497 "Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.",

498 498 },

499Key499];

500 500 

501`--download-url`501export const execResumeOptions = [

502 502 {

503Type / Values503 key: "SESSION_ID",

504 504 type: "uuid",

505`url`505 description:

506 506 "Resume the specified session. Omit and use `--last` to continue the most recent session.",

507Details507 },

508 508 {

509Advanced override for the Codex desktop DMG download URL used during install.509 key: "--last",

510 510 type: "boolean",

511Key511 defaultValue: "false",

512 512 description:

513`PATH`513 "Resume the most recent conversation from the current working directory.",

514 514 },

515Type / Values515 {

516 516 key: "--all",

517`path`517 type: "boolean",

518 518 defaultValue: "false",

519Details519 description:

520 520 "Include sessions outside the current working directory when selecting the most recent session.",

521Workspace path to open in Codex Desktop (`codex app` is available on macOS only).521 },

522 522 {

523`codex app` installs/opens the desktop app on macOS, then opens the provided workspace path. This subcommand is macOS-only.523 key: "--image, -i",

524 524 type: "path[,path...]",

525### `codex debug app-server send-message-v2`525 description:

526 526 "Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.",

527Send one message through app-server's V2 thread/turn flow using the built-in app-server test client.527 },

528 528 {

529| Key | Type / Values | Details |529 key: "PROMPT",

530| --- | --- | --- |530 type: "string | - (read stdin)",

531| `USER_MESSAGE` | `string` | Message text sent to app-server through the built-in V2 test-client flow. |531 description:

532 532 "Optional follow-up instruction sent immediately after resuming.",

533Key533 },

534 534];

535`USER_MESSAGE`535 

536 536export const forkOptions = [

537Type / Values537 {

538 538 key: "SESSION_ID",

539`string`539 type: "uuid",

540 540 description:

541Details541 "Fork the specified session. Omit and use `--last` to fork the most recent session.",

542 542 },

543Message text sent to app-server through the built-in V2 test-client flow.543 {

544 544 key: "--last",

545This debug flow initializes with `experimentalApi: true`, starts a thread, sends a turn, and streams server notifications. Use it to reproduce and inspect app-server protocol behavior locally.545 type: "boolean",

546 546 defaultValue: "false",

547### `codex apply`547 description:

548 548 "Skip the picker and fork the most recent conversation automatically.",

549Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.549 },

550 550 {

551| Key | Type / Values | Details |551 key: "--all",

552| --- | --- | --- |552 type: "boolean",

553| `TASK_ID` | `string` | Identifier of the Codex Cloud task whose diff should be applied. |553 defaultValue: "false",

554 554 description:

555Key555 "Show sessions beyond the current working directory in the picker.",

556 556 },

557`TASK_ID`557];

558 558 

559Type / Values559export const execpolicyOptions = [

560 560 {

561`string`561 key: "--rules, -r",

562 562 type: "path (repeatable)",

563Details563 description:

564 564 "Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.",

565Identifier of the Codex Cloud task whose diff should be applied.565 },

566 566 {

567Codex prints the patched files and exits non-zero if `git apply` fails (for example, due to conflicts).567 key: "--pretty",

568 568 type: "boolean",

569### `codex cloud`569 defaultValue: "false",

570 570 description: "Pretty-print the JSON result.",

571Interact with Codex cloud tasks from the terminal. The default command opens an interactive picker; `codex cloud exec` submits a task directly, and `codex cloud list` returns recent tasks for scripting or quick inspection.571 },

572 572 {

573| Key | Type / Values | Details |573 key: "COMMAND...",

574| --- | --- | --- |574 type: "var-args",

575| `--attempts` | `1-4` | Number of assistant attempts (best-of-N) Codex Cloud should run. |575 description: "Command to be checked against the specified policies.",

576| `--env` | `ENV_ID` | Target Codex Cloud environment identifier (required). Use `codex cloud` to list options. |576 },

577| `QUERY` | `string` | Task prompt. If omitted, Codex prompts interactively for details. |577];

578 578 

579Key579export const loginOptions = [

580 580 {

581`--attempts`581 key: "--with-api-key",

582 582 type: "boolean",

583Type / Values583 description:

584 584 "Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`).",

585`1-4`585 },

586 586 {

587Details587 key: "--device-auth",

588 588 type: "boolean",

589Number of assistant attempts (best-of-N) Codex Cloud should run.589 description:

590 590 "Use OAuth device code flow instead of launching a browser window.",

591Key591 },

592 592 {

593`--env`593 key: "status subcommand",

594 594 type: "codex login status",

595Type / Values595 description:

596 596 "Print the active authentication mode and exit with 0 when logged in.",

597`ENV_ID`597 },

598 598];

599Details599 

600 600export const applyOptions = [

601Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.601 {

602 602 key: "TASK_ID",

603Key603 type: "string",

604 604 description:

605`QUERY`605 "Identifier of the Codex Cloud task whose diff should be applied.",

606 606 },

607Type / Values607];

608 608 

609`string`609export const sandboxMacOptions = [

610 610 {

611Details611 key: "--permissions-profile",

612 612 type: "NAME",

613Task prompt. If omitted, Codex prompts interactively for details.613 description:

614 614 "Apply a named permissions profile from the active configuration stack.",

615Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.615 },

616 616 {

617#### `codex cloud list`617 key: "--cd, -C",

618 618 type: "DIR",

619List recent cloud tasks with optional filtering and pagination.619 description:

620 620 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",

621| Key | Type / Values | Details |621 },

622| --- | --- | --- |622 {

623| `--cursor` | `string` | Pagination cursor returned by a previous request. |623 key: "--include-managed-config",

624| `--env` | `ENV_ID` | Filter tasks by environment identifier. |624 type: "boolean",

625| `--json` | `boolean` | Emit machine-readable JSON instead of plain text. |625 defaultValue: "false",

626| `--limit` | `1-20` | Maximum number of tasks to return. |626 description:

627 627 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",

628Key628 },

629 629 {

630`--cursor`630 key: "--allow-unix-socket",

631 631 type: "path",

632Type / Values632 description:

633 633 "Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths.",

634`string`634 },

635 635 {

636Details636 key: "--log-denials",

637 637 type: "boolean",

638Pagination cursor returned by a previous request.638 defaultValue: "false",

639 639 description:

640Key640 "Capture macOS sandbox denials with `log stream` while the command runs and print them after exit.",

641 641 },

642`--env`642 {

643 643 key: "--config, -c",

644Type / Values644 type: "key=value",

645 645 description:

646`ENV_ID`646 "Pass configuration overrides into the sandboxed run (repeatable).",

647 647 },

648Details648 {

649 649 key: "COMMAND...",

650Filter tasks by environment identifier.650 type: "var-args",

651 651 description:

652Key652 "Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.",

653 653 },

654`--json`654];

655 655 

656Type / Values656export const sandboxLinuxOptions = [

657 657 {

658`boolean`658 key: "--permissions-profile",

659 659 type: "NAME",

660Details660 description:

661 661 "Apply a named permissions profile from the active configuration stack.",

662Emit machine-readable JSON instead of plain text.662 },

663 663 {

664Key664 key: "--cd, -C",

665 665 type: "DIR",

666`--limit`666 description:

667 667 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",

668Type / Values668 },

669 669 {

670`1-20`670 key: "--include-managed-config",

671 671 type: "boolean",

672Details672 defaultValue: "false",

673 673 description:

674Maximum number of tasks to return.674 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",

675 675 },

676Plain-text output prints a task URL followed by status details. Use `--json` for automation. The JSON payload contains a `tasks` array plus an optional `cursor` value. Each task includes `id`, `url`, `title`, `status`, `updated_at`, `environment_id`, `environment_label`, `summary`, `is_review`, and `attempt_total`.676 {

677 677 key: "--config, -c",

678### `codex completion`678 type: "key=value",

679 679 description:

680Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.680 "Configuration overrides applied before launching the sandbox (repeatable).",

681 681 },

682| Key | Type / Values | Details |682 {

683| --- | --- | --- |683 key: "COMMAND...",

684| `SHELL` | `bash | zsh | fish | power-shell | elvish` | Shell to generate completions for. Output prints to stdout. |684 type: "var-args",

685 685 description:

686Key686 "Command to execute under Landlock + seccomp. Provide the executable after `--`.",

687 687 },

688`SHELL`688];

689 689 

690Type / Values690export const sandboxWindowsOptions = [

691 691 {

692`bash | zsh | fish | power-shell | elvish`692 key: "--permissions-profile",

693 693 type: "NAME",

694Details694 description:

695 695 "Apply a named permissions profile from the active configuration stack.",

696Shell to generate completions for. Output prints to stdout.696 },

697 697 {

698### `codex features`698 key: "--cd, -C",

699 699 type: "DIR",

700Manage feature flags stored in `~/.codex/config.toml`. The `enable` and `disable` commands persist changes so they apply to future sessions. When you launch with `--profile`, Codex writes to that profile instead of the root configuration.700 description:

701 701 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",

702| Key | Type / Values | Details |702 },

703| --- | --- | --- |703 {

704| `Disable subcommand` | `codex features disable <feature>` | Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided. |704 key: "--include-managed-config",

705| `Enable subcommand` | `codex features enable <feature>` | Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided. |705 type: "boolean",

706| `List subcommand` | `codex features list` | Show known feature flags, their maturity stage, and their effective state. |706 defaultValue: "false",

707 707 description:

708Key708 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",

709 709 },

710`Disable subcommand`710 {

711 711 key: "--config, -c",

712Type / Values712 type: "key=value",

713 713 description:

714`codex features disable <feature>`714 "Configuration overrides applied before launching the sandbox (repeatable).",

715 715 },

716Details716 {

717 717 key: "COMMAND...",

718Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.718 type: "var-args",

719 719 description:

720Key720 "Command to execute under the native Windows sandbox. Provide the executable after `--`.",

721 721 },

722`Enable subcommand`722];

723 723 

724Type / Values724export const completionOptions = [

725 725 {

726`codex features enable <feature>`726 key: "SHELL",

727 727 type: "bash | zsh | fish | power-shell | elvish",

728Details728 defaultValue: "bash",

729 729 description: "Shell to generate completions for. Output prints to stdout.",

730Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.730 },

731 731];

732Key732 

733 733export const cloudExecOptions = [

734`List subcommand`734 {

735 735 key: "QUERY",

736Type / Values736 type: "string",

737 737 description:

738`codex features list`738 "Task prompt. If omitted, Codex prompts interactively for details.",

739 739 },

740Details740 {

741 741 key: "--env",

742Show known feature flags, their maturity stage, and their effective state.742 type: "ENV_ID",

743 743 description:

744### `codex exec`744 "Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.",

745 745 },

746Use `codex exec` (or the short form `codex e`) for scripted or CI-style runs that should finish without human interaction.746 {

747 747 key: "--attempts",

748| Key | Type / Values | Details |748 type: "1-4",

749| --- | --- | --- |749 defaultValue: "1",

750| `--cd, -C` | `path` | Set the workspace root before executing the task. |750 description:

751| `--color` | `always | never | auto` | Control ANSI color in stdout. |751 "Number of assistant attempts (best-of-N) Codex Cloud should run.",

752| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner. |752 },

753| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |753];

754| `--full-auto` | `boolean` | Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals). |754 

755| `--image, -i` | `path[,path...]` | Attach images to the first message. Repeatable; supports comma-separated lists. |755export const cloudListOptions = [

756| `--json, --experimental-json` | `boolean` | Print newline-delimited JSON events instead of formatted text. |756 {

757| `--model, -m` | `string` | Override the configured model for this run. |757 key: "--env",

758| `--oss` | `boolean` | Use the local open source provider (requires a running Ollama instance). |758 type: "ENV_ID",

759| `--output-last-message, -o` | `path` | Write the assistant’s final message to a file. Useful for downstream scripting. |759 description: "Filter tasks by environment identifier.",

760| `--output-schema` | `path` | JSON Schema file describing the expected final response shape. Codex validates tool output against it. |760 },

761| `--profile, -p` | `string` | Select a configuration profile defined in config.toml. |761 {

762| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Sandbox policy for model-generated commands. Defaults to configuration. |762 key: "--limit",

763| `--skip-git-repo-check` | `boolean` | Allow running outside a Git repository (useful for one-off directories). |763 type: "1-20",

764| `-c, --config` | `key=value` | Inline configuration override for the non-interactive run (repeatable). |764 defaultValue: "20",

765| `PROMPT` | `string | - (read stdin)` | Initial instruction for the task. Use `-` to pipe the prompt from stdin. |765 description: "Maximum number of tasks to return.",

766| `Resume subcommand` | `codex exec resume [SESSION_ID]` | Resume an exec session by ID or add `--last` to continue the most recent session from the current working directory. Add `--all` to consider sessions from any directory. Accepts an optional follow-up prompt. |766 },

767 767 {

768Key768 key: "--cursor",

769 769 type: "string",

770`--cd, -C`770 description: "Pagination cursor returned by a previous request.",

771 771 },

772Type / Values772 {

773 773 key: "--json",

774`path`774 type: "boolean",

775 775 defaultValue: "false",

776Details776 description: "Emit machine-readable JSON instead of plain text.",

777 777 },

778Set the workspace root before executing the task.778];

779 779 

780Key780export const mcpCommands = [

781 781 {

782`--color`782 key: "list",

783 783 type: "--json",

784Type / Values784 description:

785 785 "List configured MCP servers. Add `--json` for machine-readable output.",

786`always | never | auto`786 },

787 787 {

788Details788 key: "get <name>",

789 789 type: "--json",

790Control ANSI color in stdout.790 description:

791 791 "Show a specific server configuration. `--json` prints the raw config entry.",

792Key792 },

793 793 {

794`--dangerously-bypass-approvals-and-sandbox, --yolo`794 key: "add <name>",

795 795 type: "-- <command...> | --url <value>",

796Type / Values796 description:

797 797 "Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports.",

798`boolean`798 },

799 799 {

800Details800 key: "remove <name>",

801 801 description: "Delete a stored MCP server definition.",

802Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.802 },

803 803 {

804Key804 key: "login <name>",

805 805 type: "--scopes scope1,scope2",

806`--ephemeral`806 description:

807 807 "Start an OAuth login for a streamable HTTP server (servers that support OAuth only).",

808Type / Values808 },

809 {

810 key: "logout <name>",

811 description:

812 "Remove stored OAuth credentials for a streamable HTTP server.",

813 },

814];

815 

816export const mcpAddOptions = [

817 {

818 key: "COMMAND...",

819 type: "stdio transport",

820 description:

821 "Executable plus arguments to launch the MCP server. Provide after `--`.",

822 },

823 {

824 key: "--env KEY=VALUE",

825 type: "repeatable",

826 description:

827 "Environment variable assignments applied when launching a stdio server.",

828 },

829 {

830 key: "--url",

831 type: "https://…",

832 description:

833 "Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`.",

834 },

835 {

836 key: "--bearer-token-env-var",

837 type: "ENV_VAR",

838 description:

839 "Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.",

840 },

841];

842 

843export const marketplaceCommands = [

844 {

845 key: "add <source>",

846 type: "[--ref REF] [--sparse PATH]",

847 description:

848 "Install a plugin marketplace from GitHub shorthand, a Git URL, an SSH URL, or a local marketplace root directory. `--sparse` is supported only for Git sources and can be repeated.",

849 },

850 {

851 key: "upgrade [marketplace-name]",

852 description:

853 "Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided.",

854 },

855 {

856 key: "remove <marketplace-name>",

857 description: "Remove a configured plugin marketplace.",

858 },

859];

809 860 

810`boolean`861## How to read this reference

811 

812Details

813 

814Run without persisting session rollout files to disk.

815 

816Key

817 

818`--full-auto`

819 

820Type / Values

821 

822`boolean`

823 

824Details

825 

826Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals).

827 

828Key

829 

830`--image, -i`

831 

832Type / Values

833 

834`path[,path...]`

835 

836Details

837 

838Attach images to the first message. Repeatable; supports comma-separated lists.

839 

840Key

841 

842`--json, --experimental-json`

843 

844Type / Values

845 

846`boolean`

847 

848Details

849 

850Print newline-delimited JSON events instead of formatted text.

851 

852Key

853 

854`--model, -m`

855 

856Type / Values

857 

858`string`

859 

860Details

861 

862Override the configured model for this run.

863 

864Key

865 

866`--oss`

867 

868Type / Values

869 

870`boolean`

871 

872Details

873 

874Use the local open source provider (requires a running Ollama instance).

875 862 

876Key863This page catalogs every documented Codex CLI command and flag. Use the interactive tables to search by key or description. Each section indicates whether the option is stable or experimental and calls out risky combinations.

877 864 

878`--output-last-message, -o`865The CLI inherits most defaults from <code>~/.codex/config.toml</code>. Any

866 <code>-c key=value</code> overrides you pass at the command line take

867 precedence for that invocation. See [Config

868 basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.

879 869 

880Type / Values870## Global flags

881 871 

882`path`872<ConfigTable client:load options={globalFlagOptions} />

883 873 

884Details874These options apply to the base `codex` command and propagate to each subcommand unless a section below specifies otherwise.

875When you run a subcommand, place global flags after it (for example, `codex exec --oss ...`) so Codex applies them as intended.

885 876 

886Write the assistant’s final message to a file. Useful for downstream scripting.877## Command overview

887 878 

888Key879The Maturity column uses feature maturity labels such as Experimental, Beta,

880 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to

881 interpret these labels.

889 882 

890`--output-schema`883<ConfigTable

884 client:load

885 options={commandOverview}

886 secondColumnTitle="Maturity"

887 secondColumnVariant="maturity"

888/>

891 889 

892Type / Values890## Command details

893 891 

894`path`892### `codex` (interactive)

895 893