cli/reference.md Codex Docs, 2026-04-21 12:30 UTC → 2026-04-30 18:36 UTC

20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |

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

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

24| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |23| `--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.4`). |24| `--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). |25| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |

118 117 

119Key118Key

120 119 

121`--full-auto`

122 

123Type / Values

124 

125`boolean`

126 

127Details

128 

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

130 

131Key

132 

133`--image, -i`120`--image, -i`

134 121 

135Type / Values122Type / Values

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

269| [`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion) | Stable | Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell. |256| [`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion) | Stable | Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell. |

270| [`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. |257| [`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. |

258| [`codex debug models`](https://developers.openai.com/codex/cli/reference#codex-debug-models) | Experimental | Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog. |

271| [`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. |259| [`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. |

272| [`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. |260| [`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. |

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

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

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

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

270| [`codex update`](https://developers.openai.com/codex/cli/reference#codex-update) | Stable | Check for and apply a Codex CLI update when the installed release supports self-update. |

282 271 

283Key272Key

284 273 

366 355 

367Key356Key

368 357 

358[`codex debug models`](https://developers.openai.com/codex/cli/reference#codex-debug-models)

359 

360Maturity

361 

362Experimental

363 

364Details

365 

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

367 

368Key

369 

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

370 371 

371Maturity372Maturity

494 495 

495Details496Details

496 497 

497Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes.498Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes.

499 

500Key

501 

502[`codex update`](https://developers.openai.com/codex/cli/reference#codex-update)

503 

504Maturity

505 

506Stable

507 

508Details

509 

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

498 511 

499Expand to view all512Expand to view all

500 513 

502 515 

503### `codex` (interactive)516### `codex` (interactive)

504 517 

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.518Running `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. For low-friction local work, use `--sandbox workspace-write --ask-for-approval on-request`.

506 519 

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.520Use `--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 521 

665 678 

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

667 680 

681### `codex debug models`

682 

683Print the raw model catalog Codex sees as JSON.

684 

685| Key | Type / Values | Details |

686| --- | --- | --- |

687| `--bundled` | `boolean` | Skip refresh and print only the model catalog bundled with the current Codex binary. |

688 

689Key

690 

691`--bundled`

692 

693Type / Values

694 

695`boolean`

696 

697Details

698 

699Skip refresh and print only the model catalog bundled with the current Codex binary.

700 

701Use `--bundled` when you want to inspect only the catalog bundled with the current binary, without refreshing from the remote models endpoint.

702 

668### `codex apply`703### `codex apply`

669 704 

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

872| `--color` | `always | never | auto` | Control ANSI color in stdout. |907| `--color` | `always | never | auto` | Control ANSI color in stdout. |

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

874| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |909| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |

875| `--full-auto` | `boolean` | Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals). |910| `--full-auto` | `boolean` | Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used. |

911| `--ignore-rules` | `boolean` | Do not load user or project execpolicy `.rules` files for this run. |

912| `--ignore-user-config` | `boolean` | Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`. |

876| `--image, -i` | `path[,path...]` | Attach images to the first message. Repeatable; supports comma-separated lists. |913| `--image, -i` | `path[,path...]` | Attach images to the first message. Repeatable; supports comma-separated lists. |

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

878| `--model, -m` | `string` | Override the configured model for this run. |915| `--model, -m` | `string` | Override the configured model for this run. |

944 981 

945Details982Details

946 983 

947Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals).984Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.

985 

986Key

987 

988`--ignore-rules`

989 

990Type / Values

991 

992`boolean`

993 

994Details

995 

996Do not load user or project execpolicy `.rules` files for this run.

997 

998Key

999 

1000`--ignore-user-config`

1001 

1002Type / Values

1003 

1004`boolean`

1005 

1006Details

1007 

1008Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`.

948 1009 

949Key1010Key

950 1011 

1543 1604 

1544| Key | Type / Values | Details |1605| Key | Type / Values | Details |

1545| --- | --- | --- |1606| --- | --- | --- |

1607| `--allow-unix-socket` | `path` | Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths. |

1608| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |

1546| `--config, -c` | `key=value` | Pass configuration overrides into the sandboxed run (repeatable). |1609| `--config, -c` | `key=value` | Pass configuration overrides into the sandboxed run (repeatable). |

1547| `--full-auto` | `boolean` | Grant write access to the current workspace and `/tmp` without approvals. |1610| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |

1611| `--log-denials` | `boolean` | Capture macOS sandbox denials with `log stream` while the command runs and print them after exit. |

1612| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |

1548| `COMMAND...` | `var-args` | Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded. |1613| `COMMAND...` | `var-args` | Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded. |

1549 1614 

1550Key1615Key

1551 1616 

1617`--allow-unix-socket`

1618 

1619Type / Values

1620 

1621`path`

1622 

1623Details

1624 

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

1626 

1627Key

1628 

1629`--cd, -C`

1630 

1631Type / Values

1632 

1633`DIR`

1634 

1635Details

1636 

1637Working directory used for profile resolution and command execution. Requires `--permissions-profile`.

1638 

1639Key

1640 

1552`--config, -c`1641`--config, -c`

1553 1642 

1554Type / Values1643Type / Values

1561 1650 

1562Key1651Key

1563 1652 

1564`--full-auto`1653`--include-managed-config`

1654 

1655Type / Values

1656 

1657`boolean`

1658 

1659Details

1660 

1661Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.

1662 

1663Key

1664 

1665`--log-denials`

1565 1666 

1566Type / Values1667Type / Values

1567 1668 

1569 1670 

1570Details1671Details

1571 1672 

1572Grant write access to the current workspace and `/tmp` without approvals.1673Capture macOS sandbox denials with `log stream` while the command runs and print them after exit.

1674 

1675Key

1676 

1677`--permissions-profile`

1678 

1679Type / Values

1680 

1681`NAME`

1682 

1683Details

1684 

1685Apply a named permissions profile from the active configuration stack.

1573 1686 

1574Key1687Key

1575 1688 

1587 1700 

1588| Key | Type / Values | Details |1701| Key | Type / Values | Details |

1589| --- | --- | --- |1702| --- | --- | --- |

1703| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |

1590| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |1704| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |

1591| `--full-auto` | `boolean` | Grant write access to the current workspace and `/tmp` inside the Landlock sandbox. |1705| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |

1706| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |

1592| `COMMAND...` | `var-args` | Command to execute under Landlock + seccomp. Provide the executable after `--`. |1707| `COMMAND...` | `var-args` | Command to execute under Landlock + seccomp. Provide the executable after `--`. |

1593 1708 

1594Key1709Key

1595 1710 

1711`--cd, -C`

1712 

1713Type / Values

1714 

1715`DIR`

1716 

1717Details

1718 

1719Working directory used for profile resolution and command execution. Requires `--permissions-profile`.

1720 

1721Key

1722 

1596`--config, -c`1723`--config, -c`

1597 1724 

1598Type / Values1725Type / Values

1605 1732 

1606Key1733Key

1607 1734 

1608`--full-auto`1735`--include-managed-config`

1609 1736 

1610Type / Values1737Type / Values

1611 1738 

1613 1740 

1614Details1741Details

1615 1742 

1616Grant write access to the current workspace and `/tmp` inside the Landlock sandbox.1743Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.

1744 

1745Key

1746 

1747`--permissions-profile`

1748 

1749Type / Values

1750 

1751`NAME`

1752 

1753Details

1754 

1755Apply a named permissions profile from the active configuration stack.

1617 1756 

1618Key1757Key

1619 1758 

1627 1766 

1628Command to execute under Landlock + seccomp. Provide the executable after `--`.1767Command to execute under Landlock + seccomp. Provide the executable after `--`.

1629 1768 

1769#### Windows

1770 

1771| Key | Type / Values | Details |

1772| --- | --- | --- |

1773| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |

1774| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |

1775| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |

1776| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |

1777| `COMMAND...` | `var-args` | Command to execute under the native Windows sandbox. Provide the executable after `--`. |

1778 

1779Key

1780 

1781`--cd, -C`

1782 

1783Type / Values

1784 

1785`DIR`

1786 

1787Details

1788 

1789Working directory used for profile resolution and command execution. Requires `--permissions-profile`.

1790 

1791Key

1792 

1793`--config, -c`

1794 

1795Type / Values

1796 

1797`key=value`

1798 

1799Details

1800 

1801Configuration overrides applied before launching the sandbox (repeatable).

1802 

1803Key

1804 

1805`--include-managed-config`

1806 

1807Type / Values

1808 

1809`boolean`

1810 

1811Details

1812 

1813Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.

1814 

1815Key

1816 

1817`--permissions-profile`

1818 

1819Type / Values

1820 

1821`NAME`

1822 

1823Details

1824 

1825Apply a named permissions profile from the active configuration stack.

1826 

1827Key

1828 

1829`COMMAND...`

1830 

1831Type / Values

1832 

1833`var-args`

1834 

1835Details

1836 

1837Command to execute under the native Windows sandbox. Provide the executable after `--`.

1838 

1839### `codex update`

1840 

1841Check for and apply a Codex CLI update when the installed release supports self-update. Debug builds print a message telling you to install a release build instead.

1842 

1630## Flag combinations and safety tips1843## Flag combinations and safety tips

1631 1844 

1632- Set `--full-auto` for unattended local work, but avoid combining it with `--dangerously-bypass-approvals-and-sandbox` unless you are inside a dedicated sandbox VM.1845- Use `--sandbox workspace-write` for unattended local work that can stay inside the workspace, and avoid `--dangerously-bypass-approvals-and-sandbox` unless you are inside a dedicated sandbox VM.

1633- When you need to grant Codex write access to more directories, prefer `--add-dir` rather than forcing `--sandbox danger-full-access`.1846- When you need to grant Codex write access to more directories, prefer `--add-dir` rather than forcing `--sandbox danger-full-access`.

1634- Pair `--json` with `--output-last-message` in CI to capture machine-readable progress and a final natural-language summary.1847- Pair `--json` with `--output-last-message` in CI to capture machine-readable progress and a final natural-language summary.

1635 1848