cli/reference.md Codex Docs, 2026-03-11 00:31 UTC → 2026-05-18 22:01 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-codex`). |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 over stdio, WebSocket, or a Unix socket.",

126 126 },

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

128 128 key: "codex remote-control",

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

130 130 type: "experimental",

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

132 132 "Ensure the local app-server daemon is running with remote-control support enabled.",

133Type / Values133 },

134 134 {

135`path[,path...]`135 key: "codex app",

136 136 href: "/codex/cli/reference#codex-app",

137Details137 type: "stable",

138 138 description:

139Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.139 "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.",

140 140 },

141Key141 {

142 142 key: "codex debug app-server send-message-v2",

143`--model, -m`143 href: "/codex/cli/reference#codex-debug-app-server-send-message-v2",

144 144 type: "experimental",

145Type / Values145 description:

146 146 "Debug app-server by sending a single V2 message through the built-in test client.",

147`string`147 },

148 148 {

149Details149 key: "codex debug models",

150 150 href: "/codex/cli/reference#codex-debug-models",

151Override the model set in configuration (for example `gpt-5-codex`).151 type: "experimental",

152 152 description:

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

154 154 },

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

156 156 key: "codex apply",

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

158 158 type: "stable",

159`boolean`159 description:

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

161Details161 },

162 162 {

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

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

165Key165 type: "experimental",

166 166 description:

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

168 168 },

169Type / Values169 {

170 170 key: "codex completion",

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

172 172 type: "stable",

173Details173 description:

174 174 "Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.",

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

176 176 {

177Key177 key: "codex features",

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

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

180 180 description:

181Type / Values181 "List feature flags and persistently enable or disable them in `config.toml`.",

182 182 },

183`string`183 {

184 184 key: "codex exec",

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

186 186 type: "stable",

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

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

189Key189 },

190 190 {

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

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

193Type / Values193 type: "experimental",

194 194 description:

195`read-only | workspace-write | danger-full-access`195 "Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.",

196 196 },

197Details197 {

198 198 key: "codex login",

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

200 200 type: "stable",

201Key201 description:

202 202 "Authenticate Codex using ChatGPT OAuth, device auth, an API key, or an access token piped over stdin.",

203`--search`203 },

204 204 {

205Type / Values205 key: "codex logout",

206 206 href: "/codex/cli/reference#codex-logout",

207`boolean`207 type: "stable",

208 208 description: "Remove stored authentication credentials.",

209Details209 },

210 210 {

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

212 212 href: "/codex/cli/reference#codex-mcp",

213Key213 type: "experimental",

214 214 description:

215`PROMPT`215 "Manage Model Context Protocol servers (list, add, remove, authenticate).",

216 216 },

217Type / Values217 {

218 218 key: "codex plugin marketplace",

219`string`219 href: "/codex/cli/reference#codex-plugin-marketplace",

220 220 type: "experimental",

221Details221 description:

222 222 "Add, upgrade, or remove plugin marketplaces from Git or local sources.",

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 mcp-server",

226 226 href: "/codex/cli/reference#codex-mcp-server",

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

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 "Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.",

230## Command overview230 },

231 231 {

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

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

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

235 235 description:

236| Key | Maturity | Details |236 "Continue a previous interactive session by ID or resume the most recent conversation.",

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 fork",

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-fork",

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: "stable",

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 "Fork a previous interactive session into a new thread, preserving the original transcript.",

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 sandbox",

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-sandbox",

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: "experimental",

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 "Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes.",

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 key: "codex update",

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). |254 href: "/codex/cli/reference#codex-update",

255 255 type: "stable",

256Key256 description:

257 257 "Check for and apply a Codex CLI update when the installed release supports self-update.",

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

259 259];

260Maturity260 

261 261export const execOptions = [

262Stable262 {

263 263 key: "PROMPT",

264Details264 type: "string | - (read stdin)",

265 265 description:

266Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.266 "Initial instruction for the task. Use `-` to pipe the prompt from stdin.",

267 267 },

268Key268 {

269 269 key: "--image, -i",

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

271 271 description:

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

273 273 },

274Stable274 {

275 275 key: "--model, -m",

276Details276 type: "string",

277 277 description: "Override the configured model for this run.",

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

279 279 {

280Key280 key: "--oss",

281 281 type: "boolean",

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

283 283 description:

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

285 285 },

286Experimental286 {

287 287 key: "--sandbox, -s",

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

289 289 description:

290Launch the Codex app server for local development or debugging.290 "Sandbox policy for model-generated commands. Defaults to configuration.",

291 291 },

292Key292 {

293 293 key: "--profile, -p",

294[`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply)294 type: "string",

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

