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