1# Command line options1# Command line options – Codex CLI
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 2
881## How to read this reference3## How to read this reference
882 4
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.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.
884 6
885The CLI inherits most defaults from <code>~/.codex/config.toml</code>. Any7The CLI inherits most defaults from `~/.codex/config.toml`. Any
886 <code>-c key=value</code> overrides you pass at the command line take8`-c key=value` overrides you pass at the command line take
887 precedence for that invocation. See [Config9precedence for that invocation. See [Config
888 basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.10basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.
889 11
890## Global flags12## Global flags
891 13
892<ConfigTable client:load options={globalFlagOptions} />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
893 239
894These options apply to the base `codex` command and propagate to each subcommand unless a section below specifies otherwise.240These 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.241When you run a subcommand, place global flags after it (for example, `codex exec --oss ...`) so Codex applies them as intended.
896 242
897## Command overview243## Command overview
244
245The Maturity column uses feature maturity labels such as Experimental, Beta,
246and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to
247interpret 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 over stdio, WebSocket, or a Unix socket. |
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, an API key, or an access token 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 remote-control`](https://developers.openai.com/codex/cli/reference#codex-remote-control) | Experimental | Ensure the local app-server daemon is running with remote-control support enabled. |
269| [`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. |
270| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes. |
271| [`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. |
272
273Key
274
275[`codex`](https://developers.openai.com/codex/cli/reference#codex-interactive)
276
277Maturity
278
279Stable
280
281Details
282
283Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.
284
285Key
286
287[`codex app`](https://developers.openai.com/codex/cli/reference#codex-app)
288
289Maturity
290
291Stable
292
293Details
294
295Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open.
296
297Key
298
299[`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server)
300
301Maturity
302
303Experimental
304
305Details
306
307Launch the Codex app server for local development or debugging over stdio, WebSocket, or a Unix socket.
308
309Key
310
311[`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply)
312
313Maturity
314
315Stable
316
317Details
318
319Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.
320
321Key
322
323[`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud)
324
325Maturity
326
327Experimental
328
329Details
330
331Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.
332
333Key
334
335[`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion)
336
337Maturity
338
339Stable
340
341Details
342
343Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.
344
345Key
346
347[`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2)
348
349Maturity
350
351Experimental
352
353Details
354
355Debug app-server by sending a single V2 message through the built-in test client.
356
357Key
358
359[`codex debug models`](https://developers.openai.com/codex/cli/reference#codex-debug-models)
360
361Maturity
362
363Experimental
364
365Details
366
367Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog.
368
369Key
370
371[`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec)
372
373Maturity
374
375Stable
376
377Details
378
379Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.
380
381Key
382
383[`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy)
384
385Maturity
386
387Experimental
388
389Details
390
391Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.
392
393Key
394
395[`codex features`](https://developers.openai.com/codex/cli/reference#codex-features)
396
397Maturity
398
399Stable
400
401Details
402
403List feature flags and persistently enable or disable them in `config.toml`.
404
405Key
406
407[`codex fork`](https://developers.openai.com/codex/cli/reference#codex-fork)
408
409Maturity
410
411Stable
412
413Details
414
415Fork a previous interactive session into a new thread, preserving the original transcript.
416
417Key
418
419[`codex login`](https://developers.openai.com/codex/cli/reference#codex-login)
420
421Maturity
422
423Stable
424
425Details
426
427Authenticate Codex using ChatGPT OAuth, device auth, an API key, or an access token piped over stdin.
428
429Key
430
431[`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout)
432
433Maturity
434
435Stable
436
437Details
438
439Remove stored authentication credentials.
440
441Key
442
443[`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp)
444
445Maturity
446
447Experimental
448
449Details
450
451Manage Model Context Protocol servers (list, add, remove, authenticate).
452
453Key
454
455[`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server)
456
457Maturity
458
459Experimental
460
461Details
462
463Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.
464
465Key
466
467[`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace)
468
469Maturity
470
471Experimental
472
473Details
474
475Add, upgrade, or remove plugin marketplaces from Git or local sources.
476
477Key
478
479[`codex remote-control`](https://developers.openai.com/codex/cli/reference#codex-remote-control)
480
481Maturity
482
483Experimental
484
485Details
486
487Ensure the local app-server daemon is running with remote-control support enabled.
488
489Key
490
491[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)
492
493Maturity
494
495Stable
496
497Details
498
499Continue a previous interactive session by ID or resume the most recent conversation.
500
501Key
502
503[`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox)
504
505Maturity
506
507Experimental
508
509Details
510
511Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes.
512
513Key
514
515[`codex update`](https://developers.openai.com/codex/cli/reference#codex-update)
516
517Maturity
518
519Stable
520
521Details
522
523Check for and apply a Codex CLI update when the installed release supports self-update.
524
525Expand to view all
526
527## Command details
528
529### `codex` (interactive)
530
531Running `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`.
532
533Use `--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.
534
535### `codex app-server`
536
537Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.
538
539| Key | Type / Values | Details |
540| --- | --- | --- |
541| `--analytics-default-enabled` | `boolean` | Defaults analytics to enabled for first-party app-server clients unless the user opts out in config. |
542| `--listen` | `stdio:// | ws://IP:PORT | unix:// | unix://PATH | off` | 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. |
543| `--ws-audience` | `string` | Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |
544| `--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. |
545| `--ws-issuer` | `string` | Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |
546| `--ws-max-clock-skew-seconds` | `number` | Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`. |
547| `--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`. |
548| `--ws-token-file` | `absolute path` | File containing the shared capability token. Required with `--ws-auth capability-token`. |
549
550Key
551
552`--analytics-default-enabled`
553
554Type / Values
555
556`boolean`
557
558Details
559
560Defaults analytics to enabled for first-party app-server clients unless the user opts out in config.
561
562Key
563
564`--listen`
565
566Type / Values
567
568`stdio:// | ws://IP:PORT | unix:// | unix://PATH | off`
569
570Details
571
572Transport 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.
573
574Key
575
576`--ws-audience`
577
578Type / Values
579
580`string`
581
582Details
583
584Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.
585
586Key
587
588`--ws-auth`
589
590Type / Values
591
592`capability-token | signed-bearer-token`
593
594Details
595
596Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup.
597
598Key
599
600`--ws-issuer`
601
602Type / Values
603
604`string`
605
606Details
607
608Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.
609
610Key
611
612`--ws-max-clock-skew-seconds`
613
614Type / Values
615
616`number`
617
618Details
619
620Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.
621
622Key
623
624`--ws-shared-secret-file`
625
626Type / Values
627
628`absolute path`
629
630Details
631
632File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.
633
634Key
635
636`--ws-token-file`
637
638Type / Values
639
640`absolute path`
641
642Details
643
644File containing the shared capability token. Required with `--ws-auth capability-token`.
645
646`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.
647
648### `codex remote-control`
649
650Ensure the app-server daemon is running with remote-control support enabled.
651Managed remote-control clients and SSH remote workflows use this command; it’s
652not a replacement for `codex app-server --listen` when you are building a local
653protocol client.
654
655### `codex app`
656
657Launch 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.
658
659| Key | Type / Values | Details |
660| --- | --- | --- |
661| `--download-url` | `url` | Advanced override for the Codex desktop installer URL used during install. |
662| `PATH` | `path` | Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path. |
663
664Key
665
666`--download-url`
667
668Type / Values
669
670`url`
671
672Details
673
674Advanced override for the Codex desktop installer URL used during install.
675
676Key
677
678`PATH`
679
680Type / Values
681
682`path`
683
684Details
685
686Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.
687
688`codex app` opens an installed Codex Desktop app, or starts the installer when
689the app is missing. On macOS, Codex opens the provided workspace path; on
690Windows, it prints the path to open after installation.
691
692### `codex debug app-server send-message-v2`
693
694Send one message through app-server’s V2 thread/turn flow using the built-in app-server test client.
695
696| Key | Type / Values | Details |
697| --- | --- | --- |
698| `USER_MESSAGE` | `string` | Message text sent to app-server through the built-in V2 test-client flow. |
699
700Key
701
702`USER_MESSAGE`
703
704Type / Values
705
706`string`
707
708Details
709
710Message text sent to app-server through the built-in V2 test-client flow.
711
712This 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.
713
714### `codex debug models`
715
716Print the raw model catalog Codex sees as JSON.
717
718| Key | Type / Values | Details |
719| --- | --- | --- |
720| `--bundled` | `boolean` | Skip refresh and print only the model catalog bundled with the current Codex binary. |
721
722Key
723
724`--bundled`
725
726Type / Values
727
728`boolean`
729
730Details
731
732Skip refresh and print only the model catalog bundled with the current Codex binary.
733
734Use `--bundled` when you want to inspect only the catalog bundled with the current binary, without refreshing from the remote models endpoint.
735
736### `codex apply`
737
738Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.
739
740| Key | Type / Values | Details |
741| --- | --- | --- |
742| `TASK_ID` | `string` | Identifier of the Codex Cloud task whose diff should be applied. |
743
744Key
745
746`TASK_ID`
747
748Type / Values
749
750`string`
751
752Details
753
754Identifier of the Codex Cloud task whose diff should be applied.
755
756Codex prints the patched files and exits non-zero if `git apply` fails (for example, due to conflicts).
757
758### `codex cloud`
759
760Interact 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.
761
762| Key | Type / Values | Details |
763| --- | --- | --- |
764| `--attempts` | `1-4` | Number of assistant attempts (best-of-N) Codex Cloud should run. |
765| `--env` | `ENV_ID` | Target Codex Cloud environment identifier (required). Use `codex cloud` to list options. |
766| `QUERY` | `string` | Task prompt. If omitted, Codex prompts interactively for details. |
767
768Key
769
770`--attempts`
771
772Type / Values
773
774`1-4`
775
776Details
777
778Number of assistant attempts (best-of-N) Codex Cloud should run.
779
780Key
781
782`--env`
783
784Type / Values
785
786`ENV_ID`
787
788Details
789
790Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.
791
792Key
793
794`QUERY`
795
796Type / Values
797
798`string`
799
800Details
801
802Task prompt. If omitted, Codex prompts interactively for details.
803
804Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.
805
806#### `codex cloud list`
807
808List recent cloud tasks with optional filtering and pagination.
809
810| Key | Type / Values | Details |
811| --- | --- | --- |
812| `--cursor` | `string` | Pagination cursor returned by a previous request. |
813| `--env` | `ENV_ID` | Filter tasks by environment identifier. |
814| `--json` | `boolean` | Emit machine-readable JSON instead of plain text. |
815| `--limit` | `1-20` | Maximum number of tasks to return. |
816
817Key
818
819`--cursor`
820
821Type / Values
822
823`string`
824
825Details
826
827Pagination cursor returned by a previous request.
828
829Key
830
831`--env`
832
833Type / Values
834
835`ENV_ID`
836
837Details
838
839Filter tasks by environment identifier.
840
841Key
842
843`--json`
844
845Type / Values
846
847`boolean`
848
849Details
850
851Emit machine-readable JSON instead of plain text.
852
853Key
854
855`--limit`
856
857Type / Values
858
859`1-20`
860
861Details
862
863Maximum number of tasks to return.
864
865Plain-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`.
866
867### `codex completion`
868
869Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.
870
871| Key | Type / Values | Details |
872| --- | --- | --- |
873| `SHELL` | `bash | zsh | fish | power-shell | elvish` | Shell to generate completions for. Output prints to stdout. |
874
875Key
876
877`SHELL`
878
879Type / Values
880
881`bash | zsh | fish | power-shell | elvish`
882
883Details
884
885Shell to generate completions for. Output prints to stdout.
886
887### `codex features`
888
889Manage 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.
890
891| Key | Type / Values | Details |
892| --- | --- | --- |
893| `Disable subcommand` | `codex features disable <feature>` | Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided. |
894| `Enable subcommand` | `codex features enable <feature>` | Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided. |
895| `List subcommand` | `codex features list` | Show known feature flags, their maturity stage, and their effective state. |
896
897Key
898
899`Disable subcommand`
900
901Type / Values
902
903`codex features disable <feature>`
904
905Details
906
907Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.
908
909Key
910
911`Enable subcommand`
912
913Type / Values
914
915`codex features enable <feature>`
916
917Details
918
919Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.
920
921Key
922
923`List subcommand`
924
925Type / Values
926
927`codex features list`
928
929Details
930
931Show known feature flags, their maturity stage, and their effective state.
932
933### `codex exec`
934
935Use `codex exec` (or the short form `codex e`) for scripted or CI-style runs that should finish without human interaction.
936
937| Key | Type / Values | Details |
938| --- | --- | --- |
939| `--cd, -C` | `path` | Set the workspace root before executing the task. |
940| `--color` | `always | never | auto` | Control ANSI color in stdout. |
941| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner. |
942| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |
943| `--full-auto` | `boolean` | Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used. |
944| `--ignore-rules` | `boolean` | Do not load user or project execpolicy `.rules` files for this run. |
945| `--ignore-user-config` | `boolean` | Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`. |
946| `--image, -i` | `path[,path...]` | Attach images to the first message. Repeatable; supports comma-separated lists. |
947| `--json, --experimental-json` | `boolean` | Print newline-delimited JSON events instead of formatted text. |
948| `--model, -m` | `string` | Override the configured model for this run. |
949| `--oss` | `boolean` | Use the local open source provider (requires a running Ollama instance). |
950| `--output-last-message, -o` | `path` | Write the assistant’s final message to a file. Useful for downstream scripting. |
951| `--output-schema` | `path` | JSON Schema file describing the expected final response shape. Codex validates tool output against it. |
952| `--profile, -p` | `string` | Select a configuration profile defined in config.toml. |
953| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Sandbox policy for model-generated commands. Defaults to configuration. |
954| `--skip-git-repo-check` | `boolean` | Allow running outside a Git repository (useful for one-off directories). |
955| `-c, --config` | `key=value` | Inline configuration override for the non-interactive run (repeatable). |
956| `PROMPT` | `string | - (read stdin)` | Initial instruction for the task. Use `-` to pipe the prompt from stdin. |
957| `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. |
958
959Key
960
961`--cd, -C`
962
963Type / Values
964
965`path`
966
967Details
968
969Set the workspace root before executing the task.
970
971Key
972
973`--color`
974
975Type / Values
976
977`always | never | auto`
978
979Details
980
981Control ANSI color in stdout.
982
983Key
984
985`--dangerously-bypass-approvals-and-sandbox, --yolo`
986
987Type / Values
988
989`boolean`
990
991Details
992
993Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.
994
995Key
996
997`--ephemeral`
998
999Type / Values
1000
1001`boolean`
1002
1003Details
1004
1005Run without persisting session rollout files to disk.
1006
1007Key
1008
1009`--full-auto`
1010
1011Type / Values
1012
1013`boolean`
1014
1015Details
1016
1017Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.
1018
1019Key
1020
1021`--ignore-rules`
1022
1023Type / Values
1024
1025`boolean`
1026
1027Details
1028
1029Do not load user or project execpolicy `.rules` files for this run.
1030
1031Key
1032
1033`--ignore-user-config`
1034
1035Type / Values
1036
1037`boolean`
1038
1039Details
1040
1041Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`.
1042
1043Key
1044
1045`--image, -i`
1046
1047Type / Values
1048
1049`path[,path...]`
1050
1051Details
1052
1053Attach images to the first message. Repeatable; supports comma-separated lists.
1054
1055Key
1056
1057`--json, --experimental-json`
1058
1059Type / Values
1060
1061`boolean`
1062
1063Details
1064
1065Print newline-delimited JSON events instead of formatted text.
1066
1067Key
1068
1069`--model, -m`
1070
1071Type / Values
1072
1073`string`
1074
1075Details
1076
1077Override the configured model for this run.
1078
1079Key
1080
1081`--oss`
1082
1083Type / Values
1084
1085`boolean`
1086
1087Details
1088
1089Use the local open source provider (requires a running Ollama instance).
1090
1091Key
1092
1093`--output-last-message, -o`
1094
1095Type / Values
1096
1097`path`
1098
1099Details
1100
1101Write the assistant’s final message to a file. Useful for downstream scripting.
1102
1103Key
1104
1105`--output-schema`
1106
1107Type / Values
1108
1109`path`
1110
1111Details
1112
1113JSON Schema file describing the expected final response shape. Codex validates tool output against it.
1114
1115Key
1116
1117`--profile, -p`
1118
1119Type / Values
1120
1121`string`
1122
1123Details
1124
1125Select a configuration profile defined in config.toml.
1126
1127Key
1128
1129`--sandbox, -s`
1130
1131Type / Values
1132
1133`read-only | workspace-write | danger-full-access`
1134
1135Details
1136
1137Sandbox policy for model-generated commands. Defaults to configuration.
1138
1139Key
1140
1141`--skip-git-repo-check`
1142
1143Type / Values
1144
1145`boolean`
1146
1147Details
1148
1149Allow running outside a Git repository (useful for one-off directories).
1150
1151Key
1152
1153`-c, --config`
1154
1155Type / Values
1156
1157`key=value`
1158
1159Details
1160
1161Inline configuration override for the non-interactive run (repeatable).
1162
1163Key
1164
1165`PROMPT`
1166
1167Type / Values
1168
1169`string | - (read stdin)`
1170
1171Details
1172
1173Initial instruction for the task. Use `-` to pipe the prompt from stdin.
1174
1175Key
1176
1177`Resume subcommand`
1178
1179Type / Values
1180
1181`codex exec resume [SESSION_ID]`
1182
1183Details
1184
1185Resume 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.
1186
1187Expand to view all
1188
1189Codex 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:
1190
1191| Key | Type / Values | Details |
1192| --- | --- | --- |
1193| `--all` | `boolean` | Include sessions outside the current working directory when selecting the most recent session. |
1194| `--image, -i` | `path[,path...]` | Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag. |
1195| `--last` | `boolean` | Resume the most recent conversation from the current working directory. |
1196| `PROMPT` | `string | - (read stdin)` | Optional follow-up instruction sent immediately after resuming. |
1197| `SESSION_ID` | `uuid` | Resume the specified session. Omit and use `--last` to continue the most recent session. |
1198
1199Key
1200
1201`--all`
1202
1203Type / Values
1204
1205`boolean`
1206
1207Details
1208
1209Include sessions outside the current working directory when selecting the most recent session.
1210
1211Key
1212
1213`--image, -i`
1214
1215Type / Values
1216
1217`path[,path...]`
1218
1219Details
1220
1221Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.
1222
1223Key
1224
1225`--last`
1226
1227Type / Values
1228
1229`boolean`
1230
1231Details
1232
1233Resume the most recent conversation from the current working directory.
1234
1235Key
1236
1237`PROMPT`
1238
1239Type / Values
1240
1241`string | - (read stdin)`
1242
1243Details
1244
1245Optional follow-up instruction sent immediately after resuming.
898 1246
899The Maturity column uses feature maturity labels such as Experimental, Beta,1247Key
900 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to
901 interpret these labels.
902 1248
903<ConfigTable1249`SESSION_ID`
904 client:load
905 options={commandOverview}
906 secondColumnTitle="Maturity"
907 secondColumnVariant="maturity"
908/>
909 1250
910## Command details1251Type / Values
911 1252
912### `codex` (interactive)1253`uuid`
913 1254
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`.1255Details
915 1256
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.1257Resume the specified session. Omit and use `--last` to continue the most recent session.
917 1258
918### `codex app-server`1259### `codex execpolicy`
919 1260
920Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.1261Check `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.
921 1262
922<ConfigTable client:load options={appServerOptions} />1263| Key | Type / Values | Details |
1264| --- | --- | --- |
1265| `--pretty` | `boolean` | Pretty-print the JSON result. |
1266| `--rules, -r` | `path (repeatable)` | Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files. |
1267| `COMMAND...` | `var-args` | Command to be checked against the specified policies. |
923 1268
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.1269Key
925 1270
926### `codex remote-control`1271`--pretty`
927 1272
928Ensure the app-server daemon is running with remote-control support enabled.1273Type / Values
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.
932 1274
933### `codex app`1275`boolean`
934 1276
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.1277Details
936 1278
937<ConfigTable client:load options={appOptions} />1279Pretty-print the JSON result.
938 1280
939`codex app` opens an installed Codex Desktop app, or starts the installer when1281Key
940the app is missing. On macOS, Codex opens the provided workspace path; on
941Windows, it prints the path to open after installation.
942 1282
943### `codex debug app-server send-message-v2`1283`--rules, -r`
944 1284
945Send one message through app-server's V2 thread/turn flow using the built-in app-server test client.1285Type / Values
946 1286
947<ConfigTable client:load options={debugAppServerSendMessageV2Options} />1287`path (repeatable)`
948 1288
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.1289Details
950 1290
951### `codex debug models`1291Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.
952 1292
953Print the raw model catalog Codex sees as JSON.1293Key
954 1294
955<ConfigTable client:load options={debugModelsOptions} />1295`COMMAND...`
956 1296
957Use `--bundled` when you want to inspect only the catalog bundled with the current binary, without refreshing from the remote models endpoint.1297Type / Values
958 1298
959### `codex apply`1299`var-args`
960 1300
961Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.1301Details
962 1302
963<ConfigTable client:load options={applyOptions} />1303Command to be checked against the specified policies.
964 1304
965Codex prints the patched files and exits non-zero if `git apply` fails (for example, due to conflicts).1305### `codex login`
966 1306
967### `codex cloud`1307Authenticate the CLI with a ChatGPT account, API key, or access token. With no flags, Codex opens a browser for the ChatGPT OAuth flow.
968 1308
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.1309| Key | Type / Values | Details |
1310| --- | --- | --- |
1311| `--device-auth` | `boolean` | Use OAuth device code flow instead of launching a browser window. |
1312| `--with-access-token` | `boolean` | Read an access token from stdin (for example `printenv CODEX_ACCESS_TOKEN | codex login --with-access-token`). |
1313| `--with-api-key` | `boolean` | Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`). |
1314| `status subcommand` | `codex login status` | Print the active authentication mode and exit with 0 when logged in. |
970 1315
971<ConfigTable client:load options={cloudExecOptions} />1316Key
972 1317
973Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.1318`--device-auth`
974 1319
975#### `codex cloud list`1320Type / Values
976 1321
977List recent cloud tasks with optional filtering and pagination.1322`boolean`
978 1323
979<ConfigTable client:load options={cloudListOptions} />1324Details
980 1325
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`.1326Use OAuth device code flow instead of launching a browser window.
982 1327
983### `codex completion`1328Key
984 1329
985Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.1330`--with-access-token`
986 1331
987<ConfigTable client:load options={completionOptions} />1332Type / Values
988 1333
989### `codex features`1334`boolean`
990 1335
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.1336Details
992 1337
993<ConfigTable client:load options={featuresOptions} />1338Read an access token from stdin (for example `printenv CODEX_ACCESS_TOKEN | codex login --with-access-token`).
994 1339
995### `codex exec`1340Key
996 1341
997Use `codex exec` (or the short form `codex e`) for scripted or CI-style runs that should finish without human interaction.1342`--with-api-key`
998 1343
999<ConfigTable client:load options={execOptions} />1344Type / Values
1000 1345
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:1346`boolean`
1002 1347
1003<ConfigTable client:load options={execResumeOptions} />1348Details
1004 1349
1005### `codex execpolicy`1350Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`).
1006 1351
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.1352Key
1008 1353
1009<ConfigTable client:load options={execpolicyOptions} />1354`status subcommand`
1010 1355
1011### `codex login`1356Type / Values
1012 1357
1013Authenticate the CLI with a ChatGPT account, API key, or access token. With no flags, Codex opens a browser for the ChatGPT OAuth flow.1358`codex login status`
1014 1359
1015<ConfigTable client:load options={loginOptions} />1360Details
1361
1362Print the active authentication mode and exit with 0 when logged in.
1016 1363
1017`codex login status` exits with `0` when credentials are present, which is helpful in automation scripts.1364`codex login status` exits with `0` when credentials are present, which is helpful in automation scripts.
1018 1365
1024 1371
1025Manage Model Context Protocol server entries stored in `~/.codex/config.toml`.1372Manage Model Context Protocol server entries stored in `~/.codex/config.toml`.
1026 1373
1027<ConfigTable client:load options={mcpCommands} />1374| Key | Type / Values | Details |
1375| --- | --- | --- |
1376| `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. |
1377| `get <name>` | `--json` | Show a specific server configuration. `--json` prints the raw config entry. |
1378| `list` | `--json` | List configured MCP servers. Add `--json` for machine-readable output. |
1379| `login <name>` | `--scopes scope1,scope2` | Start an OAuth login for a streamable HTTP server (servers that support OAuth only). |
1380| `logout <name>` | | Remove stored OAuth credentials for a streamable HTTP server. |
1381| `remove <name>` | | Delete a stored MCP server definition. |
1382
1383Key
1384
1385`add <name>`
1386
1387Type / Values
1388
1389`-- <command...> | --url <value>`
1390
1391Details
1392
1393Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports.
1394
1395Key
1396
1397`get <name>`
1398
1399Type / Values
1400
1401`--json`
1402
1403Details
1404
1405Show a specific server configuration. `--json` prints the raw config entry.
1406
1407Key
1408
1409`list`
1410
1411Type / Values
1412
1413`--json`
1414
1415Details
1416
1417List configured MCP servers. Add `--json` for machine-readable output.
1418
1419Key
1420
1421`login <name>`
1422
1423Type / Values
1424
1425`--scopes scope1,scope2`
1426
1427Details
1428
1429Start an OAuth login for a streamable HTTP server (servers that support OAuth only).
1430
1431Key
1432
1433`logout <name>`
1434
1435Details
1436
1437Remove stored OAuth credentials for a streamable HTTP server.
1438
1439Key
1440
1441`remove <name>`
1442
1443Details
1444
1445Delete a stored MCP server definition.
1028 1446
1029The `add` subcommand supports both stdio and streamable HTTP transports:1447The `add` subcommand supports both stdio and streamable HTTP transports:
1030 1448
1031<ConfigTable client:load options={mcpAddOptions} />1449| Key | Type / Values | Details |
1450| --- | --- | --- |
1451| `--bearer-token-env-var` | `ENV_VAR` | Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server. |
1452| `--env KEY=VALUE` | `repeatable` | Environment variable assignments applied when launching a stdio server. |
1453| `--url` | `https://…` | Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`. |
1454| `COMMAND...` | `stdio transport` | Executable plus arguments to launch the MCP server. Provide after `--`. |
1455
1456Key
1457
1458`--bearer-token-env-var`
1459
1460Type / Values
1461
1462`ENV_VAR`
1463
1464Details
1465
1466Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.
1467
1468Key
1469
1470`--env KEY=VALUE`
1471
1472Type / Values
1473
1474`repeatable`
1475
1476Details
1477
1478Environment variable assignments applied when launching a stdio server.
1479
1480Key
1481
1482`--url`
1483
1484Type / Values
1485
1486`https://…`
1487
1488Details
1489
1490Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`.
1491
1492Key
1493
1494`COMMAND...`
1495
1496Type / Values
1497
1498`stdio transport`
1499
1500Details
1501
1502Executable plus arguments to launch the MCP server. Provide after `--`.
1032 1503
1033OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).1504OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).
1034 1505
1036 1507
1037Manage plugin marketplace sources that Codex can browse and install from.1508Manage plugin marketplace sources that Codex can browse and install from.
1038 1509
1039<ConfigTable client:load options={marketplaceCommands} />1510| Key | Type / Values | Details |
1511| --- | --- | --- |
1512| `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. |
1513| `remove <marketplace-name>` | | Remove a configured plugin marketplace. |
1514| `upgrade [marketplace-name]` | | Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided. |
1515
1516Key
1517
1518`add <source>`
1519
1520Type / Values
1521
1522`[--ref REF] [--sparse PATH]`
1523
1524Details
1525
1526Install 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.
1527
1528Key
1529
1530`remove <marketplace-name>`
1531
1532Details
1533
1534Remove a configured plugin marketplace.
1535
1536Key
1537
1538`upgrade [marketplace-name]`
1539
1540Details
1541
1542Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided.
1040 1543
1041`codex plugin marketplace add` accepts GitHub shorthand such as `owner/repo` or1544`codex plugin marketplace add` accepts GitHub shorthand such as `owner/repo` or
1042`owner/repo@ref`, HTTP or HTTPS Git URLs, SSH Git URLs, and local marketplace1545`owner/repo@ref`, HTTP or HTTPS Git URLs, SSH Git URLs, and local marketplace
1051 1554
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.1555Continue 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.
1053 1556
1054<ConfigTable client:load options={resumeOptions} />1557| Key | Type / Values | Details |
1558| --- | --- | --- |
1559| `--all` | `boolean` | Include sessions outside the current working directory when selecting the most recent session. |
1560| `--last` | `boolean` | Skip the picker and resume the most recent conversation from the current working directory. |
1561| `SESSION_ID` | `uuid` | Resume the specified session. Omit and use `--last` to continue the most recent session. |
1562
1563Key
1564
1565`--all`
1566
1567Type / Values
1568
1569`boolean`
1570
1571Details
1572
1573Include sessions outside the current working directory when selecting the most recent session.
1574
1575Key
1576
1577`--last`
1578
1579Type / Values
1580
1581`boolean`
1582
1583Details
1584
1585Skip the picker and resume the most recent conversation from the current working directory.
1586
1587Key
1588
1589`SESSION_ID`
1590
1591Type / Values
1592
1593`uuid`
1594
1595Details
1596
1597Resume the specified session. Omit and use `--last` to continue the most recent session.
1055 1598
1056### `codex fork`1599### `codex fork`
1057 1600
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.1601Fork 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.
1059 1602
1060<ConfigTable client:load options={forkOptions} />1603| Key | Type / Values | Details |
1604| --- | --- | --- |
1605| `--all` | `boolean` | Show sessions beyond the current working directory in the picker. |
1606| `--last` | `boolean` | Skip the picker and fork the most recent conversation automatically. |
1607| `SESSION_ID` | `uuid` | Fork the specified session. Omit and use `--last` to fork the most recent session. |
1608
1609Key
1610
1611`--all`
1612
1613Type / Values
1614
1615`boolean`
1616
1617Details
1618
1619Show sessions beyond the current working directory in the picker.
1620
1621Key
1622
1623`--last`
1624
1625Type / Values
1626
1627`boolean`
1628
1629Details
1630
1631Skip the picker and fork the most recent conversation automatically.
1632
1633Key
1634
1635`SESSION_ID`
1636
1637Type / Values
1638
1639`uuid`
1640
1641Details
1642
1643Fork the specified session. Omit and use `--last` to fork the most recent session.
1061 1644
1062### `codex sandbox`1645### `codex sandbox`
1063 1646
1065 1648
1066#### macOS seatbelt1649#### macOS seatbelt
1067 1650
1068<ConfigTable client:load options={sandboxMacOptions} />1651| Key | Type / Values | Details |
1652| --- | --- | --- |
1653| `--allow-unix-socket` | `path` | Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths. |
1654| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |
1655| `--config, -c` | `key=value` | Pass configuration overrides into the sandboxed run (repeatable). |
1656| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |
1657| `--log-denials` | `boolean` | Capture macOS sandbox denials with `log stream` while the command runs and print them after exit. |
1658| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |
1659| `COMMAND...` | `var-args` | Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded. |
1660
1661Key
1662
1663`--allow-unix-socket`
1664
1665Type / Values
1666
1667`path`
1668
1669Details
1670
1671Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths.
1672
1673Key
1674
1675`--cd, -C`
1676
1677Type / Values
1678
1679`DIR`
1680
1681Details
1682
1683Working directory used for profile resolution and command execution. Requires `--permissions-profile`.
1684
1685Key
1686
1687`--config, -c`
1688
1689Type / Values
1690
1691`key=value`
1692
1693Details
1694
1695Pass configuration overrides into the sandboxed run (repeatable).
1696
1697Key
1698
1699`--include-managed-config`
1700
1701Type / Values
1702
1703`boolean`
1704
1705Details
1706
1707Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.
1708
1709Key
1710
1711`--log-denials`
1712
1713Type / Values
1714
1715`boolean`
1716
1717Details
1718
1719Capture macOS sandbox denials with `log stream` while the command runs and print them after exit.
1720
1721Key
1722
1723`--permissions-profile`
1724
1725Type / Values
1726
1727`NAME`
1728
1729Details
1730
1731Apply a named permissions profile from the active configuration stack.
1732
1733Key
1734
1735`COMMAND...`
1736
1737Type / Values
1738
1739`var-args`
1740
1741Details
1742
1743Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.
1069 1744
1070#### Linux Landlock1745#### Linux Landlock
1071 1746
1072<ConfigTable client:load options={sandboxLinuxOptions} />1747| Key | Type / Values | Details |
1748| --- | --- | --- |
1749| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |
1750| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |
1751| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |
1752| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |
1753| `COMMAND...` | `var-args` | Command to execute under Landlock + seccomp. Provide the executable after `--`. |
1754
1755Key
1756
1757`--cd, -C`
1758
1759Type / Values
1760
1761`DIR`
1762
1763Details
1764
1765Working directory used for profile resolution and command execution. Requires `--permissions-profile`.
1766
1767Key
1768
1769`--config, -c`
1770
1771Type / Values
1772
1773`key=value`
1774
1775Details
1776
1777Configuration overrides applied before launching the sandbox (repeatable).
1778
1779Key
1780
1781`--include-managed-config`
1782
1783Type / Values
1784
1785`boolean`
1786
1787Details
1788
1789Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.
1790
1791Key
1792
1793`--permissions-profile`
1794
1795Type / Values
1796
1797`NAME`
1798
1799Details
1800
1801Apply a named permissions profile from the active configuration stack.
1802
1803Key
1804
1805`COMMAND...`
1806
1807Type / Values
1808
1809`var-args`
1810
1811Details
1812
1813Command to execute under Landlock + seccomp. Provide the executable after `--`.
1073 1814
1074#### Windows1815#### Windows
1075 1816
1076<ConfigTable client:load options={sandboxWindowsOptions} />1817| Key | Type / Values | Details |
1818| --- | --- | --- |
1819| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |
1820| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |
1821| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |
1822| `--permissions-profile` | `NAME` | Apply a named permissions profile from the active configuration stack. |
1823| `COMMAND...` | `var-args` | Command to execute under the native Windows sandbox. Provide the executable after `--`. |
1824
1825Key
1826
1827`--cd, -C`
1828
1829Type / Values
1830
1831`DIR`
1832
1833Details
1834
1835Working directory used for profile resolution and command execution. Requires `--permissions-profile`.
1836
1837Key
1838
1839`--config, -c`
1840
1841Type / Values
1842
1843`key=value`
1844
1845Details
1846
1847Configuration overrides applied before launching the sandbox (repeatable).
1848
1849Key
1850
1851`--include-managed-config`
1852
1853Type / Values
1854
1855`boolean`
1856
1857Details
1858
1859Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.
1860
1861Key
1862
1863`--permissions-profile`
1864
1865Type / Values
1866
1867`NAME`
1868
1869Details
1870
1871Apply a named permissions profile from the active configuration stack.
1872
1873Key
1874
1875`COMMAND...`
1876
1877Type / Values
1878
1879`var-args`
1880
1881Details
1882
1883Command to execute under the native Windows sandbox. Provide the executable after `--`.
1077 1884
1078### `codex update`1885### `codex update`
1079 1886