296Maturity296 },

297 297 {

298Stable298 key: "--full-auto",

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 "Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.",

303 303 },

304Key304 {

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

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

307 307 defaultValue: "false",

308Maturity308 description:

309 309 "Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.",

310Experimental310 },

311 311 {

312Details312 key: "--cd, -C",

313 313 type: "path",

314Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.314 description: "Set the workspace root before executing the task.",

315 315 },

316Key316 {

317 317 key: "--skip-git-repo-check",

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

319 319 defaultValue: "false",

320Maturity320 description:

321 321 "Allow running outside a Git repository (useful for one-off directories).",

322Stable322 },

323 323 {

324Details324 key: "--ephemeral",

325 325 type: "boolean",

326Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.326 defaultValue: "false",

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

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-user-config",

331 331 type: "boolean",

332Maturity332 defaultValue: "false",

333 333 description:

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

335 335 },

336Details336 {

337 337 key: "--ignore-rules",

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

339 339 defaultValue: "false",

340Key340 description:

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

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

343 343 {

344Maturity344 key: "--output-schema",

345 345 type: "path",

346Stable346 description:

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

348Details348 },

349 349 {

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

351 351 type: "always | never | auto",

352Key352 defaultValue: "auto",

353 353 description: "Control ANSI color in stdout.",

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

355 355 {

356Maturity356 key: "--json, --experimental-json",

357 357 type: "boolean",

358Experimental358 defaultValue: "false",

359 359 description:

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

361 361 },

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

363 363 key: "--output-last-message, -o",

364Key364 type: "path",

365 365 description:

366[`codex features`](https://developers.openai.com/codex/cli/reference#codex-features)366 "Write the assistant’s final message to a file. Useful for downstream scripting.",

367 367 },

368Maturity368 {

369 369 key: "Resume subcommand",

370Stable370 type: "codex exec resume [SESSION_ID]",

371 371 description:

372Details372 "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.",

373 373 },

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

375 375 key: "-c, --config",

376Key376 type: "key=value",

377 377 description:

378[`codex fork`](https://developers.openai.com/codex/cli/reference#codex-fork)378 "Inline configuration override for the non-interactive run (repeatable).",

379 379 },

380Maturity380];

381 381 

382Stable382export const appServerOptions = [

383 383 {

384Details384 key: "--listen",

385 385 type: "stdio:// | ws://IP:PORT | unix:// | unix://PATH | off",

386Fork a previous interactive session into a new thread, preserving the original transcript.386 defaultValue: "stdio://",

387 387 description:

388Key388 "Transport listener URL. Use `stdio://` for JSONL, `ws://IP:PORT` for a TCP WebSocket endpoint, `unix://` for the default Unix socket, `unix://PATH` for a custom Unix socket, or `off` to disable the local transport.",

389 389 },

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

391 391 key: "--ws-auth",

392Maturity392 type: "capability-token | signed-bearer-token",

393 393 description:

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

395 395 },

396Details396 {

397 397 key: "--ws-token-file",

398Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.398 type: "absolute path",

399 399 description:

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

401 401 },

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

403 403 key: "--ws-shared-secret-file",

404Maturity404 type: "absolute path",

405 405 description:

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

407 407 },

408Details408 {

409 409 key: "--ws-issuer",

410Remove stored authentication credentials.410 type: "string",

411 411 description:

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

413 413 },

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

415 415 key: "--ws-audience",

416Maturity416 type: "string",

417 417 description:

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

419 419 },

420Details420 {

421 421 key: "--ws-max-clock-skew-seconds",

422Manage Model Context Protocol servers (list, add, remove, authenticate).422 type: "number",

423 423 defaultValue: "30",

424Key424 description:

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

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

427 427 {

428Maturity428 key: "--analytics-default-enabled",

429 429 type: "boolean",

430Experimental430 defaultValue: "false",

431 431 description:

432Details432 "Defaults analytics to enabled for first-party app-server clients unless the user opts out in config.",

433 433 },

434Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.434];

435 435 

