cli/reference.md Codex Docs, 2026-02-19 20:37 UTC → 2026-04-24 18:20 UTC

1# Command line options1# Command line options

2 2 

3Options and flags for the Codex terminal client

4 

5## How to read this reference3## How to read this reference

6 4 

7This 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.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.

24| `--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. |

25| `--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`. |

26| `--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. |

27| `--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`). |

28| `--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). |

29| `--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. |

30| `--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`. |

31| `--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. |

32| `--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"`). |

33| `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. |

150 150 

151Details151Details

152 152 

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

154 154 

155Key155Key

156 156 

190 190 

191Key191Key

192 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 

193`--sandbox, -s`217`--sandbox, -s`

194 218 

195Type / Values219Type / Values

238| Key | Maturity | Details |262| Key | Maturity | Details |

239| --- | --- | --- |263| --- | --- | --- |

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

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

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

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

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

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

253| [`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). |

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

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

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

257 282 

258Key283Key

259 284 

277 302 

278Details303Details

279 304 

280Launch 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.

281 306 

282Key307Key

283 308 

437 462 

438Key463Key

439 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 

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

441 478 

442Maturity479Maturity

457 494 

458Details495Details

459 496 

460Run 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.

461 498 

462Expand to view all499Expand to view all

463 500 

467 504 

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

469 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 

470### `codex app-server`509### `codex app-server`

471 510 

472Launch 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.

473 512 

474| Key | Type / Values | Details |513| Key | Type / Values | Details |

475| --- | --- | --- |514| --- | --- | --- |

476| `--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`. |

477 522 

478Key523Key

479 524 

485 530 

486Details531Details

487 532 

488Transport 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

564 

565`string`

566 

567Details

489 568 

490`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.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.

491 608 

492### `codex app`609### `codex app`

493 610 

494Launch 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.

495 612 

496| Key | Type / Values | Details |613| Key | Type / Values | Details |

497| --- | --- | --- |614| --- | --- | --- |

498| `--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. |

499| `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. |

500 617 

501Key618Key

502 619 

508 625 

509Details626Details

510 627 

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

512 629 

513Key630Key

514 631 

520 637 

521Details638Details

522 639 

523Workspace 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.

524 641 

525`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.

526 645 

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

528 647 

1277 1396 

1278OAuth 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).

1279 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 

1280### `codex mcp-server`1442### `codex mcp-server`

1281 1443 

1282Run 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.

1477- [Config basics](https://developers.openai.com/codex/config-basic): persist defaults like the model and provider.1639- [Config basics](https://developers.openai.com/codex/config-basic): persist defaults like the model and provider.

1478- [Advanced Config](https://developers.openai.com/codex/config-advanced): profiles, providers, sandbox tuning, and integrations.1640- [Advanced Config](https://developers.openai.com/codex/config-advanced): profiles, providers, sandbox tuning, and integrations.

1479- [AGENTS.md](https://developers.openai.com/codex/guides/agents-md): conceptual overview of Codex agent capabilities and best practices.1641- [AGENTS.md](https://developers.openai.com/codex/guides/agents-md): conceptual overview of Codex agent capabilities and best practices.

1480 

1481[Previous

1482 

1483Features](https://developers.openai.com/codex/cli/features)[Next

1484 

1485Slash commands](https://developers.openai.com/codex/cli/slash-commands)