1# Command line options1# Command line options
2 2
3## How to read this reference3export const globalFlagOptions = [
4 4 {
5This page catalogs every documented Codex CLI command and flag. Use the interactive tables to search by key or description. Each section indicates whether the option is stable or experimental and calls out risky combinations.5 key: "PROMPT",
6 6 type: "string",
7The CLI inherits most defaults from <code>~/.codex/config.toml</code>. Any7 description:
8 <code>-c key=value</code> overrides you pass at the command line take8 "Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.",
9 precedence for that invocation. See [Config9 },
10 basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.10 {
11 11 key: "--image, -i",
12## Global flags12 type: "path[,path...]",
13 13 description:
14| Key | Type / Values | Details |14 "Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.",
15| --- | --- | --- |15 },
16| `--add-dir` | `path` | Grant additional directories write access alongside the main workspace. Repeat for multiple paths. |16 {
17| `--ask-for-approval, -a` | `untrusted | on-request | never` | Control when Codex pauses for human approval before running a command. `on-failure` is deprecated; prefer `on-request` for interactive runs or `never` for non-interactive runs. |17 key: "--model, -m",
18| `--cd, -C` | `path` | Set the working directory for the agent before it starts processing your request. |18 type: "string",
19| `--config, -c` | `key=value` | Override configuration values. Values parse as JSON if possible; otherwise the literal string is used. |19 description:
20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |20 "Override the model set in configuration (for example `gpt-5.4`).",
21| `--disable` | `feature` | Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable. |21 },
22| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |22 {
23| `--full-auto` | `boolean` | Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`. |23 key: "--oss",
24| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |24 type: "boolean",
25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |25 defaultValue: "false",
26| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |26 description:
27| `--oss` | `boolean` | Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running. |27 'Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running.',
28| `--profile, -p` | `string` | Configuration profile name to load from `~/.codex/config.toml`. |28 },
29| `--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. |29 {
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`. |30 key: "--profile, -p",
31| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Select the sandbox policy for model-generated shell commands. |31 type: "string",
32| `--search` | `boolean` | Enable live web search (sets `web_search = "live"` instead of the default `"cached"`). |32 description:
33| `PROMPT` | `string` | Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message. |33 "Configuration profile name to load from `~/.codex/config.toml`.",
34 34 },
35Key35 {
36 36 key: "--sandbox, -s",
37`--add-dir`37 type: "read-only | workspace-write | danger-full-access",
38 38 description:
39Type / Values39 "Select the sandbox policy for model-generated shell commands.",
40 40 },
41`path`41 {
42 42 key: "--ask-for-approval, -a",
43Details43 type: "untrusted | on-request | never",
44 44 description:
45Grant additional directories write access alongside the main workspace. Repeat for multiple paths.45 "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 },
47Key47 {
48 48 key: "--dangerously-bypass-approvals-and-sandbox, --yolo",
49`--ask-for-approval, -a`49 type: "boolean",
50 50 defaultValue: "false",
51Type / Values51 description:
52 52 "Run every command without approvals or sandboxing. Only use inside an externally hardened environment.",
53`untrusted | on-request | never`53 },
54 54 {
55Details55 key: "--cd, -C",
56 56 type: "path",
57Control 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.57 description:
58 58 "Set the working directory for the agent before it starts processing your request.",
59Key59 },
60 60 {
61`--cd, -C`61 key: "--search",
62 62 type: "boolean",
63Type / Values63 defaultValue: "false",
64 64 description:
65`path`65 'Enable live web search (sets `web_search = "live"` instead of the default `"cached"`).',
66 66 },
67Details67 {
68 68 key: "--add-dir",
69Set the working directory for the agent before it starts processing your request.69 type: "path",
70 70 description:
71Key71 "Grant additional directories write access alongside the main workspace. Repeat for multiple paths.",
72 72 },
73`--config, -c`73 {
74 74 key: "--no-alt-screen",
75Type / Values75 type: "boolean",
76 76 defaultValue: "false",
77`key=value`77 description:
78 78 "Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run).",
79Details79 },
80 80 {
81Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.81 key: "--remote",
82 82 type: "ws://host:port | wss://host:port",
83Key83 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.",
85`--dangerously-bypass-approvals-and-sandbox, --yolo`85 },
86 86 {
87Type / Values87 key: "--remote-auth-token-env",
88 88 type: "ENV_VAR",
89`boolean`89 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`.",
91Details91 },
92 92 {
93Run every command without approvals or sandboxing. Only use inside an externally hardened environment.93 key: "--enable",
94 94 type: "feature",
95Key95 description:
96 96 "Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable.",
97`--disable`97 },
98 98 {
99Type / Values99 key: "--disable",
100 100 type: "feature",
101`feature`101 description:
102 102 "Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable.",
103Details103 },
104 104 {
105Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable.105 key: "--config, -c",
106 106 type: "key=value",
107Key107 description:
108 108 "Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.",
109`--enable`109 },
110 110];
111Type / Values111
112 112export const commandOverview = [
113`feature`113 {
114 114 key: "codex",
115Details115 href: "/codex/cli/reference#codex-interactive",
116 116 type: "stable",
117Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable.117 description:
118 118 "Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.",
119Key119 },
120 120 {
121`--full-auto`121 key: "codex app-server",
122 122 href: "/codex/cli/reference#codex-app-server",
123Type / Values123 type: "experimental",
124 124 description:
125`boolean`125 "Launch the Codex app server for local development or debugging over stdio, WebSocket, or a Unix socket.",
126 126 },
127Details127 {
128 128 key: "codex remote-control",
129Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`.129 href: "/codex/cli/reference#codex-remote-control",
130 130 type: "experimental",
131Key131 description:
132 132 "Ensure the local app-server daemon is running with remote-control support enabled.",
133`--image, -i`133 },
134 134 {
135Type / Values135 key: "codex app",
136 136 href: "/codex/cli/reference#codex-app",
137`path[,path...]`137 type: "stable",
138 138 description:
139Details139 "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 },
141Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.141 {
142 142 key: "codex debug app-server send-message-v2",
143Key143 href: "/codex/cli/reference#codex-debug-app-server-send-message-v2",
144 144 type: "experimental",
145`--model, -m`145 description:
146 146 "Debug app-server by sending a single V2 message through the built-in test client.",
147Type / Values147 },
148 148 {
149`string`149 key: "codex debug models",
150 150 href: "/codex/cli/reference#codex-debug-models",
151Details151 type: "experimental",
152 152 description:
153Override the model set in configuration (for example `gpt-5.4`).153 "Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog.",
154 154 },
155Key155 {
156 156 key: "codex apply",
157`--no-alt-screen`157 href: "/codex/cli/reference#codex-apply",
158 158 type: "stable",
159Type / Values159 description:
160 160 "Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.",
161`boolean`161 },
162 162 {
163Details163 key: "codex cloud",
164 164 href: "/codex/cli/reference#codex-cloud",
165Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run).165 type: "experimental",
166 166 description:
167Key167 "Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.",
168 168 },
169`--oss`169 {
170 170 key: "codex completion",
171Type / Values171 href: "/codex/cli/reference#codex-completion",
172 172 type: "stable",
173`boolean`173 description:
174 174 "Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.",
175Details175 },
176 176 {
177Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running.177 key: "codex features",
178 178 href: "/codex/cli/reference#codex-features",
179Key179 type: "stable",
180 180 description:
181`--profile, -p`181 "List feature flags and persistently enable or disable them in `config.toml`.",
182 182 },
183Type / Values183 {
184 184 key: "codex exec",
185`string`185 href: "/codex/cli/reference#codex-exec",
186 186 type: "stable",
187Details187 description:
188 188 "Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.",
189Configuration profile name to load from `~/.codex/config.toml`.189 },
190 190 {
191Key191 key: "codex execpolicy",
192 192 href: "/codex/cli/reference#codex-execpolicy",
193`--remote`193 type: "experimental",
194 194 description:
195Type / Values195 "Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.",
196 196 },
197`ws://host:port | wss://host:port`197 {
198 198 key: "codex login",
199Details199 href: "/codex/cli/reference#codex-login",
200 200 type: "stable",
201Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode.201 description:
202 202 "Authenticate Codex using ChatGPT OAuth, device auth, an API key, or an access token piped over stdin.",
203Key203 },
204 204 {
205`--remote-auth-token-env`205 key: "codex logout",
206 206 href: "/codex/cli/reference#codex-logout",
207Type / Values207 type: "stable",
208 208 description: "Remove stored authentication credentials.",
209`ENV_VAR`209 },
210 210 {
211Details211 key: "codex mcp",
212 212 href: "/codex/cli/reference#codex-mcp",
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`.213 type: "experimental",
214 214 description:
215Key215 "Manage Model Context Protocol servers (list, add, remove, authenticate).",
216 216 },
217`--sandbox, -s`217 {
218 218 key: "codex plugin marketplace",
219Type / Values219 href: "/codex/cli/reference#codex-plugin-marketplace",
220 220 type: "experimental",
221`read-only | workspace-write | danger-full-access`221 description:
222 222 "Add, upgrade, or remove plugin marketplaces from Git or local sources.",
223Details223 },
224 224 {
225Select the sandbox policy for model-generated shell commands.225 key: "codex mcp-server",
226 226 href: "/codex/cli/reference#codex-mcp-server",
227Key227 type: "experimental",
228 228 description:
229`--search`229 "Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.",
230 230 },
231Type / Values231 {
232 232 key: "codex resume",
233`boolean`233 href: "/codex/cli/reference#codex-resume",
234 234 type: "stable",
235Details235 description:
236 236 "Continue a previous interactive session by ID or resume the most recent conversation.",
237Enable live web search (sets `web_search = "live"` instead of the default `"cached"`).237 },
238 238 {
239Key239 key: "codex fork",
240 240 href: "/codex/cli/reference#codex-fork",
241`PROMPT`241 type: "stable",
242 242 description:
243Type / Values243 "Fork a previous interactive session into a new thread, preserving the original transcript.",
244 244 },
245`string`245 {
246 246 key: "codex sandbox",
247Details247 href: "/codex/cli/reference#codex-sandbox",
248 248 type: "experimental",
249Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.249 description:
250 250 "Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes.",
251Expand to view all251 },
252 252 {
253These options apply to the base `codex` command and propagate to each subcommand unless a section below specifies otherwise.253 key: "codex update",
254When you run a subcommand, place global flags after it (for example, `codex exec --oss ...`) so Codex applies them as intended.254 href: "/codex/cli/reference#codex-update",
255 255 type: "stable",
256## Command overview256 description:
257 257 "Check for and apply a Codex CLI update when the installed release supports self-update.",
258The Maturity column uses feature maturity labels such as Experimental, Beta,258 },
259 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to259];
260 interpret these labels.260
261 261export const execOptions = [
262| Key | Maturity | Details |262 {
263| --- | --- | --- |263 key: "PROMPT",
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. |264 type: "string | - (read stdin)",
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. |265 description:
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. |266 "Initial instruction for the task. Use `-` to pipe the prompt from stdin.",
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`. |267 },
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`. |268 {
269| [`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion) | Stable | Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell. |269 key: "--image, -i",
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. |270 type: "path[,path...]",
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. |271 description:
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. |272 "Attach images to the first message. Repeatable; supports comma-separated lists.",
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`. |273 },
274| [`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. |274 {
275| [`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. |275 key: "--model, -m",
276| [`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout) | Stable | Remove stored authentication credentials. |276 type: "string",
277| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |277 description: "Override the configured model for this run.",
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. |278 },
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. |279 {
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. |280 key: "--oss",
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. |281 type: "boolean",
282 282 defaultValue: "false",
283Key283 description:
284 284 "Use the local open source provider (requires a running Ollama instance).",
285[`codex`](https://developers.openai.com/codex/cli/reference#codex-interactive)285 },
286 286 {
287Maturity287 key: "--sandbox, -s",
288 288 type: "read-only | workspace-write | danger-full-access",
289Stable289 description:
290 290 "Sandbox policy for model-generated commands. Defaults to configuration.",
291Details291 },
292 292 {
293Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.293 key: "--profile, -p",
294 294 type: "string",
295Key295 description: "Select a configuration profile defined in config.toml.",
296 296 },
297[`codex app`](https://developers.openai.com/codex/cli/reference#codex-app)297 {
298 298 key: "--full-auto",
299Maturity299 type: "boolean",
300 300 defaultValue: "false",
301Stable301 description:
302 302 "Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.",
303Details303 },
304 304 {
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.305 key: "--dangerously-bypass-approvals-and-sandbox, --yolo",
306 306 type: "boolean",
307Key307 defaultValue: "false",
308 308 description:
309[`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server)309 "Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.",
310 310 },
311Maturity311 {
312 312 key: "--cd, -C",
313Experimental313 type: "path",
314 314 description: "Set the workspace root before executing the task.",
315Details315 },
316 316 {
317Launch the Codex app server for local development or debugging.317 key: "--skip-git-repo-check",
318 318 type: "boolean",
319Key319 defaultValue: "false",
320 320 description:
321[`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply)321 "Allow running outside a Git repository (useful for one-off directories).",
322 322 },
323Maturity323 {
324 324 key: "--ephemeral",
325Stable325 type: "boolean",
326 326 defaultValue: "false",
327Details327 description: "Run without persisting session rollout files to disk.",
328 328 },
329Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.329 {
330 330 key: "--ignore-user-config",
331Key331 type: "boolean",
332 332 defaultValue: "false",
333[`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud)333 description:
334 334 "Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`.",
335Maturity335 },
336 336 {
337Experimental337 key: "--ignore-rules",
338 338 type: "boolean",
339Details339 defaultValue: "false",
340 340 description:
341Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.341 "Do not load user or project execpolicy `.rules` files for this run.",
342 342 },
343Key343 {
344 344 key: "--output-schema",
345[`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion)345 type: "path",
346 346 description:
347Maturity347 "JSON Schema file describing the expected final response shape. Codex validates tool output against it.",
348 348 },
349Stable349 {
350 350 key: "--color",
351Details351 type: "always | never | auto",
352 352 defaultValue: "auto",
353Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.353 description: "Control ANSI color in stdout.",
354 354 },
355Key355 {
356 356 key: "--json, --experimental-json",
357[`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2)357 type: "boolean",
358 358 defaultValue: "false",
359Maturity359 description:
360 360 "Print newline-delimited JSON events instead of formatted text.",
361Experimental361 },
362 362 {
363Details363 key: "--output-last-message, -o",
364 364 type: "path",
365Debug app-server by sending a single V2 message through the built-in test client.365 description:
366 366 "Write the assistant’s final message to a file. Useful for downstream scripting.",
367Key367 },
368 368 {
369[`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec)369 key: "Resume subcommand",
370 370 type: "codex exec resume [SESSION_ID]",
371Maturity371 description:
372 372 "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.",
373Stable373 },
374 374 {
375Details375 key: "-c, --config",
376 376 type: "key=value",
377Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.377 description:
378 378 "Inline configuration override for the non-interactive run (repeatable).",
379Key379 },
380 380];
381[`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy)381
382 382export const appServerOptions = [
383Maturity383 {
384 384 key: "--listen",
385Experimental385 type: "stdio:// | ws://IP:PORT | unix:// | unix://PATH | off",
386 386 defaultValue: "stdio://",
387Details387 description:
388 388 "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.",
389Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.389 },
390 390 {
391Key391 key: "--ws-auth",
392 392 type: "capability-token | signed-bearer-token",
393[`codex features`](https://developers.openai.com/codex/cli/reference#codex-features)393 description:
394 394 "Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup.",
395Maturity395 },
396 396 {
397Stable397 key: "--ws-token-file",
398 398 type: "absolute path",
399Details399 description:
400 400 "File containing the shared capability token. Required with `--ws-auth capability-token`.",
401List feature flags and persistently enable or disable them in `config.toml`.401 },
402 402 {
403Key403 key: "--ws-shared-secret-file",
404 404 type: "absolute path",
405[`codex fork`](https://developers.openai.com/codex/cli/reference#codex-fork)405 description:
406 406 "File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.",
407Maturity407 },
408 408 {
409Stable409 key: "--ws-issuer",
410 410 type: "string",
411Details411 description:
412 412 "Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.",
413Fork a previous interactive session into a new thread, preserving the original transcript.413 },
414 414 {
415Key415 key: "--ws-audience",
416 416 type: "string",
417[`codex login`](https://developers.openai.com/codex/cli/reference#codex-login)417 description:
418 418 "Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.",
419Maturity419 },
420 420 {
421Stable421 key: "--ws-max-clock-skew-seconds",
422 422 type: "number",
423Details423 defaultValue: "30",
424 424 description:
425Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.425 "Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.",
426 426 },
427Key427 {
428 428 key: "--analytics-default-enabled",
429[`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout)429 type: "boolean",
430 430 defaultValue: "false",
431Maturity431 description:
432 432 "Defaults analytics to enabled for first-party app-server clients unless the user opts out in config.",
433Stable433 },
434 434];
435Details435
436 436export const appOptions = [
437Remove stored authentication credentials.437 {
438 438 key: "PATH",
439Key439 type: "path",
440 440 defaultValue: ".",
441[`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp)441 description:
442 442 "Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.",
443Maturity443 },
444 444 {
445Experimental445 key: "--download-url",
446 446 type: "url",
447Details447 description:
448 448 "Advanced override for the Codex desktop installer URL used during install.",
449Manage Model Context Protocol servers (list, add, remove, authenticate).449 },
450 450];
451Key451
452 452export const debugAppServerSendMessageV2Options = [
453[`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server)453 {
454 454 key: "USER_MESSAGE",
455Maturity455 type: "string",
456 456 description:
457Experimental457 "Message text sent to app-server through the built-in V2 test-client flow.",
458 458 },
459Details459];
460 460
461Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.461export const debugModelsOptions = [
462 462 {
463Key463 key: "--bundled",
464 464 type: "boolean",
465[`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace)465 defaultValue: "false",
466 466 description:
467Maturity467 "Skip refresh and print only the model catalog bundled with the current Codex binary.",
468 468 },
469Experimental469];
470 470
471Details471export const resumeOptions = [
472 472 {
473Add, upgrade, or remove plugin marketplaces from Git or local sources.473 key: "SESSION_ID",
474 474 type: "uuid",
475Key475 description:
476 476 "Resume the specified session. Omit and use `--last` to continue the most recent session.",
477[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)477 },
478 478 {
479Maturity479 key: "--last",
480 480 type: "boolean",
481Stable481 defaultValue: "false",
482 482 description:
483Details483 "Skip the picker and resume the most recent conversation from the current working directory.",
484 484 },
485Continue a previous interactive session by ID or resume the most recent conversation.485 {
486 486 key: "--all",
487Key487 type: "boolean",
488 488 defaultValue: "false",
489[`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox)489 description:
490 490 "Include sessions outside the current working directory when selecting the most recent session.",
491Maturity491 },
492 492];
493Experimental493
494 494export const featuresOptions = [
495Details495 {
496 496 key: "List subcommand",
497Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes.497 type: "codex features list",
498 498 description:
499Expand to view all499 "Show known feature flags, their maturity stage, and their effective state.",
500 500 },
501## Command details501 {
502 502 key: "Enable subcommand",
503### `codex` (interactive)503 type: "codex features enable <feature>",
504 504 description:
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.505 "Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.",
506 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.507 {
508 508 key: "Disable subcommand",
509### `codex app-server`509 type: "codex features disable <feature>",
510 510 description:
511Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.511 "Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.",
512 512 },
513| Key | Type / Values | Details |513];
514| --- | --- | --- |514
515| `--listen` | `stdio:// | ws://IP:PORT` | Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients. |515export const execResumeOptions = [
516| `--ws-audience` | `string` | Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |516 {
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. |517 key: "SESSION_ID",
518| `--ws-issuer` | `string` | Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |518 type: "uuid",
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`. |519 description:
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`. |520 "Resume the specified session. Omit and use `--last` to continue the most recent session.",
521| `--ws-token-file` | `absolute path` | File containing the shared capability token. Required with `--ws-auth capability-token`. |521 },
522 522 {
523Key523 key: "--last",
524 524 type: "boolean",
525`--listen`525 defaultValue: "false",
526 526 description:
527Type / Values527 "Resume the most recent conversation from the current working directory.",
528 528 },
529`stdio:// | ws://IP:PORT`529 {
530 530 key: "--all",
531Details531 type: "boolean",
532 532 defaultValue: "false",
533Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients.533 description:
534 534 "Include sessions outside the current working directory when selecting the most recent session.",
535Key535 },
536 536 {
537`--ws-audience`537 key: "--image, -i",
538 538 type: "path[,path...]",
539Type / Values539 description:
540 540 "Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.",
541`string`541 },
542 542 {
543Details543 key: "PROMPT",
544 544 type: "string | - (read stdin)",
545Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.545 description:
546 546 "Optional follow-up instruction sent immediately after resuming.",
547Key547 },
548 548];
549`--ws-auth`549
550 550export const forkOptions = [
551Type / Values551 {
552 552 key: "SESSION_ID",
553`capability-token | signed-bearer-token`553 type: "uuid",
554 554 description:
555Details555 "Fork the specified session. Omit and use `--last` to fork the most recent session.",
556 556 },
557Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup.557 {
558 558 key: "--last",
559Key559 type: "boolean",
560 560 defaultValue: "false",
561`--ws-issuer`561 description:
562 562 "Skip the picker and fork the most recent conversation automatically.",
563Type / Values563 },
564 564 {
565`string`565 key: "--all",
566 566 type: "boolean",
567Details567 defaultValue: "false",
568 568 description:
569Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.569 "Show sessions beyond the current working directory in the picker.",
570 570 },
571Key571];
572 572
573`--ws-max-clock-skew-seconds`573export const execpolicyOptions = [
574 574 {
575Type / Values575 key: "--rules, -r",
576 576 type: "path (repeatable)",
577`number`577 description:
578 578 "Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.",
579Details579 },
580 580 {
581Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.581 key: "--pretty",
582 582 type: "boolean",
583Key583 defaultValue: "false",
584 584 description: "Pretty-print the JSON result.",
585`--ws-shared-secret-file`585 },
586 586 {
587Type / Values587 key: "COMMAND...",
588 588 type: "var-args",
589`absolute path`589 description: "Command to be checked against the specified policies.",
590 590 },
591Details591];
592 592
593File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.593export const loginOptions = [
594 594 {
595Key595 key: "--with-api-key",
596 596 type: "boolean",
597`--ws-token-file`597 description:
598 598 "Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`).",
599Type / Values599 },
600 600 {
601`absolute path`601 key: "--with-access-token",
602 602 type: "boolean",
603Details603 description:
604 604 "Read an access token from stdin (for example `printenv CODEX_ACCESS_TOKEN | codex login --with-access-token`).",
605File containing the shared capability token. Required with `--ws-auth capability-token`.605 },
606 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.607 key: "--device-auth",
608 608 type: "boolean",
609### `codex app`609 description:
610 610 "Use OAuth device code flow instead of launching a browser window.",
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.611 },
612 612 {
613| Key | Type / Values | Details |613 key: "status subcommand",
614| --- | --- | --- |614 type: "codex login status",
615| `--download-url` | `url` | Advanced override for the Codex desktop installer URL used during install. |615 description:
616| `PATH` | `path` | Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path. |616 "Print the active authentication mode and exit with 0 when logged in.",
617 617 },
618Key618];
619 619
620`--download-url`620export const applyOptions = [
621 621 {
622Type / Values622 key: "TASK_ID",
623 623 type: "string",
624`url`624 description:
625 625 "Identifier of the Codex Cloud task whose diff should be applied.",
626Details626 },
627 627];
628Advanced override for the Codex desktop installer URL used during install.628
629 629export const sandboxMacOptions = [
630Key630 {
631 631 key: "--permissions-profile",
632`PATH`632 type: "NAME",
633 633 description:
634Type / Values634 "Apply a named permissions profile from the active configuration stack.",
635 635 },
636`path`636 {
637 637 key: "--cd, -C",
638Details638 type: "DIR",
639 639 description:
640Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.640 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",
641 641 },
642`codex app` opens an installed Codex Desktop app, or starts the installer when642 {
643the app is missing. On macOS, Codex opens the provided workspace path; on643 key: "--include-managed-config",
644Windows, it prints the path to open after installation.644 type: "boolean",
645 645 defaultValue: "false",
646### `codex debug app-server send-message-v2`646 description:
647 647 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",
648Send one message through app-server's V2 thread/turn flow using the built-in app-server test client.648 },
649 649 {
650| Key | Type / Values | Details |650 key: "--allow-unix-socket",
651| --- | --- | --- |651 type: "path",
652| `USER_MESSAGE` | `string` | Message text sent to app-server through the built-in V2 test-client flow. |652 description:
653 653 "Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths.",
654Key654 },
655 655 {
656`USER_MESSAGE`656 key: "--log-denials",
657 657 type: "boolean",
658Type / Values658 defaultValue: "false",
659 659 description:
660`string`660 "Capture macOS sandbox denials with `log stream` while the command runs and print them after exit.",
661 661 },
662Details662 {
663 663 key: "--config, -c",
664Message text sent to app-server through the built-in V2 test-client flow.664 type: "key=value",
665 665 description:
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.666 "Pass configuration overrides into the sandboxed run (repeatable).",
667 667 },
668### `codex apply`668 {
669 669 key: "COMMAND...",
670Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.670 type: "var-args",
671 671 description:
672| Key | Type / Values | Details |672 "Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.",
673| --- | --- | --- |673 },
674| `TASK_ID` | `string` | Identifier of the Codex Cloud task whose diff should be applied. |674];
675 675
676Key676export const sandboxLinuxOptions = [
677 677 {
678`TASK_ID`678 key: "--permissions-profile",
679 679 type: "NAME",
680Type / Values680 description:
681 681 "Apply a named permissions profile from the active configuration stack.",
682`string`682 },
683 683 {
684Details684 key: "--cd, -C",
685 685 type: "DIR",
686Identifier of the Codex Cloud task whose diff should be applied.686 description:
687 687 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",
688Codex prints the patched files and exits non-zero if `git apply` fails (for example, due to conflicts).688 },
689 689 {
690### `codex cloud`690 key: "--include-managed-config",
691 691 type: "boolean",
692Interact 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.692 defaultValue: "false",
693 693 description:
694| Key | Type / Values | Details |694 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",
695| --- | --- | --- |695 },
696| `--attempts` | `1-4` | Number of assistant attempts (best-of-N) Codex Cloud should run. |696 {
697| `--env` | `ENV_ID` | Target Codex Cloud environment identifier (required). Use `codex cloud` to list options. |697 key: "--config, -c",
698| `QUERY` | `string` | Task prompt. If omitted, Codex prompts interactively for details. |698 type: "key=value",
699 699 description:
700Key700 "Configuration overrides applied before launching the sandbox (repeatable).",
701 701 },
702`--attempts`702 {
703 703 key: "COMMAND...",
704Type / Values704 type: "var-args",
705 705 description:
706`1-4`706 "Command to execute under Landlock + seccomp. Provide the executable after `--`.",
707 707 },
708Details708];
709 709
710Number of assistant attempts (best-of-N) Codex Cloud should run.710export const sandboxWindowsOptions = [
711 711 {
712Key712 key: "--permissions-profile",
713 713 type: "NAME",
714`--env`714 description:
715 715 "Apply a named permissions profile from the active configuration stack.",
716Type / Values716 },
717 717 {
718`ENV_ID`718 key: "--cd, -C",
719 719 type: "DIR",
720Details720 description:
721 721 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",
722Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.722 },
723 723 {
724Key724 key: "--include-managed-config",
725 725 type: "boolean",
726`QUERY`726 defaultValue: "false",
727 727 description:
728Type / Values728 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",
729 729 },
730`string`730 {
731 731 key: "--config, -c",
732Details732 type: "key=value",
733 733 description:
734Task prompt. If omitted, Codex prompts interactively for details.734 "Configuration overrides applied before launching the sandbox (repeatable).",
735 735 },
736Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.736 {
737 737 key: "COMMAND...",
738#### `codex cloud list`738 type: "var-args",
739 739 description:
740List recent cloud tasks with optional filtering and pagination.740 "Command to execute under the native Windows sandbox. Provide the executable after `--`.",
741 741 },
742| Key | Type / Values | Details |742];
743| --- | --- | --- |743
744| `--cursor` | `string` | Pagination cursor returned by a previous request. |744export const completionOptions = [
745| `--env` | `ENV_ID` | Filter tasks by environment identifier. |745 {
746| `--json` | `boolean` | Emit machine-readable JSON instead of plain text. |746 key: "SHELL",
747| `--limit` | `1-20` | Maximum number of tasks to return. |747 type: "bash | zsh | fish | power-shell | elvish",
748 748 defaultValue: "bash",
749Key749 description: "Shell to generate completions for. Output prints to stdout.",
750 750 },
751`--cursor`751];
752 752
753Type / Values753export const cloudExecOptions = [
754 754 {
755`string`755 key: "QUERY",
756 756 type: "string",
757Details757 description:
758 758 "Task prompt. If omitted, Codex prompts interactively for details.",
759Pagination cursor returned by a previous request.759 },
760 760 {
761Key761 key: "--env",
762 762 type: "ENV_ID",
763`--env`763 description:
764 764 "Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.",
765Type / Values765 },
766 766 {
767`ENV_ID`767 key: "--attempts",
768 768 type: "1-4",
769Details769 defaultValue: "1",
770 770 description:
771Filter tasks by environment identifier.771 "Number of assistant attempts (best-of-N) Codex Cloud should run.",
772 772 },
773Key773];
774 774
775`--json`775export const cloudListOptions = [
776 776 {
777Type / Values777 key: "--env",
778 778 type: "ENV_ID",
779`boolean`779 description: "Filter tasks by environment identifier.",
780 780 },
781Details781 {
782 782 key: "--limit",
783Emit machine-readable JSON instead of plain text.783 type: "1-20",
784 784 defaultValue: "20",
785Key785 description: "Maximum number of tasks to return.",
786 786 },
787`--limit`787 {
788 788 key: "--cursor",
789Type / Values789 type: "string",
790 790 description: "Pagination cursor returned by a previous request.",
791`1-20`791 },
792 792 {
793Details793 key: "--json",
794 794 type: "boolean",
795Maximum number of tasks to return.795 defaultValue: "false",
796 796 description: "Emit machine-readable JSON instead of plain text.",
797Plain-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`.797 },
798 798];
799### `codex completion`799
800 800export const mcpCommands = [
801Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.801 {
802 802 key: "list",
803| Key | Type / Values | Details |803 type: "--json",
804| --- | --- | --- |804 description:
805| `SHELL` | `bash | zsh | fish | power-shell | elvish` | Shell to generate completions for. Output prints to stdout. |805 "List configured MCP servers. Add `--json` for machine-readable output.",
806 806 },
807Key807 {
808 808 key: "get <name>",
809`SHELL`809 type: "--json",
810 810 description:
811Type / Values811 "Show a specific server configuration. `--json` prints the raw config entry.",
812 812 },
813`bash | zsh | fish | power-shell | elvish`813 {
814 814 key: "add <name>",
815Details815 type: "-- <command...> | --url <value>",
816 816 description:
817Shell to generate completions for. Output prints to stdout.817 "Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports.",
818 818 },
819### `codex features`819 {
820 820 key: "remove <name>",
821Manage 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.821 description: "Delete a stored MCP server definition.",
822 822 },
823| Key | Type / Values | Details |823 {
824| --- | --- | --- |824 key: "login <name>",
825| `Disable subcommand` | `codex features disable <feature>` | Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided. |825 type: "--scopes scope1,scope2",
826| `Enable subcommand` | `codex features enable <feature>` | Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided. |826 description:
827| `List subcommand` | `codex features list` | Show known feature flags, their maturity stage, and their effective state. |827 "Start an OAuth login for a streamable HTTP server (servers that support OAuth only).",
828 828 },
829Key829 {
830 830 key: "logout <name>",
831`Disable subcommand`831 description:
832 832 "Remove stored OAuth credentials for a streamable HTTP server.",
833Type / Values833 },
834 834];
835`codex features disable <feature>`835
836 836export const mcpAddOptions = [
837Details837 {
838 838 key: "COMMAND...",
839Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.839 type: "stdio transport",
840 840 description:
841Key841 "Executable plus arguments to launch the MCP server. Provide after `--`.",
842 842 },
843`Enable subcommand`843 {
844 844 key: "--env KEY=VALUE",
845Type / Values845 type: "repeatable",
846 846 description:
847`codex features enable <feature>`847 "Environment variable assignments applied when launching a stdio server.",
848 848 },
849Details849 {
850 850 key: "--url",
851Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.851 type: "https://…",
852 852 description:
853Key853 "Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`.",
854 854 },
855`List subcommand`855 {
856 856 key: "--bearer-token-env-var",
857Type / Values857 type: "ENV_VAR",
858 858 description:
859`codex features list`859 "Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.",
860 860 },
861Details861];
862 862
863Show known feature flags, their maturity stage, and their effective state.863export const marketplaceCommands = [
864 864 {
865### `codex exec`865 key: "add <source>",
866 866 type: "[--ref REF] [--sparse PATH]",
867Use `codex exec` (or the short form `codex e`) for scripted or CI-style runs that should finish without human interaction.867 description:
868 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| Key | Type / Values | Details |869 },
870| --- | --- | --- |870 {
871| `--cd, -C` | `path` | Set the workspace root before executing the task. |871 key: "upgrade [marketplace-name]",
872| `--color` | `always | never | auto` | Control ANSI color in stdout. |872 description:
873| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner. |873 "Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided.",
874| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |874 },
875| `--full-auto` | `boolean` | Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals). |875 {
876| `--image, -i` | `path[,path...]` | Attach images to the first message. Repeatable; supports comma-separated lists. |876 key: "remove <marketplace-name>",
877| `--json, --experimental-json` | `boolean` | Print newline-delimited JSON events instead of formatted text. |877 description: "Remove a configured plugin marketplace.",
878| `--model, -m` | `string` | Override the configured model for this run. |878 },
879| `--oss` | `boolean` | Use the local open source provider (requires a running Ollama instance). |879];
880| `--output-last-message, -o` | `path` | Write the assistant’s final message to a file. Useful for downstream scripting. |
881| `--output-schema` | `path` | JSON Schema file describing the expected final response shape. Codex validates tool output against it. |
882| `--profile, -p` | `string` | Select a configuration profile defined in config.toml. |
883| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Sandbox policy for model-generated commands. Defaults to configuration. |
884| `--skip-git-repo-check` | `boolean` | Allow running outside a Git repository (useful for one-off directories). |
885| `-c, --config` | `key=value` | Inline configuration override for the non-interactive run (repeatable). |
886| `PROMPT` | `string | - (read stdin)` | Initial instruction for the task. Use `-` to pipe the prompt from stdin. |
887| `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. |
888
889Key
890
891`--cd, -C`
892
893Type / Values
894
895`path`
896
897Details
898
899Set the workspace root before executing the task.
900
901Key
902
903`--color`
904
905Type / Values
906
907`always | never | auto`
908
909Details
910
911Control ANSI color in stdout.
912
913Key
914
915`--dangerously-bypass-approvals-and-sandbox, --yolo`
916
917Type / Values
918
919`boolean`
920
921Details
922
923Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.
924
925Key
926
927`--ephemeral`
928
929Type / Values
930
931`boolean`
932
933Details
934
935Run without persisting session rollout files to disk.
936
937Key
938
939`--full-auto`
940
941Type / Values
942
943`boolean`
944
945Details
946
947Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals).
948
949Key
950
951`--image, -i`
952
953Type / Values
954
955`path[,path...]`
956
957Details
958
959Attach images to the first message. Repeatable; supports comma-separated lists.
960
961Key
962
963`--json, --experimental-json`
964
965Type / Values
966 880
967`boolean`881## How to read this reference
968
969Details
970
971Print newline-delimited JSON events instead of formatted text.
972
973Key
974
975`--model, -m`
976
977Type / Values
978
979`string`
980
981Details
982
983Override the configured model for this run.
984
985Key
986
987`--oss`
988
989Type / Values
990
991`boolean`
992 882
993Details883This 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.
994 884
995Use 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
888 basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.
996 889
997Key890## Global flags
998 891
999`--output-last-message, -o`892<ConfigTable client:load options={globalFlagOptions} />
1000 893
1001Type / Values894These options apply to the base `codex` command and propagate to each subcommand unless a section below specifies otherwise.
895When you run a subcommand, place global flags after it (for example, `codex exec --oss ...`) so Codex applies them as intended.
1002 896
1003`path`897## Command overview
1004 898
1005Details899The Maturity column uses feature maturity labels such as Experimental, Beta,
900 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to
901 interpret these labels.
1006 902
1007Write the assistant’s final message to a file. Useful for downstream scripting.903<ConfigTable
904 client:load
905 options={commandOverview}
906 secondColumnTitle="Maturity"
907 secondColumnVariant="maturity"
908/>
1008 909
1009Key910## Command details
1010 911
1011`--output-schema`912### `codex` (interactive)
1012 913
1013Type / Values914Running `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`.
1014 915
1015`path`916Use `--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.
1016 917
1017Details918### `codex app-server`
1018 919
1019JSON Schema file describing the expected final response shape. Codex validates tool output against it.920Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.
1020 921
1021Key922<ConfigTable client:load options={appServerOptions} />
1022 923
1023`--profile, -p`924`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://`. Use `--listen unix://` to accept WebSocket handshakes on Codex's default Unix socket, or `--listen unix:///absolute/path.sock` to choose a socket path. If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.
1024 925
1025Type / Values926### `codex remote-control`
1026 927
1027`string`928Ensure the app-server daemon is running with remote-control support enabled.
929Managed remote-control clients and SSH remote workflows use this command; it's
930not a replacement for `codex app-server --listen` when you are building a local
931protocol client.
1028 932
1029Details933### `codex app`
1030 934
1031Select a configuration profile defined in config.toml.935Launch 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.
1032 936
1033Key937<ConfigTable client:load options={appOptions} />
1034 938
1035`--sandbox, -s`939`codex app` opens an installed Codex Desktop app, or starts the installer when
940the app is missing. On macOS, Codex opens the provided workspace path; on
941Windows, it prints the path to open after installation.
1036 942
1037Type / Values943### `codex debug app-server send-message-v2`
1038 944
1039`read-only | workspace-write | danger-full-access`945Send one message through app-server's V2 thread/turn flow using the built-in app-server test client.
1040 946
1041Details947<ConfigTable client:load options={debugAppServerSendMessageV2Options} />
1042 948
1043Sandbox policy for model-generated commands. Defaults to configuration.949This 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.
1044 950
1045Key951### `codex debug models`
1046 952
1047`--skip-git-repo-check`953Print the raw model catalog Codex sees as JSON.
1048 954
1049Type / Values955<ConfigTable client:load options={debugModelsOptions} />
1050 956
1051`boolean`957Use `--bundled` when you want to inspect only the catalog bundled with the current binary, without refreshing from the remote models endpoint.
1052 958
1053Details959### `codex apply`
1054 960
1055Allow running outside a Git repository (useful for one-off directories).961Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.
1056 962
1057Key963<ConfigTable client:load options={applyOptions} />
1058 964
1059`-c, --config`965Codex prints the patched files and exits non-zero if `git apply` fails (for example, due to conflicts).
1060 966
1061Type / Values967### `codex cloud`
1062 968
1063`key=value`969Interact 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.
1064 970
1065Details971<ConfigTable client:load options={cloudExecOptions} />
1066 972
1067Inline configuration override for the non-interactive run (repeatable).973Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.
1068 974
1069Key975#### `codex cloud list`
1070 976
1071`PROMPT`977List recent cloud tasks with optional filtering and pagination.
1072 978
1073Type / Values979<ConfigTable client:load options={cloudListOptions} />
1074 980
1075`string | - (read stdin)`981Plain-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`.
1076 982
1077Details983### `codex completion`
1078 984
1079Initial instruction for the task. Use `-` to pipe the prompt from stdin.985Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.
1080 986
1081Key987<ConfigTable client:load options={completionOptions} />
1082 988
1083`Resume subcommand`989### `codex features`
1084 990
1085Type / Values991Manage 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.
1086 992
1087`codex exec resume [SESSION_ID]`993<ConfigTable client:load options={featuresOptions} />
1088 994
1089Details995### `codex exec`
1090 996
1091Resume 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.997Use `codex exec` (or the short form `codex e`) for scripted or CI-style runs that should finish without human interaction.
1092 998
1093Expand to view all999<ConfigTable client:load options={execOptions} />
1094 1000
1095Codex writes formatted output by default. Add `--json` to receive newline-delimited JSON events (one per state change). The optional `resume` subcommand lets you continue non-interactive tasks. Use `--last` to pick the most recent session from the current working directory, or add `--all` to search across all sessions:1001Codex writes formatted output by default. Add `--json` to receive newline-delimited JSON events (one per state change). The optional `resume` subcommand lets you continue non-interactive tasks. Use `--last` to pick the most recent session from the current working directory, or add `--all` to search across all sessions:
1096 1002
1097| Key | Type / Values | Details |1003<ConfigTable client:load options={execResumeOptions} />
1098| --- | --- | --- |
1099| `--all` | `boolean` | Include sessions outside the current working directory when selecting the most recent session. |
1100| `--image, -i` | `path[,path...]` | Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag. |
1101| `--last` | `boolean` | Resume the most recent conversation from the current working directory. |
1102| `PROMPT` | `string | - (read stdin)` | Optional follow-up instruction sent immediately after resuming. |
1103| `SESSION_ID` | `uuid` | Resume the specified session. Omit and use `--last` to continue the most recent session. |
1104
1105Key
1106
1107`--all`
1108
1109Type / Values
1110
1111`boolean`
1112
1113Details
1114
1115Include sessions outside the current working directory when selecting the most recent session.
1116
1117Key
1118
1119`--image, -i`
1120
1121Type / Values
1122
1123`path[,path...]`
1124
1125Details
1126
1127Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.
1128
1129Key
1130
1131`--last`
1132
1133Type / Values
1134
1135`boolean`
1136
1137Details
1138
1139Resume the most recent conversation from the current working directory.
1140
1141Key
1142
1143`PROMPT`
1144
1145Type / Values
1146
1147`string | - (read stdin)`
1148
1149Details
1150
1151Optional follow-up instruction sent immediately after resuming.
1152
1153Key
1154
1155`SESSION_ID`
1156
1157Type / Values
1158
1159`uuid`
1160
1161Details
1162
1163Resume the specified session. Omit and use `--last` to continue the most recent session.
1164 1004
1165### `codex execpolicy`1005### `codex execpolicy`
1166 1006
1167Check `execpolicy` rule files before you save them. `codex execpolicy check` accepts one or more `--rules` flags (for example, files under `~/.codex/rules`) and emits JSON showing the strictest decision and any matching rules. Add `--pretty` to format the output. The `execpolicy` command is currently in preview.1007Check `execpolicy` rule files before you save them. `codex execpolicy check` accepts one or more `--rules` flags (for example, files under `~/.codex/rules`) and emits JSON showing the strictest decision and any matching rules. Add `--pretty` to format the output. The `execpolicy` command is currently in preview.
1168 1008
1169| Key | Type / Values | Details |1009<ConfigTable client:load options={execpolicyOptions} />
1170| --- | --- | --- |
1171| `--pretty` | `boolean` | Pretty-print the JSON result. |
1172| `--rules, -r` | `path (repeatable)` | Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files. |
1173| `COMMAND...` | `var-args` | Command to be checked against the specified policies. |
1174
1175Key
1176
1177`--pretty`
1178
1179Type / Values
1180
1181`boolean`
1182
1183Details
1184
1185Pretty-print the JSON result.
1186
1187Key
1188
1189`--rules, -r`
1190
1191Type / Values
1192
1193`path (repeatable)`
1194
1195Details
1196
1197Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.
1198
1199Key
1200
1201`COMMAND...`
1202
1203Type / Values
1204
1205`var-args`
1206
1207Details
1208
1209Command to be checked against the specified policies.
1210 1010
1211### `codex login`1011### `codex login`
1212 1012
1213Authenticate the CLI with a ChatGPT account or API key. With no flags, Codex opens a browser for the ChatGPT OAuth flow.1013Authenticate the CLI with a ChatGPT account, API key, or access token. With no flags, Codex opens a browser for the ChatGPT OAuth flow.
1214
1215| Key | Type / Values | Details |
1216| --- | --- | --- |
1217| `--device-auth` | `boolean` | Use OAuth device code flow instead of launching a browser window. |
1218| `--with-api-key` | `boolean` | Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`). |
1219| `status subcommand` | `codex login status` | Print the active authentication mode and exit with 0 when logged in. |
1220
1221Key
1222
1223`--device-auth`
1224
1225Type / Values
1226
1227`boolean`
1228
1229Details
1230
1231Use OAuth device code flow instead of launching a browser window.
1232
1233Key
1234
1235`--with-api-key`
1236
1237Type / Values
1238
1239`boolean`
1240
1241Details
1242 1014
1243Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`).1015<ConfigTable client:load options={loginOptions} />
1244
1245Key
1246
1247`status subcommand`
1248
1249Type / Values
1250
1251`codex login status`
1252
1253Details
1254
1255Print the active authentication mode and exit with 0 when logged in.
1256 1016
1257`codex login status` exits with `0` when credentials are present, which is helpful in automation scripts.1017`codex login status` exits with `0` when credentials are present, which is helpful in automation scripts.
1258 1018
1264 1024
1265Manage Model Context Protocol server entries stored in `~/.codex/config.toml`.1025Manage Model Context Protocol server entries stored in `~/.codex/config.toml`.
1266 1026
1267| Key | Type / Values | Details |1027<ConfigTable client:load options={mcpCommands} />
1268| --- | --- | --- |
1269| `add <name>` | `-- <command...> | --url <value>` | Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports. |
1270| `get <name>` | `--json` | Show a specific server configuration. `--json` prints the raw config entry. |
1271| `list` | `--json` | List configured MCP servers. Add `--json` for machine-readable output. |
1272| `login <name>` | `--scopes scope1,scope2` | Start an OAuth login for a streamable HTTP server (servers that support OAuth only). |
1273| `logout <name>` | | Remove stored OAuth credentials for a streamable HTTP server. |
1274| `remove <name>` | | Delete a stored MCP server definition. |
1275
1276Key
1277
1278`add <name>`
1279
1280Type / Values
1281
1282`-- <command...> | --url <value>`
1283
1284Details
1285
1286Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports.
1287
1288Key
1289
1290`get <name>`
1291
1292Type / Values
1293
1294`--json`
1295
1296Details
1297
1298Show a specific server configuration. `--json` prints the raw config entry.
1299
1300Key
1301
1302`list`
1303
1304Type / Values
1305
1306`--json`
1307
1308Details
1309
1310List configured MCP servers. Add `--json` for machine-readable output.
1311
1312Key
1313
1314`login <name>`
1315
1316Type / Values
1317
1318`--scopes scope1,scope2`
1319
1320Details
1321
1322Start an OAuth login for a streamable HTTP server (servers that support OAuth only).
1323
1324Key
1325
1326`logout <name>`
1327
1328Details
1329
1330Remove stored OAuth credentials for a streamable HTTP server.
1331
1332Key
1333
1334`remove <name>`
1335
1336Details
1337
1338Delete a stored MCP server definition.
1339 1028
1340The `add` subcommand supports both stdio and streamable HTTP transports:1029The `add` subcommand supports both stdio and streamable HTTP transports:
1341 1030
1342| Key | Type / Values | Details |1031<ConfigTable client:load options={mcpAddOptions} />
1343| --- | --- | --- |
1344| `--bearer-token-env-var` | `ENV_VAR` | Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server. |
1345| `--env KEY=VALUE` | `repeatable` | Environment variable assignments applied when launching a stdio server. |
1346| `--url` | `https://…` | Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`. |
1347| `COMMAND...` | `stdio transport` | Executable plus arguments to launch the MCP server. Provide after `--`. |
1348
1349Key
1350
1351`--bearer-token-env-var`
1352
1353Type / Values
1354
1355`ENV_VAR`
1356
1357Details
1358
1359Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.
1360
1361Key
1362
1363`--env KEY=VALUE`
1364
1365Type / Values
1366
1367`repeatable`
1368
1369Details
1370
1371Environment variable assignments applied when launching a stdio server.
1372
1373Key
1374
1375`--url`
1376
1377Type / Values
1378
1379`https://…`
1380
1381Details
1382
1383Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`.
1384
1385Key
1386
1387`COMMAND...`
1388
1389Type / Values
1390
1391`stdio transport`
1392
1393Details
1394
1395Executable plus arguments to launch the MCP server. Provide after `--`.
1396 1032
1397OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).1033OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).
1398 1034
1400 1036
1401Manage plugin marketplace sources that Codex can browse and install from.1037Manage plugin marketplace sources that Codex can browse and install from.
1402 1038
1403| Key | Type / Values | Details |1039<ConfigTable client:load options={marketplaceCommands} />
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 1040
1437`codex plugin marketplace add` accepts GitHub shorthand such as `owner/repo` or1041`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 marketplace1042`owner/repo@ref`, HTTP or HTTPS Git URLs, SSH Git URLs, and local marketplace
1447 1051
1448Continue an interactive session by ID or resume the most recent conversation. `codex resume` scopes `--last` to the current working directory unless you pass `--all`. It accepts the same global flags as `codex`, including model and sandbox overrides.1052Continue an interactive session by ID or resume the most recent conversation. `codex resume` scopes `--last` to the current working directory unless you pass `--all`. It accepts the same global flags as `codex`, including model and sandbox overrides.
1449 1053
1450| Key | Type / Values | Details |1054<ConfigTable client:load options={resumeOptions} />
1451| --- | --- | --- |
1452| `--all` | `boolean` | Include sessions outside the current working directory when selecting the most recent session. |
1453| `--last` | `boolean` | Skip the picker and resume the most recent conversation from the current working directory. |
1454| `SESSION_ID` | `uuid` | Resume the specified session. Omit and use `--last` to continue the most recent session. |
1455
1456Key
1457
1458`--all`
1459
1460Type / Values
1461
1462`boolean`
1463
1464Details
1465
1466Include sessions outside the current working directory when selecting the most recent session.
1467
1468Key
1469
1470`--last`
1471
1472Type / Values
1473
1474`boolean`
1475
1476Details
1477
1478Skip the picker and resume the most recent conversation from the current working directory.
1479
1480Key
1481
1482`SESSION_ID`
1483
1484Type / Values
1485
1486`uuid`
1487
1488Details
1489
1490Resume the specified session. Omit and use `--last` to continue the most recent session.
1491 1055
1492### `codex fork`1056### `codex fork`
1493 1057
1494Fork a previous interactive session into a new thread. By default, `codex fork` opens the session picker; add `--last` to fork your most recent session instead.1058Fork a previous interactive session into a new thread. By default, `codex fork` opens the session picker; add `--last` to fork your most recent session instead.
1495 1059
1496| Key | Type / Values | Details |1060<ConfigTable client:load options={forkOptions} />
1497| --- | --- | --- |
1498| `--all` | `boolean` | Show sessions beyond the current working directory in the picker. |
1499| `--last` | `boolean` | Skip the picker and fork the most recent conversation automatically. |
1500| `SESSION_ID` | `uuid` | Fork the specified session. Omit and use `--last` to fork the most recent session. |
1501
1502Key
1503
1504`--all`
1505
1506Type / Values
1507
1508`boolean`
1509
1510Details
1511
1512Show sessions beyond the current working directory in the picker.
1513
1514Key
1515
1516`--last`
1517
1518Type / Values
1519
1520`boolean`
1521
1522Details
1523
1524Skip the picker and fork the most recent conversation automatically.
1525
1526Key
1527
1528`SESSION_ID`
1529
1530Type / Values
1531
1532`uuid`
1533
1534Details
1535
1536Fork the specified session. Omit and use `--last` to fork the most recent session.
1537 1061
1538### `codex sandbox`1062### `codex sandbox`
1539 1063
1541 1065
1542#### macOS seatbelt1066#### macOS seatbelt
1543 1067
1544| Key | Type / Values | Details |1068<ConfigTable client:load options={sandboxMacOptions} />
1545| --- | --- | --- |
1546| `--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. |
1548| `COMMAND...` | `var-args` | Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded. |
1549
1550Key
1551
1552`--config, -c`
1553
1554Type / Values
1555
1556`key=value`
1557
1558Details
1559
1560Pass configuration overrides into the sandboxed run (repeatable).
1561
1562Key
1563
1564`--full-auto`
1565
1566Type / Values
1567
1568`boolean`
1569
1570Details
1571
1572Grant write access to the current workspace and `/tmp` without approvals.
1573
1574Key
1575
1576`COMMAND...`
1577
1578Type / Values
1579
1580`var-args`
1581
1582Details
1583
1584Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.
1585 1069
1586#### Linux Landlock1070#### Linux Landlock
1587 1071
1588| Key | Type / Values | Details |1072<ConfigTable client:load options={sandboxLinuxOptions} />
1589| --- | --- | --- |
1590| `--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. |
1592| `COMMAND...` | `var-args` | Command to execute under Landlock + seccomp. Provide the executable after `--`. |
1593
1594Key
1595
1596`--config, -c`
1597
1598Type / Values
1599
1600`key=value`
1601
1602Details
1603
1604Configuration overrides applied before launching the sandbox (repeatable).
1605
1606Key
1607
1608`--full-auto`
1609
1610Type / Values
1611
1612`boolean`
1613
1614Details
1615
1616Grant write access to the current workspace and `/tmp` inside the Landlock sandbox.
1617
1618Key
1619
1620`COMMAND...`
1621 1073
1622Type / Values1074#### Windows
1623 1075
1624`var-args`1076<ConfigTable client:load options={sandboxWindowsOptions} />
1625 1077
1626Details1078### `codex update`
1627 1079
1628Command to execute under Landlock + seccomp. Provide the executable after `--`.1080Check 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.
1629 1081
1630## Flag combinations and safety tips1082## Flag combinations and safety tips
1631 1083
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.1084- 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`.1085- 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.1086- Pair `--json` with `--output-last-message` in CI to capture machine-readable progress and a final natural-language summary.
1635 1087
