cli/reference.md Codex Docs, 2026-02-24 00:33 UTC → 2026-04-21 18:29 UTC

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

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

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| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |

25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5-codex`). |25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |

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

27| `--oss` | `boolean` | Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running. |27| `--oss` | `boolean` | 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| `--profile, -p` | `string` | Configuration profile name to load from `~/.codex/config.toml`. |

29| `--remote` | `ws://host:port | wss://host:port` | Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode. |

30| `--remote-auth-token-env` | `ENV_VAR` | 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`. |

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

30| `--search` | `boolean` | Enable live web search (sets `web_search = "live"` instead of the default `"cached"`). |32| `--search` | `boolean` | Enable live web search (sets `web_search = "live"` instead of the default `"cached"`). |

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

148 150 

149Details151Details

150 152 

151Override the model set in configuration (for example `gpt-5-codex`).153Override the model set in configuration (for example `gpt-5.4`).

152 154 

153Key155Key

154 156 

188 190 

189Key191Key

190 192 

193`--remote`

194 

195Type / Values

196 

197`ws://host:port | wss://host:port`

198 

199Details

200 

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

202 

203Key

204 

205`--remote-auth-token-env`

206 

207Type / Values

208 

209`ENV_VAR`

210 

211Details

212 

213Read 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`.

214 

215Key

216 

191`--sandbox, -s`217`--sandbox, -s`

192 218 

193Type / Values219Type / Values

236| Key | Maturity | Details |262| Key | Maturity | Details |

237| --- | --- | --- |263| --- | --- | --- |

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. |264| [`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. |

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. |265| [`codex app`](https://developers.openai.com/codex/cli/reference#codex-app) | Stable | 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. |

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. |266| [`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server) | Experimental | Launch the Codex app server for local development or debugging. |

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`. |267| [`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`. |

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`. |268| [`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`. |

250| [`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout) | Stable | Remove stored authentication credentials. |276| [`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout) | Stable | Remove stored authentication credentials. |

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

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. |278| [`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. |

279| [`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace) | Experimental | Add, upgrade, or remove plugin marketplaces from Git or local sources. |

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. |280| [`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. |

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). |281| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes. |

255 282 

256Key283Key

257 284 

275 302 

276Details303Details

277 304 

278Launch the Codex desktop app on macOS, optionally opening a specific workspace path.305Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open.

279 306 

280Key307Key

281 308 

435 462 

436Key463Key

437 464 

465[`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace)

466 

467Maturity

468 

469Experimental

470 

471Details

472 

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

474 

475Key

476 

438[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)477[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)

439 478 

440Maturity479Maturity

455 494 

456Details495Details

457 496 

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

459 498 

460Expand to view all499Expand to view all

461 500 

465 504 

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.505Running `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.

467 506 

507Use `--remote ws://host:port` or `--remote wss://host:port` to connect the TUI to an app server started with `codex app-server --listen ws://IP:PORT`. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication. See [Codex CLI features](https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server) for setup examples and authentication guidance.

508 

468### `codex app-server`509### `codex app-server`

469 510 

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

471 512 

472| Key | Type / Values | Details |513| Key | Type / Values | Details |

473| --- | --- | --- |514| --- | --- | --- |

474| `--listen` | `stdio:// | ws://IP:PORT` | Transport listener URL. `ws://` is experimental and intended for development/testing. |515| `--listen` | `stdio:// | ws://IP:PORT` | Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients. |

516| `--ws-audience` | `string` | Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |

517| `--ws-auth` | `capability-token | signed-bearer-token` | Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup. |

518| `--ws-issuer` | `string` | Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |

519| `--ws-max-clock-skew-seconds` | `number` | Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`. |

520| `--ws-shared-secret-file` | `absolute path` | File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`. |

521| `--ws-token-file` | `absolute path` | File containing the shared capability token. Required with `--ws-auth capability-token`. |

475 522 

476Key523Key

477 524 

483 530 

484Details531Details

485 532 

486Transport listener URL. `ws://` is experimental and intended for development/testing.533Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients.

534 

535Key

536 

537`--ws-audience`

538 

539Type / Values

540 

541`string`

542 

543Details

544 

545Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.

546 

547Key

548 

549`--ws-auth`

550 

551Type / Values

552 

553`capability-token | signed-bearer-token`

554 

555Details

556 

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

558 

559Key

560 

561`--ws-issuer`

562 

563Type / Values

487 564 

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.565`string`

566 

567Details

568 

569Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.

570 

571Key

572 

573`--ws-max-clock-skew-seconds`

574 

575Type / Values

576 

577`number`

578 

579Details

580 

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

582 

583Key

584 

585`--ws-shared-secret-file`

586 

587Type / Values

588 

589`absolute path`

590 

591Details

592 

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

594 

595Key

596 

597`--ws-token-file`

598 

599Type / Values

600 

601`absolute path`

602 

603Details

604 

605File containing the shared capability token. Required with `--ws-auth capability-token`.

606 

607`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior. `--listen ws://IP:PORT` enables WebSocket transport for app-server clients. The server accepts `ws://` listen URLs; use TLS termination or a secure proxy when clients connect with `wss://`. If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.

489 608 

490### `codex app`609### `codex app`

491 610 

492Launch Codex Desktop from the terminal on macOS and optionally open a specific workspace path.611Launch Codex Desktop from the terminal on macOS or Windows. On macOS, Codex can open a specific workspace path; on Windows, Codex prints the path to open.

493 612 

494| Key | Type / Values | Details |613| Key | Type / Values | Details |

495| --- | --- | --- |614| --- | --- | --- |

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

497| `PATH` | `path` | Workspace path to open in Codex Desktop (`codex app` is available on macOS only). |616| `PATH` | `path` | Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path. |

498 617 

499Key618Key

500 619 

506 625 

507Details626Details

508 627 

509Advanced override for the Codex desktop DMG download URL used during install.628Advanced override for the Codex desktop installer URL used during install.

510 629 

511Key630Key

512 631 

518 637 

519Details638Details

520 639 

521Workspace path to open in Codex Desktop (`codex app` is available on macOS only).640Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.

522 641 

523`codex app` installs/opens the desktop app on macOS, then opens the provided workspace path. This subcommand is macOS-only.642`codex app` opens an installed Codex Desktop app, or starts the installer when

643the app is missing. On macOS, Codex opens the provided workspace path; on

644Windows, it prints the path to open after installation.

524 645 

525### `codex debug app-server send-message-v2`646### `codex debug app-server send-message-v2`

526 647 

1275 1396 

1276OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).1397OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).

1277 1398 

1399### `codex plugin marketplace`

1400 

1401Manage plugin marketplace sources that Codex can browse and install from.

1402 

1403| Key | Type / Values | Details |

1404| --- | --- | --- |

1405| `add <source>` | `[--ref REF] [--sparse PATH]` | 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. |

1406| `remove <marketplace-name>` | | Remove a configured plugin marketplace. |

1407| `upgrade [marketplace-name]` | | Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided. |

1408 

1409Key

1410 

1411`add <source>`

1412 

1413Type / Values

1414 

1415`[--ref REF] [--sparse PATH]`

1416 

1417Details

1418 

1419Install 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.

1420 

1421Key

1422 

1423`remove <marketplace-name>`

1424 

1425Details

1426 

1427Remove a configured plugin marketplace.

1428 

1429Key

1430 

1431`upgrade [marketplace-name]`

1432 

1433Details

1434 

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

1436 

1437`codex plugin marketplace add` accepts GitHub shorthand such as `owner/repo` or

1438`owner/repo@ref`, HTTP or HTTPS Git URLs, SSH Git URLs, and local marketplace

1439root directories. Use `--ref` to pin a Git ref, and repeat `--sparse PATH` to

1440use a sparse checkout for Git-backed marketplace repositories.

1441 

1278### `codex mcp-server`1442### `codex mcp-server`

1279 1443 

1280Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.1444Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.