436Key436export const appOptions = [

437 437 {

438[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)438 key: "PATH",

439 439 type: "path",

440Maturity440 defaultValue: ".",

441 441 description:

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

443 443 },

444Details444 {

445 445 key: "--download-url",

446Continue a previous interactive session by ID or resume the most recent conversation.446 type: "url",

447 447 description:

448Key448 "Advanced override for the Codex desktop installer URL used during install.",

449 449 },

450[`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox)450];

451 451 

452Maturity452export const debugAppServerSendMessageV2Options = [

453 453 {

454Experimental454 key: "USER_MESSAGE",

455 455 type: "string",

456Details456 description:

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

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

459 459];

460Expand to view all460 

461 461export const debugModelsOptions = [

462## Command details462 {

463 463 key: "--bundled",

464### `codex` (interactive)464 type: "boolean",

465 465 defaultValue: "false",

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 description:

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

468### `codex app-server`468 },

469 469];

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

471 471export const resumeOptions = [

472| Key | Type / Values | Details |472 {

473| --- | --- | --- |473 key: "SESSION_ID",

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

475 475 description:

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

477 477 },

478`--listen`478 {

479 479 key: "--last",

480Type / Values480 type: "boolean",

481 481 defaultValue: "false",

482`stdio:// | ws://IP:PORT`482 description:

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

484Details484 },

485 485 {

486Transport listener URL. `ws://` is experimental and intended for development/testing.486 key: "--all",

487 487 type: "boolean",

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 defaultValue: "false",

489 489 description:

490### `codex app`490 "Include sessions outside the current working directory when selecting the most recent session.",

491 491 },

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

493 493 

494| Key | Type / Values | Details |494export const featuresOptions = [

495| --- | --- | --- |495 {

496| `--download-url` | `url` | Advanced override for the Codex desktop DMG download URL used during install. |496 key: "List subcommand",

497| `PATH` | `path` | Workspace path to open in Codex Desktop (`codex app` is available on macOS only). |497 type: "codex features list",

498 498 description:

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

500 500 },

501`--download-url`501 {

502 502 key: "Enable subcommand",

503Type / Values503 type: "codex features enable <feature>",

504 504 description:

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

506 506 },

507Details507 {

508 508 key: "Disable subcommand",

509Advanced override for the Codex desktop DMG download URL used during install.509 type: "codex features disable <feature>",

510 510 description:

511Key511 "Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.",

512 512 },

513`PATH`513];

514 514 

515Type / Values515export const execResumeOptions = [

516 516 {

517`path`517 key: "SESSION_ID",

518 518 type: "uuid",

519Details519 description:

520 520 "Resume the specified session. Omit and use `--last` to continue 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: "--last",

524 524 type: "boolean",

525### `codex debug app-server send-message-v2`525 defaultValue: "false",

526 526 description:

527Send one message through app-server's V2 thread/turn flow using the built-in app-server test client.527 "Resume the most recent conversation from the current working directory.",

528 528 },

529| Key | Type / Values | Details |529 {

530| --- | --- | --- |530 key: "--all",

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

532 532 defaultValue: "false",

533Key533 description:

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

535`USER_MESSAGE`535 },

536 536 {

537Type / Values537 key: "--image, -i",

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

539`string`539 description:

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

541Details541 },

542 542 {

543Message text sent to app-server through the built-in V2 test-client flow.543 key: "PROMPT",

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

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 description:

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

547### `codex apply`547 },

548 548];

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 550export const forkOptions = [

551| Key | Type / Values | Details |551 {

552| --- | --- | --- |552 key: "SESSION_ID",

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

554 554 description:

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

556 556 },

557`TASK_ID`557 {

558 558 key: "--last",

559Type / Values559 type: "boolean",

560 560 defaultValue: "false",

561`string`561 description:

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

563Details563 },

564 564 {

565Identifier of the Codex Cloud task whose diff should be applied.565 key: "--all",

566 566 type: "boolean",

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

568 568 description:

569### `codex cloud`569 "Show sessions beyond the current working directory in the picker.",

570 570 },

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 |573export const execpolicyOptions = [

574| --- | --- | --- |574 {

575| `--attempts` | `1-4` | Number of assistant attempts (best-of-N) Codex Cloud should run. |575 key: "--rules, -r",

576| `--env` | `ENV_ID` | Target Codex Cloud environment identifier (required). Use `codex cloud` to list options. |576 type: "path (repeatable)",

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

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

579Key579 },

580 580 {

581`--attempts`581 key: "--pretty",

582 582 type: "boolean",

583Type / Values583 defaultValue: "false",

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

585`1-4`585 },

586 586 {

587Details587 key: "COMMAND...",

588 588 type: "var-args",

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

590 590 },

591Key591];

592 592 

593`--env`593export const loginOptions = [

594 594 {

595Type / Values595 key: "--with-api-key",

596 596 type: "boolean",

597`ENV_ID`597 description:

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

599Details599 },

600 600 {

601Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.601 key: "--with-access-token",

602 602 type: "boolean",

603Key603 description:

604 604 "Read an access token from stdin (for example `printenv CODEX_ACCESS_TOKEN | codex login --with-access-token`).",

605`QUERY`605 },

606 606 {

607Type / Values607 key: "--device-auth",

608 608 type: "boolean",

609`string`609 description:

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

611Details611 },

612 612 {

613Task prompt. If omitted, Codex prompts interactively for details.613 key: "status subcommand",

614 614 type: "codex login status",

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

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

617#### `codex cloud list`617 },

618 618];

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

620 620export const applyOptions = [

621| Key | Type / Values | Details |621 {

622| --- | --- | --- |622 key: "TASK_ID",

623| `--cursor` | `string` | Pagination cursor returned by a previous request. |623 type: "string",

624| `--env` | `ENV_ID` | Filter tasks by environment identifier. |624 description:

625| `--json` | `boolean` | Emit machine-readable JSON instead of plain text. |625 "Identifier of the Codex Cloud task whose diff should be applied.",

626| `--limit` | `1-20` | Maximum number of tasks to return. |626 },

627 627];

628Key628 

629 629export const sandboxMacOptions = [

630`--cursor`630 {

631 631 key: "--permissions-profile",

632Type / Values632 type: "NAME",

633 633 description:

634`string`634 "Apply a named permissions profile from the active configuration stack.",

635 635 },

636Details636 {

637 637 key: "--cd, -C",

638Pagination cursor returned by a previous request.638 type: "DIR",

639 639 description:

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

641 641 },

642`--env`642 {

643 643 key: "--include-managed-config",

644Type / Values644 type: "boolean",

645 645 defaultValue: "false",

646`ENV_ID`646 description:

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

648Details648 },

649 649 {

650Filter tasks by environment identifier.650 key: "--allow-unix-socket",

651 651 type: "path",

652Key652 description:

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

654`--json`654 },

655 655 {

656Type / Values656 key: "--log-denials",

657 657 type: "boolean",

658`boolean`658 defaultValue: "false",

659 659 description:

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

661 661 },

662Emit machine-readable JSON instead of plain text.662 {

663 663 key: "--config, -c",

664Key664 type: "key=value",

665 665 description:

666`--limit`666 "Pass configuration overrides into the sandboxed run (repeatable).",

667 667 },

668Type / Values668 {

669 669 key: "COMMAND...",

670`1-20`670 type: "var-args",

671 671 description:

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

673 673 },

674Maximum number of tasks to return.674];

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`.676export const sandboxLinuxOptions = [

677 677 {

678### `codex completion`678 key: "--permissions-profile",

679 679 type: "NAME",

680Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.680 description:

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

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

683| --- | --- | --- |683 {

684| `SHELL` | `bash | zsh | fish | power-shell | elvish` | Shell to generate completions for. Output prints to stdout. |684 key: "--cd, -C",

685 685 type: "DIR",

686Key686 description:

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

688`SHELL`688 },

689 689 {

690Type / Values690 key: "--include-managed-config",

691 691 type: "boolean",

692`bash | zsh | fish | power-shell | elvish`692 defaultValue: "false",

693 693 description:

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

695 695 },

696Shell to generate completions for. Output prints to stdout.696 {

697 697 key: "--config, -c",

698### `codex features`698 type: "key=value",

699 699 description:

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 "Configuration overrides applied before launching the sandbox (repeatable).",

701 701 },

702| Key | Type / Values | Details |702 {

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

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

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

706| `List subcommand` | `codex features list` | Show known feature flags, their maturity stage, and their effective state. |706 "Command to execute under Landlock + seccomp. Provide the executable after `--`.",

707 707 },

708Key708];

709 709 

710`Disable subcommand`710export const sandboxWindowsOptions = [

711 711 {

712Type / Values712 key: "--permissions-profile",

713 713 type: "NAME",

714`codex features disable <feature>`714 description:

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

716Details716 },

717 717 {

718Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.718 key: "--cd, -C",

719 719 type: "DIR",

720Key720 description:

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

722`Enable subcommand`722 },

723 723 {

724Type / Values724 key: "--include-managed-config",

725 725 type: "boolean",

726`codex features enable <feature>`726 defaultValue: "false",

727 727 description:

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

729 729 },

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

731 731 key: "--config, -c",

732Key732 type: "key=value",

733 733 description:

734`List subcommand`734 "Configuration overrides applied before launching the sandbox (repeatable).",

735 735 },

736Type / Values736 {

737 737 key: "COMMAND...",

738`codex features list`738 type: "var-args",

739 739 description:

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

741 741 },

742Show known feature flags, their maturity stage, and their effective state.742];

743 743 

744### `codex exec`744export const completionOptions = [

745 745 {

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

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

748| Key | Type / Values | Details |748 defaultValue: "bash",

749| --- | --- | --- |749 description: "Shell to generate completions for. Output prints to stdout.",

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

751| `--color` | `always | never | auto` | Control ANSI color in stdout. |751];

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. |753export const cloudExecOptions = [

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. |755 key: "QUERY",

756| `--json, --experimental-json` | `boolean` | Print newline-delimited JSON events instead of formatted text. |756 type: "string",

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

758| `--oss` | `boolean` | Use the local open source provider (requires a running Ollama instance). |758 "Task prompt. If omitted, Codex prompts interactively for details.",

759| `--output-last-message, -o` | `path` | Write the assistant’s final message to a file. Useful for downstream scripting. |759 },

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 key: "--env",

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

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

764| `-c, --config` | `key=value` | Inline configuration override for the non-interactive run (repeatable). |764 "Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.",

765| `PROMPT` | `string | - (read stdin)` | Initial instruction for the task. Use `-` to pipe the prompt from stdin. |765 },

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 key: "--attempts",

768Key768 type: "1-4",

769 769 defaultValue: "1",

770`--cd, -C`770 description:

771 771 "Number of assistant attempts (best-of-N) Codex Cloud should run.",

772Type / Values772 },

773 773];

774`path`774 

775 775export const cloudListOptions = [

776Details776 {

777 777 key: "--env",

778Set the workspace root before executing the task.778 type: "ENV_ID",

779 779 description: "Filter tasks by environment identifier.",

780Key780 },

781 781 {

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

783 783 type: "1-20",

784Type / Values784 defaultValue: "20",

785 785 description: "Maximum number of tasks to return.",

786`always | never | auto`786 },

787 787 {

788Details788 key: "--cursor",

789 789 type: "string",

790Control ANSI color in stdout.790 description: "Pagination cursor returned by a previous request.",

791 791 },

792Key792 {

793 793 key: "--json",

794`--dangerously-bypass-approvals-and-sandbox, --yolo`794 type: "boolean",

795 795 defaultValue: "false",

796Type / Values796 description: "Emit machine-readable JSON instead of plain text.",

797 797 },

798`boolean`798];

799 799 

800Details800export const mcpCommands = [

801 801 {

802Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.802 key: "list",

803 803 type: "--json",

804Key804 description:

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

806 },

807 {

808 key: "get <name>",

809 type: "--json",

810 description:

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

812 },

813 {

814 key: "add <name>",

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

816 description:

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

818 },

819 {

820 key: "remove <name>",

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

822 },

823 {

824 key: "login <name>",

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

826 description:

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

828 },

829 {

830 key: "logout <name>",

831 description:

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

833 },

834];

835 

836export const mcpAddOptions = [

837 {

838 key: "COMMAND...",

839 type: "stdio transport",

840 description:

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

842 },

843 {

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

845 type: "repeatable",

846 description:

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

848 },

849 {

850 key: "--url",

851 type: "https://…",

852 description:

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

854 },

855 {

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

857 type: "ENV_VAR",

858 description:

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

860 },

861];

862 

863export const marketplaceCommands = [

864 {

865 key: "add <source>",

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

867 description:

868 "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.",

869 },

870 {

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

872 description:

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

874 },

875 {

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

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

878 },

879];

805 880 

806`--ephemeral`881## How to read this reference

807 

808Type / Values

809 

810`boolean`

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 882 

872Details883This 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.

873 884 

874Use the local open source provider (requires a running Ollama instance).885The CLI inherits most defaults from <code>~/.codex/config.toml</code>. Any

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

887 precedence for that invocation. See [Config