1# Command line options – Codex CLI1# Command line options
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 "Layer `$CODEX_HOME/profile-name.config.toml` on top of the base user config.",
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: "--dangerously-bypass-hook-trust",
56 type: "boolean",
57 defaultValue: "false",
58 description:
59 "Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources.",
60 },
61 {
62 key: "--cd, -C",
63 type: "path",
64 description:
65 "Set the working directory for the agent before it starts processing your request.",
66 },
67 {
68 key: "--search",
69 type: "boolean",
70 defaultValue: "false",
71 description:
72 'Enable live web search (sets `web_search = "live"` instead of the default `"cached"`).',
73 },
74 {
75 key: "--add-dir",
76 type: "path",
77 description:
78 "Grant additional directories write access alongside the main workspace. Repeat for multiple paths.",
79 },
80 {
81 key: "--no-alt-screen",
82 type: "boolean",
83 defaultValue: "false",
84 description:
85 "Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run).",
86 },
87 {
88 key: "--remote",
89 type: "ws://host:port | wss://host:port | unix:// | unix://PATH",
90 description:
91 "Connect the interactive TUI to a remote app-server endpoint over WebSocket or a Unix socket. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode.",
92 },
93 {
94 key: "--remote-auth-token-env",
95 type: "ENV_VAR",
96 description:
97 "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 local-only `ws://` URLs.",
98 },
99 {
100 key: "--strict-config",
101 type: "boolean",
102 defaultValue: "false",
103 description:
104 "Error when `config.toml` contains fields this Codex version does not recognize. Supported by runtime commands such as `codex`, `exec`, `review`, `resume`, `fork`, `app-server`, `mcp-server`, and `exec-server`.",
105 },
106 {
107 key: "--enable",
108 type: "feature",
109 description:
110 "Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable.",
111 },
112 {
113 key: "--disable",
114 type: "feature",
115 description:
116 "Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable.",
117 },
118 {
119 key: "--config, -c",
120 type: "key=value",
121 description:
122 "Override configuration values. Values parse as TOML if possible; otherwise the literal string is used.",
123 },
124];
125
126export const commandOverview = [
127 {
128 key: "codex",
129 href: "/codex/cli/reference#codex-interactive",
130 type: "stable",
131 description:
132 "Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.",
133 },
134 {
135 key: "codex app-server",
136 href: "/codex/cli/reference#codex-app-server",
137 type: "experimental",
138 description:
139 "Launch the Codex app server for local development or debugging over stdio, WebSocket, or a Unix socket.",
140 },
141 {
142 key: "codex remote-control",
143 href: "/codex/cli/reference#codex-remote-control",
144 type: "experimental",
145 description:
146 "Ensure the local app-server daemon is running with remote-control support enabled.",
147 },
148 {
149 key: "codex app",
150 href: "/codex/cli/reference#codex-app",
151 type: "stable",
152 description:
153 "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.",
154 },
155 {
156 key: "codex debug app-server send-message-v2",
157 href: "/codex/cli/reference#codex-debug-app-server-send-message-v2",
158 type: "experimental",
159 description:
160 "Debug app-server by sending a single V2 message through the built-in test client.",
161 },
162 {
163 key: "codex debug models",
164 href: "/codex/cli/reference#codex-debug-models",
165 type: "experimental",
166 description:
167 "Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog.",
168 },
169 {
170 key: "codex apply",
171 href: "/codex/cli/reference#codex-apply",
172 type: "stable",
173 description:
174 "Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.",
175 },
176 {
177 key: "codex archive",
178 href: "/codex/cli/reference#codex-archive-and-codex-unarchive",
179 type: "stable",
180 description:
181 "Archive a saved interactive session by session ID or session name.",
182 },
183 {
184 key: "codex cloud",
185 href: "/codex/cli/reference#codex-cloud",
186 type: "experimental",
187 description:
188 "Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.",
189 },
190 {
191 key: "codex completion",
192 href: "/codex/cli/reference#codex-completion",
193 type: "stable",
194 description:
195 "Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.",
196 },
197 {
198 key: "codex doctor",
199 href: "/codex/cli/reference#codex-doctor",
200 type: "stable",
201 description:
202 "Generate a diagnostic report for local installation, config, auth, runtime, Git, terminal, app-server, and thread inventory issues.",
203 },
204 {
205 key: "codex features",
206 href: "/codex/cli/reference#codex-features",
207 type: "stable",
208 description:
209 "List feature flags and persistently enable or disable them in `config.toml`.",
210 },
211 {
212 key: "codex exec",
213 href: "/codex/cli/reference#codex-exec",
214 type: "stable",
215 description:
216 "Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.",
217 },
218 {
219 key: "codex execpolicy",
220 href: "/codex/cli/reference#codex-execpolicy",
221 type: "experimental",
222 description:
223 "Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.",
224 },
225 {
226 key: "codex login",
227 href: "/codex/cli/reference#codex-login",
228 type: "stable",
229 description:
230 "Authenticate Codex using ChatGPT OAuth, device auth, an API key, or an access token piped over stdin.",
231 },
232 {
233 key: "codex logout",
234 href: "/codex/cli/reference#codex-logout",
235 type: "stable",
236 description: "Remove stored authentication credentials.",
237 },
238 {
239 key: "codex mcp",
240 href: "/codex/cli/reference#codex-mcp",
241 type: "experimental",
242 description:
243 "Manage Model Context Protocol servers (list, add, remove, authenticate).",
244 },
245 {
246 key: "codex plugin marketplace",
247 href: "/codex/cli/reference#codex-plugin-marketplace",
248 type: "experimental",
249 description:
250 "Add, list, upgrade, or remove plugin marketplaces from Git or local sources.",
251 },
252 {
253 key: "codex plugin",
254 href: "/codex/cli/reference#codex-plugin",
255 type: "experimental",
256 description:
257 "Install, list, and remove plugins from configured marketplace sources.",
258 },
259 {
260 key: "codex mcp-server",
261 href: "/codex/cli/reference#codex-mcp-server",
262 type: "experimental",
263 description:
264 "Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.",
265 },
266 {
267 key: "codex resume",
268 href: "/codex/cli/reference#codex-resume",
269 type: "stable",
270 description:
271 "Continue a previous interactive session by ID or resume the most recent conversation.",
272 },
273 {
274 key: "codex fork",
275 href: "/codex/cli/reference#codex-fork",
276 type: "stable",
277 description:
278 "Fork a previous interactive session into a new thread, preserving the original transcript.",
279 },
280 {
281 key: "codex sandbox",
282 href: "/codex/cli/reference#codex-sandbox",
283 type: "experimental",
284 description:
285 "Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes.",
286 },
287 {
288 key: "codex update",
289 href: "/codex/cli/reference#codex-update",
290 type: "stable",
291 description:
292 "Check for and apply a Codex CLI update when the installed release supports self-update.",
293 },
294 {
295 key: "codex unarchive",
296 href: "/codex/cli/reference#codex-archive-and-codex-unarchive",
297 type: "stable",
298 description:
299 "Restore an archived interactive session by session ID or session name.",
300 },
301];
302
303export const execOptions = [
304 {
305 key: "PROMPT",
306 type: "string | - (read stdin)",
307 description:
308 "Initial instruction for the task. Use `-` to pipe the prompt from stdin.",
309 },
310 {
311 key: "--image, -i",
312 type: "path[,path...]",
313 description:
314 "Attach images to the first message. Repeatable; supports comma-separated lists.",
315 },
316 {
317 key: "--model, -m",
318 type: "string",
319 description: "Override the configured model for this run.",
320 },
321 {
322 key: "--oss",
323 type: "boolean",
324 defaultValue: "false",
325 description:
326 "Use the local open source provider (requires a running Ollama instance).",
327 },
328 {
329 key: "--sandbox, -s",
330 type: "read-only | workspace-write | danger-full-access",
331 description:
332 "Sandbox policy for model-generated commands. Defaults to configuration.",
333 },
334 {
335 key: "--profile, -p",
336 type: "string",
337 description:
338 "Layer `$CODEX_HOME/profile-name.config.toml` on top of the base user config.",
339 },
340 {
341 key: "--full-auto",
342 type: "boolean",
343 defaultValue: "false",
344 description:
345 "Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.",
346 },
347 {
348 key: "--dangerously-bypass-approvals-and-sandbox, --yolo",
349 type: "boolean",
350 defaultValue: "false",
351 description:
352 "Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.",
353 },
354 {
355 key: "--dangerously-bypass-hook-trust",
356 type: "boolean",
357 defaultValue: "false",
358 description:
359 "Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources.",
360 },
361 {
362 key: "--cd, -C",
363 type: "path",
364 description: "Set the workspace root before executing the task.",
365 },
366 {
367 key: "--skip-git-repo-check",
368 type: "boolean",
369 defaultValue: "false",
370 description:
371 "Allow running outside a Git repository (useful for one-off directories).",
372 },
373 {
374 key: "--ephemeral",
375 type: "boolean",
376 defaultValue: "false",
377 description: "Run without persisting session rollout files to disk.",
378 },
379 {
380 key: "--ignore-user-config",
381 type: "boolean",
382 defaultValue: "false",
383 description:
384 "Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`.",
385 },
386 {
387 key: "--ignore-rules",
388 type: "boolean",
389 defaultValue: "false",
390 description:
391 "Do not load user or project execpolicy `.rules` files for this run.",
392 },
393 {
394 key: "--output-schema",
395 type: "path",
396 description:
397 "JSON Schema file describing the expected final response shape. Codex validates tool output against it.",
398 },
399 {
400 key: "--color",
401 type: "always | never | auto",
402 defaultValue: "auto",
403 description: "Control ANSI color in stdout.",
404 },
405 {
406 key: "--json, --experimental-json",
407 type: "boolean",
408 defaultValue: "false",
409 description:
410 "Print newline-delimited JSON events instead of formatted text.",
411 },
412 {
413 key: "--output-last-message, -o",
414 type: "path",
415 description:
416 "Write the assistant’s final message to a file. Useful for downstream scripting.",
417 },
418 {
419 key: "Resume subcommand",
420 type: "codex exec resume [SESSION_ID]",
421 description:
422 "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.",
423 },
424 {
425 key: "-c, --config",
426 type: "key=value",
427 description:
428 "Inline configuration override for the non-interactive run (repeatable).",
429 },
430];
431
432export const appServerOptions = [
433 {
434 key: "--stdio",
435 type: "boolean",
436 defaultValue: "false",
437 description:
438 "Use stdio transport. Equivalent to `--listen stdio://` and mutually exclusive with `--listen`.",
439 },
440 {
441 key: "--listen",
442 type: "stdio:// | ws://IP:PORT | unix:// | unix://PATH | off",
443 defaultValue: "stdio://",
444 description:
445 "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.",
446 },
447 {
448 key: "--ws-auth",
449 type: "capability-token | signed-bearer-token",
450 description:
451 "Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup.",
452 },
453 {
454 key: "--ws-token-file",
455 type: "absolute path",
456 description:
457 "File containing the shared capability token. Use with `--ws-auth capability-token` unless you provide `--ws-token-sha256` instead.",
458 },
459 {
460 key: "--ws-token-sha256",
461 type: "hexadecimal SHA-256 digest",
462 description:
463 "Expected SHA-256 digest for capability-token authentication. Use instead of `--ws-token-file` when the client token comes from another source.",
464 },
465 {
466 key: "--ws-shared-secret-file",
467 type: "absolute path",
468 description:
469 "File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.",
470 },
471 {
472 key: "--ws-issuer",
473 type: "string",
474 description:
475 "Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.",
476 },
477 {
478 key: "--ws-audience",
479 type: "string",
480 description:
481 "Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.",
482 },
483 {
484 key: "--ws-max-clock-skew-seconds",
485 type: "number",
486 defaultValue: "30",
487 description:
488 "Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.",
489 },
490 {
491 key: "--analytics-default-enabled",
492 type: "boolean",
493 defaultValue: "false",
494 description:
495 "Defaults analytics to enabled for first-party app-server clients unless the user opts out in config.",
496 },
497];
498
499export const appOptions = [
500 {
501 key: "PATH",
502 type: "path",
503 defaultValue: ".",
504 description:
505 "Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.",
506 },
507 {
508 key: "--download-url",
509 type: "url",
510 description:
511 "Advanced override for the Codex desktop installer URL used during install.",
512 },
513];
514
515export const debugAppServerSendMessageV2Options = [
516 {
517 key: "USER_MESSAGE",
518 type: "string",
519 description:
520 "Message text sent to app-server through the built-in V2 test-client flow.",
521 },
522];
523
524export const debugModelsOptions = [
525 {
526 key: "--bundled",
527 type: "boolean",
528 defaultValue: "false",
529 description:
530 "Skip refresh and print only the model catalog bundled with the current Codex binary.",
531 },
532];
533
534export const doctorOptions = [
535 {
536 key: "--json",
537 type: "boolean",
538 defaultValue: "false",
539 description: "Emit a redacted machine-readable support report.",
540 },
541 {
542 key: "--summary",
543 type: "boolean",
544 defaultValue: "false",
545 description: "Show grouped check rows and the final count summary only.",
546 },
547 {
548 key: "--all",
549 type: "boolean",
550 defaultValue: "false",
551 description: "Expand long lists in the detailed human-readable report.",
552 },
553 {
554 key: "--no-color",
555 type: "boolean",
556 defaultValue: "false",
557 description: "Disable ANSI color in human-readable output.",
558 },
559 {
560 key: "--ascii",
561 type: "boolean",
562 defaultValue: "false",
563 description:
564 "Use ASCII status labels and separators in human-readable output.",
565 },
566];
567
568export const resumeOptions = [
569 {
570 key: "SESSION_ID",
571 type: "uuid",
572 description:
573 "Resume the specified session. Omit and use `--last` to continue the most recent session.",
574 },
575 {
576 key: "--last",
577 type: "boolean",
578 defaultValue: "false",
579 description:
580 "Skip the picker and resume the most recent conversation from the current working directory.",
581 },
582 {
583 key: "--all",
584 type: "boolean",
585 defaultValue: "false",
586 description:
587 "Include sessions outside the current working directory when selecting the most recent session.",
588 },
589];
590
591export const featuresOptions = [
592 {
593 key: "List subcommand",
594 type: "codex features list",
595 description:
596 "Show known feature flags, their maturity stage, and their effective state.",
597 },
598 {
599 key: "Enable subcommand",
600 type: "codex features enable <feature>",
601 description:
602 "Persistently enable a feature flag in `$CODEX_HOME/config.toml`.",
603 },
604 {
605 key: "Disable subcommand",
606 type: "codex features disable <feature>",
607 description:
608 "Persistently disable a feature flag in `$CODEX_HOME/config.toml`.",
609 },
610];
611
612export const execResumeOptions = [
613 {
614 key: "SESSION_ID",
615 type: "uuid",
616 description:
617 "Resume the specified session. Omit and use `--last` to continue the most recent session.",
618 },
619 {
620 key: "--last",
621 type: "boolean",
622 defaultValue: "false",
623 description:
624 "Resume the most recent conversation from the current working directory.",
625 },
626 {
627 key: "--all",
628 type: "boolean",
629 defaultValue: "false",
630 description:
631 "Include sessions outside the current working directory when selecting the most recent session.",
632 },
633 {
634 key: "--image, -i",
635 type: "path[,path...]",
636 description:
637 "Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.",
638 },
639 {
640 key: "PROMPT",
641 type: "string | - (read stdin)",
642 description:
643 "Optional follow-up instruction sent immediately after resuming.",
644 },
645];
646
647export const forkOptions = [
648 {
649 key: "SESSION_ID",
650 type: "uuid",
651 description:
652 "Fork the specified session. Omit and use `--last` to fork the most recent session.",
653 },
654 {
655 key: "--last",
656 type: "boolean",
657 defaultValue: "false",
658 description:
659 "Skip the picker and fork the most recent conversation automatically.",
660 },
661 {
662 key: "--all",
663 type: "boolean",
664 defaultValue: "false",
665 description:
666 "Show sessions beyond the current working directory in the picker.",
667 },
668];
669
670export const execpolicyOptions = [
671 {
672 key: "--rules, -r",
673 type: "path (repeatable)",
674 description:
675 "Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.",
676 },
677 {
678 key: "--pretty",
679 type: "boolean",
680 defaultValue: "false",
681 description: "Pretty-print the JSON result.",
682 },
683 {
684 key: "COMMAND...",
685 type: "var-args",
686 description: "Command to be checked against the specified policies.",
687 },
688];
689
690export const loginOptions = [
691 {
692 key: "--with-api-key",
693 type: "boolean",
694 description:
695 "Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`).",
696 },
697 {
698 key: "--with-access-token",
699 type: "boolean",
700 description:
701 "Read an access token from stdin (for example `printenv CODEX_ACCESS_TOKEN | codex login --with-access-token`).",
702 },
703 {
704 key: "--device-auth",
705 type: "boolean",
706 description:
707 "Use OAuth device code flow instead of launching a browser window.",
708 },
709 {
710 key: "status subcommand",
711 type: "codex login status",
712 description:
713 "Print the active authentication mode and exit with 0 when logged in.",
714 },
715];
716
717export const applyOptions = [
718 {
719 key: "TASK_ID",
720 type: "string",
721 description:
722 "Identifier of the Codex Cloud task whose diff should be applied.",
723 },
724];
725
726export const sandboxMacOptions = [
727 {
728 key: "--profile, -p",
729 type: "NAME",
730 description:
731 "Layer `$CODEX_HOME/NAME.config.toml` on top of the base user config.",
732 },
733 {
734 key: "--permissions-profile, -P",
735 type: "NAME",
736 description:
737 "Apply a named permissions profile from the active configuration stack.",
738 },
739 {
740 key: "--cd, -C",
741 type: "DIR",
742 description:
743 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",
744 },
745 {
746 key: "--include-managed-config",
747 type: "boolean",
748 defaultValue: "false",
749 description:
750 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",
751 },
752 {
753 key: "--allow-unix-socket",
754 type: "path",
755 description:
756 "Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths.",
757 },
758 {
759 key: "--log-denials",
760 type: "boolean",
761 defaultValue: "false",
762 description:
763 "Capture macOS sandbox denials with `log stream` while the command runs and print them after exit.",
764 },
765 {
766 key: "--config, -c",
767 type: "key=value",
768 description:
769 "Pass configuration overrides into the sandboxed run (repeatable).",
770 },
771 {
772 key: "COMMAND...",
773 type: "var-args",
774 description:
775 "Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.",
776 },
777];
778
779export const sandboxLinuxOptions = [
780 {
781 key: "--profile, -p",
782 type: "NAME",
783 description:
784 "Layer `$CODEX_HOME/NAME.config.toml` on top of the base user config.",
785 },
786 {
787 key: "--permissions-profile, -P",
788 type: "NAME",
789 description:
790 "Apply a named permissions profile from the active configuration stack.",
791 },
792 {
793 key: "--cd, -C",
794 type: "DIR",
795 description:
796 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",
797 },
798 {
799 key: "--include-managed-config",
800 type: "boolean",
801 defaultValue: "false",
802 description:
803 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",
804 },
805 {
806 key: "--config, -c",
807 type: "key=value",
808 description:
809 "Configuration overrides applied before launching the sandbox (repeatable).",
810 },
811 {
812 key: "COMMAND...",
813 type: "var-args",
814 description:
815 "Command to execute under Landlock + seccomp. Provide the executable after `--`.",
816 },
817];
818
819export const sandboxWindowsOptions = [
820 {
821 key: "--profile, -p",
822 type: "NAME",
823 description:
824 "Layer `$CODEX_HOME/NAME.config.toml` on top of the base user config.",
825 },
826 {
827 key: "--permissions-profile, -P",
828 type: "NAME",
829 description:
830 "Apply a named permissions profile from the active configuration stack.",
831 },
832 {
833 key: "--cd, -C",
834 type: "DIR",
835 description:
836 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",
837 },
838 {
839 key: "--include-managed-config",
840 type: "boolean",
841 defaultValue: "false",
842 description:
843 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",
844 },
845 {
846 key: "--config, -c",
847 type: "key=value",
848 description:
849 "Configuration overrides applied before launching the sandbox (repeatable).",
850 },
851 {
852 key: "COMMAND...",
853 type: "var-args",
854 description:
855 "Command to execute under the native Windows sandbox. Provide the executable after `--`.",
856 },
857];
858
859export const completionOptions = [
860 {
861 key: "SHELL",
862 type: "bash | zsh | fish | power-shell | elvish",
863 defaultValue: "bash",
864 description: "Shell to generate completions for. Output prints to stdout.",
865 },
866];
867
868export const cloudExecOptions = [
869 {
870 key: "QUERY",
871 type: "string",
872 description:
873 "Task prompt. If omitted, Codex prompts interactively for details.",
874 },
875 {
876 key: "--env",
877 type: "ENV_ID",
878 description:
879 "Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.",
880 },
881 {
882 key: "--attempts",
883 type: "1-4",
884 defaultValue: "1",
885 description:
886 "Number of assistant attempts (best-of-N) Codex Cloud should run.",
887 },
888];
889
890export const cloudListOptions = [
891 {
892 key: "--env",
893 type: "ENV_ID",
894 description: "Filter tasks by environment identifier.",
895 },
896 {
897 key: "--limit",
898 type: "1-20",
899 defaultValue: "20",
900 description: "Maximum number of tasks to return.",
901 },
902 {
903 key: "--cursor",
904 type: "string",
905 description: "Pagination cursor returned by a previous request.",
906 },
907 {
908 key: "--json",
909 type: "boolean",
910 defaultValue: "false",
911 description: "Emit machine-readable JSON instead of plain text.",
912 },
913];
914
915export const mcpCommands = [
916 {
917 key: "list",
918 type: "--json",
919 description:
920 "List configured MCP servers. Add `--json` for machine-readable output.",
921 },
922 {
923 key: "get <name>",
924 type: "--json",
925 description:
926 "Show a specific server configuration. `--json` prints the raw config entry.",
927 },
928 {
929 key: "add <name>",
930 type: "-- <command...> | --url <value>",
931 description:
932 "Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports.",
933 },
934 {
935 key: "remove <name>",
936 description: "Delete a stored MCP server definition.",
937 },
938 {
939 key: "login <name>",
940 type: "--scopes scope1,scope2",
941 description:
942 "Start an OAuth login for a streamable HTTP server (servers that support OAuth only).",
943 },
944 {
945 key: "logout <name>",
946 description:
947 "Remove stored OAuth credentials for a streamable HTTP server.",
948 },
949];
950
951export const mcpAddOptions = [
952 {
953 key: "COMMAND...",
954 type: "stdio transport",
955 description:
956 "Executable plus arguments to launch the MCP server. Provide after `--`.",
957 },
958 {
959 key: "--env KEY=VALUE",
960 type: "repeatable",
961 description:
962 "Environment variable assignments applied when launching a stdio server.",
963 },
964 {
965 key: "--url",
966 type: "https://…",
967 description:
968 "Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`.",
969 },
970 {
971 key: "--bearer-token-env-var",
972 type: "ENV_VAR",
973 description:
974 "Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.",
975 },
976 {
977 key: "--oauth-client-id",
978 type: "CLIENT_ID",
979 description:
980 "OAuth client identifier for a streamable HTTP MCP server. Requires `--url`.",
981 },
982 {
983 key: "--oauth-resource",
984 type: "RESOURCE",
985 description:
986 "OAuth resource parameter to include during login for a streamable HTTP MCP server. Requires `--url`.",
987 },
988];
989
990export const marketplaceCommands = [
991 {
992 key: "add <source>",
993 type: "[--ref REF] [--sparse PATH] [--json]",
994 description:
995 "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.",
996 },
997 {
998 key: "list",
999 type: "[--json]",
1000 description:
1001 "Show plugin marketplaces Codex is currently considering and the root path for each marketplace.",
1002 },
1003 {
1004 key: "upgrade [marketplace-name]",
1005 type: "[--json]",
1006 description:
1007 "Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided.",
1008 },
1009 {
1010 key: "remove <marketplace-name>",
1011 type: "[--json]",
1012 description: "Remove a configured plugin marketplace.",
1013 },
1014];
1015
1016export const pluginCommands = [
1017 {
1018 key: "add <plugin[@marketplace]>",
1019 type: "[--marketplace, -m NAME] [--json]",
1020 description:
1021 "Install a plugin from a configured marketplace. Use `--marketplace` or `-m` when the plugin argument omits `@marketplace`.",
1022 },
1023 {
1024 key: "list",
1025 type: "[--marketplace, -m NAME] [--available --json] [--json]",
1026 description:
1027 "List installed plugins. With `--json`, output has `installed` and `available` arrays; `--available` includes uninstalled marketplace plugins and requires `--json`.",
1028 },
1029 {
1030 key: "remove <plugin[@marketplace]>",
1031 type: "[--marketplace, -m NAME] [--json]",
1032 description:
1033 "Remove an installed plugin from local config and cache. Use `--json` for automation-friendly output.",
1034 },
1035 {
1036 key: "marketplace",
1037 description:
1038 "Manage configured marketplace sources. See `codex plugin marketplace` below.",
1039 },
1040];
1041
1042export const archiveOptions = [
1043 {
1044 key: "SESSION",
1045 type: "session ID | session name",
1046 description:
1047 "Saved session to archive or restore. Session IDs take precedence over session names.",
1048 },
1049 {
1050 key: "--remote",
1051 type: "ws://host:port | wss://host:port | unix:// | unix://PATH",
1052 description:
1053 "Connect to a remote app-server endpoint before changing archive state.",
1054 },
1055 {
1056 key: "--remote-auth-token-env",
1057 type: "ENV_VAR",
1058 description:
1059 "Read a bearer token from this environment variable when `--remote` requires authentication.",
1060 },
1061];
2 1062
3## How to read this reference1063## How to read this reference
4 1064
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.1065This 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 1066
7The CLI inherits most defaults from `~/.codex/config.toml`. Any1067The CLI inherits most defaults from <code>~/.codex/config.toml</code>. Any
8`-c key=value` overrides you pass at the command line take1068 <code>-c key=value</code> overrides you pass at the command line take
9precedence for that invocation. See [Config1069 precedence for that invocation. See [Config
10basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.1070 basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.
11 1071
12## Global flags1072## Global flags
13 1073
14| Key | Type / Values | Details |1074<ConfigTable client:load options={globalFlagOptions} />
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 TOML 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| `--dangerously-bypass-hook-trust` | `boolean` | Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources. |
22| `--disable` | `feature` | Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable. |
23| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |
24| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |
25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |
26| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |
27| `--oss` | `boolean` | Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running. |
28| `--profile, -p` | `string` | Layer `$CODEX_HOME/profile-name.config.toml` on top of the base user config. |
29| `--remote` | `ws://host:port | wss://host:port | unix:// | unix://PATH` | Connect the interactive TUI to a remote app-server endpoint over WebSocket or a Unix socket. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode. |
30| `--remote-auth-token-env` | `ENV_VAR` | Read a bearer token from this environment variable and send it when connecting with `--remote`. Requires `--remote`; tokens are only sent over `wss://` URLs or local-only `ws://` URLs. |
31| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Select the sandbox policy for model-generated shell commands. |
32| `--search` | `boolean` | Enable live web search (sets `web_search = "live"` instead of the default `"cached"`). |
33| `--strict-config` | `boolean` | Error when `config.toml` contains fields this Codex version does not recognize. Supported by runtime commands such as `codex`, `exec`, `review`, `resume`, `fork`, `app-server`, `mcp-server`, and `exec-server`. |
34| `PROMPT` | `string` | Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message. |
35 1075
36Key1076These options apply to the base `codex` command. Most propagate to commands;
37 1077see the notes above or the relevant command help for exceptions. For propagated
38`--add-dir`1078flags, follow the relevant command help. For example, `codex exec --oss ...`
39 1079applies `--oss` to `exec`.
40Type / Values
41
42`path`
43
44Details
45
46Grant additional directories write access alongside the main workspace. Repeat for multiple paths.
47
48Key
49
50`--ask-for-approval, -a`
51
52Type / Values
53
54`untrusted | on-request | never`
55
56Details
57
58Control 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.
59
60Key
61
62`--cd, -C`
63
64Type / Values
65
66`path`
67
68Details
69
70Set the working directory for the agent before it starts processing your request.
71
72Key
73
74`--config, -c`
75
76Type / Values
77
78`key=value`
79
80Details
81
82Override configuration values. Values parse as TOML if possible; otherwise the literal string is used.
83
84Key
85
86`--dangerously-bypass-approvals-and-sandbox, --yolo`
87
88Type / Values
89
90`boolean`
91
92Details
93
94Run every command without approvals or sandboxing. Only use inside an externally hardened environment.
95
96Key
97
98`--dangerously-bypass-hook-trust`
99
100Type / Values
101
102`boolean`
103
104Details
105
106Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources.
107
108Key
109
110`--disable`
111
112Type / Values
113
114`feature`
115
116Details
117
118Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable.
119
120Key
121
122`--enable`
123
124Type / Values
125
126`feature`
127
128Details
129
130Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable.
131
132Key
133
134`--image, -i`
135
136Type / Values
137
138`path[,path...]`
139
140Details
141
142Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.
143
144Key
145
146`--model, -m`
147
148Type / Values
149
150`string`
151
152Details
153
154Override the model set in configuration (for example `gpt-5.4`).
155
156Key
157
158`--no-alt-screen`
159
160Type / Values
161
162`boolean`
163
164Details
165
166Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run).
167
168Key
169
170`--oss`
171
172Type / Values
173
174`boolean`
175
176Details
177
178Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running.
179
180Key
181
182`--profile, -p`
183
184Type / Values
185
186`string`
187
188Details
189
190Layer `$CODEX_HOME/profile-name.config.toml` on top of the base user config.
191
192Key
193
194`--remote`
195
196Type / Values
197
198`ws://host:port | wss://host:port | unix:// | unix://PATH`
199
200Details
201
202Connect the interactive TUI to a remote app-server endpoint over WebSocket or a Unix socket. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode.
203
204Key
205
206`--remote-auth-token-env`
207
208Type / Values
209
210`ENV_VAR`
211
212Details
213
214Read a bearer token from this environment variable and send it when connecting with `--remote`. Requires `--remote`; tokens are only sent over `wss://` URLs or local-only `ws://` URLs.
215
216Key
217
218`--sandbox, -s`
219
220Type / Values
221
222`read-only | workspace-write | danger-full-access`
223
224Details
225
226Select the sandbox policy for model-generated shell commands.
227
228Key
229
230`--search`
231
232Type / Values
233
234`boolean`
235
236Details
237
238Enable live web search (sets `web_search = "live"` instead of the default `"cached"`).
239
240Key
241
242`--strict-config`
243
244Type / Values
245
246`boolean`
247
248Details
249
250Error when `config.toml` contains fields this Codex version does not recognize. Supported by runtime commands such as `codex`, `exec`, `review`, `resume`, `fork`, `app-server`, `mcp-server`, and `exec-server`.
251
252Key
253
254`PROMPT`
255
256Type / Values
257
258`string`
259
260Details
261
262Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.
263
264Expand to view all
265
266These options apply to the base `codex` command. Most propagate to commands;
267see the notes above or the relevant command help for exceptions. For propagated
268flags, follow the relevant command help. For example, `codex exec --oss ...`
269applies `--oss` to `exec`.
270
271## Command overview
272
273The Maturity column uses feature maturity labels such as Experimental, Beta,
274and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to
275interpret these labels.
276
277| Key | Maturity | Details |
278| --- | --- | --- |
279| [`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. |
280| [`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. |
281| [`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. |
282| [`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`. |
283| [`codex archive`](https://developers.openai.com/codex/cli/reference#codex-archive-and-codex-unarchive) | Stable | Archive a saved interactive session by session ID or session name. |
284| [`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`. |
285| [`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion) | Stable | Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell. |
286| [`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. |
287| [`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. |
288| [`codex doctor`](https://developers.openai.com/codex/cli/reference#codex-doctor) | Stable | Generate a diagnostic report for local installation, config, auth, runtime, Git, terminal, app-server, and thread inventory issues. |
289| [`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. |
290| [`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. |
291| [`codex features`](https://developers.openai.com/codex/cli/reference#codex-features) | Stable | List feature flags and persistently enable or disable them in `config.toml`. |
292| [`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. |
293| [`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. |
294| [`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout) | Stable | Remove stored authentication credentials. |
295| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |
296| [`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. |
297| [`codex plugin`](https://developers.openai.com/codex/cli/reference#codex-plugin) | Experimental | Install, list, and remove plugins from configured marketplace sources. |
298| [`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace) | Experimental | Add, list, upgrade, or remove plugin marketplaces from Git or local sources. |
299| [`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. |
300| [`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. |
301| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes. |
302| [`codex unarchive`](https://developers.openai.com/codex/cli/reference#codex-archive-and-codex-unarchive) | Stable | Restore an archived interactive session by session ID or session name. |
303| [`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. |
304
305Key
306
307[`codex`](https://developers.openai.com/codex/cli/reference#codex-interactive)
308
309Maturity
310
311Stable
312
313Details
314
315Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.
316
317Key
318
319[`codex app`](https://developers.openai.com/codex/cli/reference#codex-app)
320
321Maturity
322
323Stable
324
325Details
326
327Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open.
328
329Key
330
331[`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server)
332
333Maturity
334
335Experimental
336
337Details
338
339Launch the Codex app server for local development or debugging over stdio, WebSocket, or a Unix socket.
340
341Key
342
343[`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply)
344
345Maturity
346
347Stable
348
349Details
350
351Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.
352
353Key
354
355[`codex archive`](https://developers.openai.com/codex/cli/reference#codex-archive-and-codex-unarchive)
356
357Maturity
358
359Stable
360
361Details
362
363Archive a saved interactive session by session ID or session name.
364
365Key
366
367[`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud)
368
369Maturity
370
371Experimental
372
373Details
374
375Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.
376
377Key
378
379[`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion)
380
381Maturity
382
383Stable
384
385Details
386
387Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.
388
389Key
390
391[`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2)
392
393Maturity
394
395Experimental
396
397Details
398
399Debug app-server by sending a single V2 message through the built-in test client.
400
401Key
402
403[`codex debug models`](https://developers.openai.com/codex/cli/reference#codex-debug-models)
404
405Maturity
406
407Experimental
408
409Details
410
411Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog.
412
413Key
414
415[`codex doctor`](https://developers.openai.com/codex/cli/reference#codex-doctor)
416
417Maturity
418
419Stable
420
421Details
422
423Generate a diagnostic report for local installation, config, auth, runtime, Git, terminal, app-server, and thread inventory issues.
424
425Key
426
427[`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec)
428
429Maturity
430
431Stable
432
433Details
434
435Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.
436
437Key
438
439[`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy)
440
441Maturity
442
443Experimental
444
445Details
446
447Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.
448
449Key
450
451[`codex features`](https://developers.openai.com/codex/cli/reference#codex-features)
452
453Maturity
454
455Stable
456
457Details
458
459List feature flags and persistently enable or disable them in `config.toml`.
460
461Key
462
463[`codex fork`](https://developers.openai.com/codex/cli/reference#codex-fork)
464
465Maturity
466
467Stable
468
469Details
470
471Fork a previous interactive session into a new thread, preserving the original transcript.
472
473Key
474
475[`codex login`](https://developers.openai.com/codex/cli/reference#codex-login)
476
477Maturity
478
479Stable
480
481Details
482
483Authenticate Codex using ChatGPT OAuth, device auth, an API key, or an access token piped over stdin.
484
485Key
486
487[`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout)
488
489Maturity
490
491Stable
492
493Details
494
495Remove stored authentication credentials.
496
497Key
498
499[`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp)
500
501Maturity
502
503Experimental
504
505Details
506
507Manage Model Context Protocol servers (list, add, remove, authenticate).
508
509Key
510
511[`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server)
512
513Maturity
514
515Experimental
516
517Details
518
519Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.
520
521Key
522
523[`codex plugin`](https://developers.openai.com/codex/cli/reference#codex-plugin)
524
525Maturity
526
527Experimental
528
529Details
530
531Install, list, and remove plugins from configured marketplace sources.
532
533Key
534
535[`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace)
536
537Maturity
538
539Experimental
540
541Details
542
543Add, list, upgrade, or remove plugin marketplaces from Git or local sources.
544
545Key
546
547[`codex remote-control`](https://developers.openai.com/codex/cli/reference#codex-remote-control)
548
549Maturity
550
551Experimental
552
553Details
554
555Ensure the local app-server daemon is running with remote-control support enabled.
556
557Key
558
559[`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume)
560
561Maturity
562
563Stable
564
565Details
566
567Continue a previous interactive session by ID or resume the most recent conversation.
568
569Key
570
571[`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox)
572
573Maturity
574
575Experimental
576
577Details
578
579Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes.
580
581Key
582
583[`codex unarchive`](https://developers.openai.com/codex/cli/reference#codex-archive-and-codex-unarchive)
584
585Maturity
586
587Stable
588
589Details
590
591Restore an archived interactive session by session ID or session name.
592
593Key
594
595[`codex update`](https://developers.openai.com/codex/cli/reference#codex-update)
596
597Maturity
598
599Stable
600
601Details
602
603Check for and apply a Codex CLI update when the installed release supports self-update.
604
605Expand to view all
606
607## Command details
608
609### `codex` (interactive)
610
611Running `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`.
612
613Use `--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`. For a local Unix socket, use `--remote unix://` for the default socket or `--remote unix://PATH` for an explicit path. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication.
614
615### `codex app-server`
616
617Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.
618
619| Key | Type / Values | Details |
620| --- | --- | --- |
621| `--analytics-default-enabled` | `boolean` | Defaults analytics to enabled for first-party app-server clients unless the user opts out in config. |
622| `--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. |
623| `--stdio` | `boolean` | Use stdio transport. Equivalent to `--listen stdio://` and mutually exclusive with `--listen`. |
624| `--ws-audience` | `string` | Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |
625| `--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. |
626| `--ws-issuer` | `string` | Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |
627| `--ws-max-clock-skew-seconds` | `number` | Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`. |
628| `--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`. |
629| `--ws-token-file` | `absolute path` | File containing the shared capability token. Use with `--ws-auth capability-token` unless you provide `--ws-token-sha256` instead. |
630| `--ws-token-sha256` | `hexadecimal SHA-256 digest` | Expected SHA-256 digest for capability-token authentication. Use instead of `--ws-token-file` when the client token comes from another source. |
631
632Key
633
634`--analytics-default-enabled`
635
636Type / Values
637
638`boolean`
639
640Details
641
642Defaults analytics to enabled for first-party app-server clients unless the user opts out in config.
643
644Key
645
646`--listen`
647
648Type / Values
649
650`stdio:// | ws://IP:PORT | unix:// | unix://PATH | off`
651
652Details
653
654Transport 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.
655
656Key
657
658`--stdio`
659
660Type / Values
661
662`boolean`
663
664Details
665
666Use stdio transport. Equivalent to `--listen stdio://` and mutually exclusive with `--listen`.
667
668Key
669
670`--ws-audience`
671
672Type / Values
673
674`string`
675
676Details
677
678Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.
679
680Key
681
682`--ws-auth`
683
684Type / Values
685
686`capability-token | signed-bearer-token`
687
688Details
689
690Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup.
691
692Key
693
694`--ws-issuer`
695
696Type / Values
697
698`string`
699
700Details
701
702Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.
703
704Key
705
706`--ws-max-clock-skew-seconds`
707
708Type / Values
709
710`number`
711
712Details
713
714Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.
715
716Key
717
718`--ws-shared-secret-file`
719
720Type / Values
721
722`absolute path`
723
724Details
725
726File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.
727
728Key
729
730`--ws-token-file`
731
732Type / Values
733
734`absolute path`
735
736Details
737
738File containing the shared capability token. Use with `--ws-auth capability-token` unless you provide `--ws-token-sha256` instead.
739
740Key
741
742`--ws-token-sha256`
743
744Type / Values
745
746`hexadecimal SHA-256 digest`
747
748Details
749
750Expected SHA-256 digest for capability-token authentication. Use instead of `--ws-token-file` when the client token comes from another source.
751
752`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior, and `codex app-server --stdio` is an alias for that transport. `--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.
753
754### `codex remote-control`
755
756Ensure the app-server daemon is running with remote-control support enabled.
757Managed remote-control clients and SSH remote workflows use this command; it’s
758not a replacement for `codex app-server --listen` when you are building a local
759protocol client.
760
761### `codex app`
762
763Launch 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.
764
765| Key | Type / Values | Details |
766| --- | --- | --- |
767| `--download-url` | `url` | Advanced override for the Codex desktop installer URL used during install. |
768| `PATH` | `path` | Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path. |
769
770Key
771
772`--download-url`
773
774Type / Values
775
776`url`
777
778Details
779
780Advanced override for the Codex desktop installer URL used during install.
781
782Key
783
784`PATH`
785
786Type / Values
787
788`path`
789
790Details
791
792Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.
793
794`codex app` opens an installed Codex Desktop app, or starts the installer when
795the app is missing. On macOS, Codex opens the provided workspace path; on
796Windows, it prints the path to open after installation.
797
798### `codex debug app-server send-message-v2`
799
800Send one message through app-server’s V2 thread/turn flow using the built-in app-server test client.
801
802| Key | Type / Values | Details |
803| --- | --- | --- |
804| `USER_MESSAGE` | `string` | Message text sent to app-server through the built-in V2 test-client flow. |
805
806Key
807
808`USER_MESSAGE`
809
810Type / Values
811
812`string`
813
814Details
815
816Message text sent to app-server through the built-in V2 test-client flow.
817
818This 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.
819
820### `codex debug models`
821
822Print the raw model catalog Codex sees as JSON.
823
824| Key | Type / Values | Details |
825| --- | --- | --- |
826| `--bundled` | `boolean` | Skip refresh and print only the model catalog bundled with the current Codex binary. |
827
828Key
829
830`--bundled`
831
832Type / Values
833
834`boolean`
835
836Details
837
838Skip refresh and print only the model catalog bundled with the current Codex binary.
839
840Use `--bundled` when you want to inspect only the catalog bundled with the current binary, without refreshing from the remote models endpoint.
841
842### `codex apply`
843
844Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.
845
846| Key | Type / Values | Details |
847| --- | --- | --- |
848| `TASK_ID` | `string` | Identifier of the Codex Cloud task whose diff should be applied. |
849
850Key
851
852`TASK_ID`
853
854Type / Values
855
856`string`
857
858Details
859
860Identifier of the Codex Cloud task whose diff should be applied.
861
862Codex prints the patched files and exits non-zero if `git apply` fails (for example, due to conflicts).
863
864### `codex archive` and `codex unarchive`
865
866Archive or restore a saved interactive session by session ID or session name.
867Use these commands when you want to clean up the session picker without deleting
868the transcript. Session IDs take precedence over session names.
869
870```
871codex archive <SESSION>
872codex unarchive <SESSION>
873```
874
875| Key | Type / Values | Details |
876| --- | --- | --- |
877| `--remote` | `ws://host:port | wss://host:port | unix:// | unix://PATH` | Connect to a remote app-server endpoint before changing archive state. |
878| `--remote-auth-token-env` | `ENV_VAR` | Read a bearer token from this environment variable when `--remote` requires authentication. |
879| `SESSION` | `session ID | session name` | Saved session to archive or restore. Session IDs take precedence over session names. |
880
881Key
882
883`--remote`
884
885Type / Values
886
887`ws://host:port | wss://host:port | unix:// | unix://PATH`
888
889Details
890
891Connect to a remote app-server endpoint before changing archive state.
892
893Key
894
895`--remote-auth-token-env`
896
897Type / Values
898
899`ENV_VAR`
900
901Details
902
903Read a bearer token from this environment variable when `--remote` requires authentication.
904
905Key
906
907`SESSION`
908
909Type / Values
910
911`session ID | session name`
912
913Details
914
915Saved session to archive or restore. Session IDs take precedence over session names.
916
917### `codex cloud`
918
919Interact 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.
920
921| Key | Type / Values | Details |
922| --- | --- | --- |
923| `--attempts` | `1-4` | Number of assistant attempts (best-of-N) Codex Cloud should run. |
924| `--env` | `ENV_ID` | Target Codex Cloud environment identifier (required). Use `codex cloud` to list options. |
925| `QUERY` | `string` | Task prompt. If omitted, Codex prompts interactively for details. |
926
927Key
928
929`--attempts`
930
931Type / Values
932
933`1-4`
934
935Details
936
937Number of assistant attempts (best-of-N) Codex Cloud should run.
938
939Key
940
941`--env`
942
943Type / Values
944
945`ENV_ID`
946
947Details
948
949Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.
950
951Key
952
953`QUERY`
954
955Type / Values
956
957`string`
958
959Details
960
961Task prompt. If omitted, Codex prompts interactively for details.
962
963Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.
964
965#### `codex cloud list`
966
967List recent cloud tasks with optional filtering and pagination.
968
969| Key | Type / Values | Details |
970| --- | --- | --- |
971| `--cursor` | `string` | Pagination cursor returned by a previous request. |
972| `--env` | `ENV_ID` | Filter tasks by environment identifier. |
973| `--json` | `boolean` | Emit machine-readable JSON instead of plain text. |
974| `--limit` | `1-20` | Maximum number of tasks to return. |
975
976Key
977
978`--cursor`
979
980Type / Values
981
982`string`
983
984Details
985
986Pagination cursor returned by a previous request.
987
988Key
989
990`--env`
991
992Type / Values
993
994`ENV_ID`
995
996Details
997
998Filter tasks by environment identifier.
999
1000Key
1001
1002`--json`
1003
1004Type / Values
1005
1006`boolean`
1007
1008Details
1009
1010Emit machine-readable JSON instead of plain text.
1011
1012Key
1013
1014`--limit`
1015
1016Type / Values
1017
1018`1-20`
1019
1020Details
1021
1022Maximum number of tasks to return.
1023
1024Plain-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`.
1025
1026### `codex completion`
1027
1028Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.
1029
1030| Key | Type / Values | Details |
1031| --- | --- | --- |
1032| `SHELL` | `bash | zsh | fish | power-shell | elvish` | Shell to generate completions for. Output prints to stdout. |
1033
1034Key
1035
1036`SHELL`
1037
1038Type / Values
1039
1040`bash | zsh | fish | power-shell | elvish`
1041
1042Details
1043
1044Shell to generate completions for. Output prints to stdout.
1045
1046### `codex doctor`
1047
1048Generate a local diagnostic report before filing a support issue or
1049while investigating a broken Codex installation. The report checks installation,
1050configuration, authentication, runtime, Git, terminal, app-server, and thread
1051inventory health.
1052
1053| Key | Type / Values | Details |
1054| --- | --- | --- |
1055| `--all` | `boolean` | Expand long lists in the detailed human-readable report. |
1056| `--ascii` | `boolean` | Use ASCII status labels and separators in human-readable output. |
1057| `--json` | `boolean` | Emit a redacted machine-readable support report. |
1058| `--no-color` | `boolean` | Disable ANSI color in human-readable output. |
1059| `--summary` | `boolean` | Show grouped check rows and the final count summary only. |
1060
1061Key
1062
1063`--all`
1064
1065Type / Values
1066
1067`boolean`
1068
1069Details
1070
1071Expand long lists in the detailed human-readable report.
1072
1073Key
1074
1075`--ascii`
1076
1077Type / Values
1078
1079`boolean`
1080
1081Details
1082
1083Use ASCII status labels and separators in human-readable output.
1084
1085Key
1086
1087`--json`
1088
1089Type / Values
1090
1091`boolean`
1092
1093Details
1094
1095Emit a redacted machine-readable support report.
1096
1097Key
1098
1099`--no-color`
1100
1101Type / Values
1102
1103`boolean`
1104
1105Details
1106
1107Disable ANSI color in human-readable output.
1108
1109Key
1110
1111`--summary`
1112
1113Type / Values
1114
1115`boolean`
1116
1117Details
1118
1119Show grouped check rows and the final count summary only.
1120
1121### `codex features`
1122
1123Manage feature flags stored in `$CODEX_HOME/config.toml`. The `enable` and
1124`disable` commands persist changes so they apply to future sessions. The
1125`features` subcommand doesn’t accept `--profile`.
1126
1127| Key | Type / Values | Details |
1128| --- | --- | --- |
1129| `Disable subcommand` | `codex features disable <feature>` | Persistently disable a feature flag in `$CODEX_HOME/config.toml`. |
1130| `Enable subcommand` | `codex features enable <feature>` | Persistently enable a feature flag in `$CODEX_HOME/config.toml`. |
1131| `List subcommand` | `codex features list` | Show known feature flags, their maturity stage, and their effective state. |
1132
1133Key
1134
1135`Disable subcommand`
1136
1137Type / Values
1138
1139`codex features disable <feature>`
1140
1141Details
1142
1143Persistently disable a feature flag in `$CODEX_HOME/config.toml`.
1144
1145Key
1146
1147`Enable subcommand`
1148
1149Type / Values
1150
1151`codex features enable <feature>`
1152
1153Details
1154
1155Persistently enable a feature flag in `$CODEX_HOME/config.toml`.
1156
1157Key
1158
1159`List subcommand`
1160
1161Type / Values
1162
1163`codex features list`
1164
1165Details
1166
1167Show known feature flags, their maturity stage, and their effective state.
1168
1169### `codex exec`
1170
1171Use `codex exec` (or the short form `codex e`) for scripted or CI-style runs that should finish without human interaction.
1172
1173| Key | Type / Values | Details |
1174| --- | --- | --- |
1175| `--cd, -C` | `path` | Set the workspace root before executing the task. |
1176| `--color` | `always | never | auto` | Control ANSI color in stdout. |
1177| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner. |
1178| `--dangerously-bypass-hook-trust` | `boolean` | Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources. |
1179| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |
1180| `--full-auto` | `boolean` | Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used. |
1181| `--ignore-rules` | `boolean` | Do not load user or project execpolicy `.rules` files for this run. |
1182| `--ignore-user-config` | `boolean` | Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`. |
1183| `--image, -i` | `path[,path...]` | Attach images to the first message. Repeatable; supports comma-separated lists. |
1184| `--json, --experimental-json` | `boolean` | Print newline-delimited JSON events instead of formatted text. |
1185| `--model, -m` | `string` | Override the configured model for this run. |
1186| `--oss` | `boolean` | Use the local open source provider (requires a running Ollama instance). |
1187| `--output-last-message, -o` | `path` | Write the assistant’s final message to a file. Useful for downstream scripting. |
1188| `--output-schema` | `path` | JSON Schema file describing the expected final response shape. Codex validates tool output against it. |
1189| `--profile, -p` | `string` | Layer `$CODEX_HOME/profile-name.config.toml` on top of the base user config. |
1190| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Sandbox policy for model-generated commands. Defaults to configuration. |
1191| `--skip-git-repo-check` | `boolean` | Allow running outside a Git repository (useful for one-off directories). |
1192| `-c, --config` | `key=value` | Inline configuration override for the non-interactive run (repeatable). |
1193| `PROMPT` | `string | - (read stdin)` | Initial instruction for the task. Use `-` to pipe the prompt from stdin. |
1194| `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. |
1195
1196Key
1197
1198`--cd, -C`
1199
1200Type / Values
1201
1202`path`
1203
1204Details
1205
1206Set the workspace root before executing the task.
1207
1208Key
1209
1210`--color`
1211
1212Type / Values
1213
1214`always | never | auto`
1215
1216Details
1217
1218Control ANSI color in stdout.
1219
1220Key
1221
1222`--dangerously-bypass-approvals-and-sandbox, --yolo`
1223
1224Type / Values
1225
1226`boolean`
1227
1228Details
1229
1230Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.
1231
1232Key
1233
1234`--dangerously-bypass-hook-trust`
1235
1236Type / Values
1237
1238`boolean`
1239
1240Details
1241
1242Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources.
1243
1244Key
1245
1246`--ephemeral`
1247
1248Type / Values
1249
1250`boolean`
1251
1252Details
1253
1254Run without persisting session rollout files to disk.
1255
1256Key
1257
1258`--full-auto`
1259
1260Type / Values
1261
1262`boolean`
1263
1264Details
1265
1266Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.
1267
1268Key
1269
1270`--ignore-rules`
1271
1272Type / Values
1273
1274`boolean`
1275
1276Details
1277
1278Do not load user or project execpolicy `.rules` files for this run.
1279
1280Key
1281
1282`--ignore-user-config`
1283
1284Type / Values
1285
1286`boolean`
1287
1288Details
1289
1290Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`.
1291
1292Key
1293
1294`--image, -i`
1295
1296Type / Values
1297
1298`path[,path...]`
1299
1300Details
1301
1302Attach images to the first message. Repeatable; supports comma-separated lists.
1303
1304Key
1305
1306`--json, --experimental-json`
1307
1308Type / Values
1309
1310`boolean`
1311
1312Details
1313
1314Print newline-delimited JSON events instead of formatted text.
1315
1316Key
1317
1318`--model, -m`
1319
1320Type / Values
1321
1322`string`
1323
1324Details
1325
1326Override the configured model for this run.
1327
1328Key
1329
1330`--oss`
1331
1332Type / Values
1333
1334`boolean`
1335
1336Details
1337
1338Use the local open source provider (requires a running Ollama instance).
1339
1340Key
1341
1342`--output-last-message, -o`
1343
1344Type / Values
1345
1346`path`
1347
1348Details
1349
1350Write the assistant’s final message to a file. Useful for downstream scripting.
1351
1352Key
1353
1354`--output-schema`
1355
1356Type / Values
1357
1358`path`
1359
1360Details
1361
1362JSON Schema file describing the expected final response shape. Codex validates tool output against it.
1363
1364Key
1365
1366`--profile, -p`
1367
1368Type / Values
1369
1370`string`
1371
1372Details
1373
1374Layer `$CODEX_HOME/profile-name.config.toml` on top of the base user config.
1375
1376Key
1377
1378`--sandbox, -s`
1379
1380Type / Values
1381
1382`read-only | workspace-write | danger-full-access`
1383
1384Details
1385
1386Sandbox policy for model-generated commands. Defaults to configuration.
1387
1388Key
1389
1390`--skip-git-repo-check`
1391
1392Type / Values
1393
1394`boolean`
1395
1396Details
1397
1398Allow running outside a Git repository (useful for one-off directories).
1399
1400Key
1401
1402`-c, --config`
1403
1404Type / Values
1405
1406`key=value`
1407
1408Details
1409
1410Inline configuration override for the non-interactive run (repeatable).
1411
1412Key
1413
1414`PROMPT`
1415
1416Type / Values
1417
1418`string | - (read stdin)`
1419
1420Details
1421
1422Initial instruction for the task. Use `-` to pipe the prompt from stdin.
1423
1424Key
1425
1426`Resume subcommand`
1427
1428Type / Values
1429
1430`codex exec resume [SESSION_ID]`
1431
1432Details
1433
1434Resume 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.
1435
1436Expand to view all
1437
1438Codex 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:
1439
1440| Key | Type / Values | Details |
1441| --- | --- | --- |
1442| `--all` | `boolean` | Include sessions outside the current working directory when selecting the most recent session. |
1443| `--image, -i` | `path[,path...]` | Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag. |
1444| `--last` | `boolean` | Resume the most recent conversation from the current working directory. |
1445| `PROMPT` | `string | - (read stdin)` | Optional follow-up instruction sent immediately after resuming. |
1446| `SESSION_ID` | `uuid` | Resume the specified session. Omit and use `--last` to continue the most recent session. |
1447
1448Key
1449
1450`--all`
1451
1452Type / Values
1453
1454`boolean`
1455
1456Details
1457
1458Include sessions outside the current working directory when selecting the most recent session.
1459
1460Key
1461
1462`--image, -i`
1463
1464Type / Values
1465
1466`path[,path...]`
1467
1468Details
1469
1470Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.
1471
1472Key
1473
1474`--last`
1475
1476Type / Values
1477
1478`boolean`
1479
1480Details
1481
1482Resume the most recent conversation from the current working directory.
1483
1484Key
1485
1486`PROMPT`
1487
1488Type / Values
1489
1490`string | - (read stdin)`
1491
1492Details
1493
1494Optional follow-up instruction sent immediately after resuming.
1495
1496Key
1497
1498`SESSION_ID`
1499
1500Type / Values
1501
1502`uuid`
1503
1504Details
1505
1506Resume the specified session. Omit and use `--last` to continue the most recent session.
1507
1508### `codex execpolicy`
1509
1510Check `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.
1511
1512| Key | Type / Values | Details |
1513| --- | --- | --- |
1514| `--pretty` | `boolean` | Pretty-print the JSON result. |
1515| `--rules, -r` | `path (repeatable)` | Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files. |
1516| `COMMAND...` | `var-args` | Command to be checked against the specified policies. |
1517
1518Key
1519
1520`--pretty`
1521
1522Type / Values
1523
1524`boolean`
1525
1526Details
1527
1528Pretty-print the JSON result.
1529
1530Key
1531
1532`--rules, -r`
1533
1534Type / Values
1535
1536`path (repeatable)`
1537
1538Details
1539
1540Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.
1541
1542Key
1543
1544`COMMAND...`
1545
1546Type / Values
1547
1548`var-args`
1549
1550Details
1551
1552Command to be checked against the specified policies.
1553
1554### `codex login`
1555
1556Authenticate the CLI with a ChatGPT account, API key, or access token. With no flags, Codex opens a browser for the ChatGPT OAuth flow.
1557
1558| Key | Type / Values | Details |
1559| --- | --- | --- |
1560| `--device-auth` | `boolean` | Use OAuth device code flow instead of launching a browser window. |
1561| `--with-access-token` | `boolean` | Read an access token from stdin (for example `printenv CODEX_ACCESS_TOKEN | codex login --with-access-token`). |
1562| `--with-api-key` | `boolean` | Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`). |
1563| `status subcommand` | `codex login status` | Print the active authentication mode and exit with 0 when logged in. |
1564
1565Key
1566
1567`--device-auth`
1568
1569Type / Values
1570
1571`boolean`
1572
1573Details
1574
1575Use OAuth device code flow instead of launching a browser window.
1576
1577Key
1578
1579`--with-access-token`
1580
1581Type / Values
1582
1583`boolean`
1584
1585Details
1586
1587Read an access token from stdin (for example `printenv CODEX_ACCESS_TOKEN | codex login --with-access-token`).
1588
1589Key
1590
1591`--with-api-key`
1592
1593Type / Values
1594
1595`boolean`
1596
1597Details
1598
1599Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`).
1600
1601Key
1602
1603`status subcommand`
1604
1605Type / Values
1606
1607`codex login status`
1608
1609Details
1610
1611Print the active authentication mode and exit with 0 when logged in.
1612
1613`codex login status` exits with `0` when credentials are present, which is helpful in automation scripts.
1614
1615### `codex logout`
1616
1617Remove saved credentials for both API key and ChatGPT authentication. This command has no flags.
1618
1619### `codex mcp`
1620
1621Manage Model Context Protocol server entries stored in `~/.codex/config.toml`.
1622
1623| Key | Type / Values | Details |
1624| --- | --- | --- |
1625| `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. |
1626| `get <name>` | `--json` | Show a specific server configuration. `--json` prints the raw config entry. |
1627| `list` | `--json` | List configured MCP servers. Add `--json` for machine-readable output. |
1628| `login <name>` | `--scopes scope1,scope2` | Start an OAuth login for a streamable HTTP server (servers that support OAuth only). |
1629| `logout <name>` | | Remove stored OAuth credentials for a streamable HTTP server. |
1630| `remove <name>` | | Delete a stored MCP server definition. |
1631
1632Key
1633
1634`add <name>`
1635
1636Type / Values
1637
1638`-- <command...> | --url <value>`
1639
1640Details
1641
1642Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports.
1643
1644Key
1645
1646`get <name>`
1647
1648Type / Values
1649
1650`--json`
1651
1652Details
1653
1654Show a specific server configuration. `--json` prints the raw config entry.
1655
1656Key
1657
1658`list`
1659
1660Type / Values
1661
1662`--json`
1663
1664Details
1665
1666List configured MCP servers. Add `--json` for machine-readable output.
1667
1668Key
1669
1670`login <name>`
1671
1672Type / Values
1673
1674`--scopes scope1,scope2`
1675
1676Details
1677 1080
1678Start an OAuth login for a streamable HTTP server (servers that support OAuth only).1081## Command overview
1679 1082
1680Key1083The Maturity column uses feature maturity labels such as Experimental, Beta,
1084 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to
1085 interpret these labels.
1681 1086
1682`logout <name>`1087<ConfigTable
1088 client:load
1089 options={commandOverview}
1090 secondColumnTitle="Maturity"
1091 secondColumnVariant="maturity"
1092/>
1683 1093
1684Details1094## Command details
1685 1095
1686Remove stored OAuth credentials for a streamable HTTP server.1096### `codex` (interactive)
1687 1097
1688Key1098Running `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`.
1689 1099
1690`remove <name>`1100Use `--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`. For a local Unix socket, use `--remote unix://` for the default socket or `--remote unix://PATH` for an explicit path. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication.
1691 1101
1692Details1102### `codex app-server`
1693 1103
1694Delete a stored MCP server definition.1104Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.
1695 1105
1696The `add` subcommand supports both stdio and streamable HTTP transports:1106<ConfigTable client:load options={appServerOptions} />
1697 1107
1698| Key | Type / Values | Details |1108`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior, and `codex app-server --stdio` is an alias for that transport. `--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.
1699| --- | --- | --- |
1700| `--bearer-token-env-var` | `ENV_VAR` | Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server. |
1701| `--env KEY=VALUE` | `repeatable` | Environment variable assignments applied when launching a stdio server. |
1702| `--oauth-client-id` | `CLIENT_ID` | OAuth client identifier for a streamable HTTP MCP server. Requires `--url`. |
1703| `--oauth-resource` | `RESOURCE` | OAuth resource parameter to include during login for a streamable HTTP MCP server. Requires `--url`. |
1704| `--url` | `https://…` | Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`. |
1705| `COMMAND...` | `stdio transport` | Executable plus arguments to launch the MCP server. Provide after `--`. |
1706 1109
1707Key1110### `codex remote-control`
1708 1111
1709`--bearer-token-env-var`1112Ensure the app-server daemon is running with remote-control support enabled.
1113Managed remote-control clients and SSH remote workflows use this command; it's
1114not a replacement for `codex app-server --listen` when you are building a local
1115protocol client.
1710 1116
1711Type / Values1117### `codex app`
1712 1118
1713`ENV_VAR`1119Launch 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.
1714 1120
1715Details1121<ConfigTable client:load options={appOptions} />
1716 1122
1717Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.1123`codex app` opens an installed Codex Desktop app, or starts the installer when
1124the app is missing. On macOS, Codex opens the provided workspace path; on
1125Windows, it prints the path to open after installation.
1718 1126
1719Key1127### `codex debug app-server send-message-v2`
1720 1128
1721`--env KEY=VALUE`1129Send one message through app-server's V2 thread/turn flow using the built-in app-server test client.
1722 1130
1723Type / Values1131<ConfigTable client:load options={debugAppServerSendMessageV2Options} />
1724 1132
1725`repeatable`1133This 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.
1726 1134
1727Details1135### `codex debug models`
1728 1136
1729Environment variable assignments applied when launching a stdio server.1137Print the raw model catalog Codex sees as JSON.
1730 1138
1731Key1139<ConfigTable client:load options={debugModelsOptions} />
1732 1140
1733`--oauth-client-id`1141Use `--bundled` when you want to inspect only the catalog bundled with the current binary, without refreshing from the remote models endpoint.
1734 1142
1735Type / Values1143### `codex apply`
1736 1144
1737`CLIENT_ID`1145Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.
1738 1146
1739Details1147<ConfigTable client:load options={applyOptions} />
1740 1148
1741OAuth client identifier for a streamable HTTP MCP server. Requires `--url`.1149Codex prints the patched files and exits non-zero if `git apply` fails (for example, due to conflicts).
1742 1150
1743Key1151### `codex archive` and `codex unarchive`
1744 1152
1745`--oauth-resource`1153Archive or restore a saved interactive session by session ID or session name.
1154Use these commands when you want to clean up the session picker without deleting
1155the transcript. Session IDs take precedence over session names.
1746 1156
1747Type / Values1157```bash
1158codex archive <SESSION>
1159codex unarchive <SESSION>
1160```
1748 1161
1749`RESOURCE`1162<ConfigTable client:load options={archiveOptions} />
1750 1163
1751Details1164### `codex cloud`
1752 1165
1753OAuth resource parameter to include during login for a streamable HTTP MCP server. Requires `--url`.1166Interact 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.
1754 1167
1755Key1168<ConfigTable client:load options={cloudExecOptions} />
1756 1169
1757`--url`1170Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.
1758 1171
1759Type / Values1172#### `codex cloud list`
1760 1173
1761`https://…`1174List recent cloud tasks with optional filtering and pagination.
1762 1175
1763Details1176<ConfigTable client:load options={cloudListOptions} />
1764 1177
1765Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`.1178Plain-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`.
1766 1179
1767Key1180### `codex completion`
1768 1181
1769`COMMAND...`1182Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.
1770 1183
1771Type / Values1184<ConfigTable client:load options={completionOptions} />
1772 1185
1773`stdio transport`1186### `codex doctor`
1774 1187
1775Details1188Generate a local diagnostic report before filing a support issue or
1189while investigating a broken Codex installation. The report checks installation,
1190configuration, authentication, runtime, Git, terminal, app-server, and thread
1191inventory health.
1776 1192
1777Executable plus arguments to launch the MCP server. Provide after `--`.1193<ConfigTable client:load options={doctorOptions} />
1778 1194
1779OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).1195### `codex features`
1780 1196
1781### `codex plugin`1197Manage feature flags stored in `$CODEX_HOME/config.toml`. The `enable` and
1198`disable` commands persist changes so they apply to future sessions. The
1199`features` subcommand doesn't accept `--profile`.
1782 1200
1783Install, list, and remove plugins from configured marketplaces.1201<ConfigTable client:load options={featuresOptions} />
1784 1202
1785| Key | Type / Values | Details |1203### `codex exec`
1786| --- | --- | --- |
1787| `add <plugin[@marketplace]>` | `[--marketplace, -m NAME] [--json]` | Install a plugin from a configured marketplace. Use `--marketplace` or `-m` when the plugin argument omits `@marketplace`. |
1788| `list` | `[--marketplace, -m NAME] [--available --json] [--json]` | List installed plugins. With `--json`, output has `installed` and `available` arrays; `--available` includes uninstalled marketplace plugins and requires `--json`. |
1789| `marketplace` | | Manage configured marketplace sources. See `codex plugin marketplace` below. |
1790| `remove <plugin[@marketplace]>` | `[--marketplace, -m NAME] [--json]` | Remove an installed plugin from local config and cache. Use `--json` for automation-friendly output. |
1791 1204
1792Key1205Use `codex exec` (or the short form `codex e`) for scripted or CI-style runs that should finish without human interaction.
1793 1206
1794`add <plugin[@marketplace]>`1207<ConfigTable client:load options={execOptions} />
1795 1208
1796Type / Values1209Codex 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:
1797 1210
1798`[--marketplace, -m NAME] [--json]`1211<ConfigTable client:load options={execResumeOptions} />
1799 1212
1800Details1213### `codex execpolicy`
1801 1214
1802Install a plugin from a configured marketplace. Use `--marketplace` or `-m` when the plugin argument omits `@marketplace`.1215Check `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.
1803 1216
1804Key1217<ConfigTable client:load options={execpolicyOptions} />
1805 1218
1806`list`1219### `codex login`
1807 1220
1808Type / Values1221Authenticate the CLI with a ChatGPT account, API key, or access token. With no flags, Codex opens a browser for the ChatGPT OAuth flow.
1809 1222
1810`[--marketplace, -m NAME] [--available --json] [--json]`1223<ConfigTable client:load options={loginOptions} />
1811 1224
1812Details1225`codex login status` exits with `0` when credentials are present, which is helpful in automation scripts.
1813 1226
1814List installed plugins. With `--json`, output has `installed` and `available` arrays; `--available` includes uninstalled marketplace plugins and requires `--json`.1227### `codex logout`
1815 1228
1816Key1229Remove saved credentials for both API key and ChatGPT authentication. This command has no flags.
1817 1230
1818`marketplace`1231### `codex mcp`
1819 1232
1820Details1233Manage Model Context Protocol server entries stored in `~/.codex/config.toml`.
1821 1234
1822Manage configured marketplace sources. See `codex plugin marketplace` below.1235<ConfigTable client:load options={mcpCommands} />
1823 1236
1824Key1237The `add` subcommand supports both stdio and streamable HTTP transports:
1825 1238
1826`remove <plugin[@marketplace]>`1239<ConfigTable client:load options={mcpAddOptions} />
1827 1240
1828Type / Values1241OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).
1829 1242
1830`[--marketplace, -m NAME] [--json]`1243### `codex plugin`
1831 1244
1832Details1245Install, list, and remove plugins from configured marketplaces.
1833 1246
1834Remove an installed plugin from local config and cache. Use `--json` for automation-friendly output.1247<ConfigTable client:load options={pluginCommands} />
1835 1248
1836`codex plugin add --json` prints `pluginId`, `name`, `marketplaceName`,1249`codex plugin add --json` prints `pluginId`, `name`, `marketplaceName`,
1837`version`, `installedPath`, and `authPolicy`. `codex plugin list --json` prints1250`version`, `installedPath`, and `authPolicy`. `codex plugin list --json` prints
1845 1258
1846Manage plugin marketplace sources that Codex can browse and install from.1259Manage plugin marketplace sources that Codex can browse and install from.
1847 1260
1848| Key | Type / Values | Details |1261<ConfigTable client:load options={marketplaceCommands} />
1849| --- | --- | --- |
1850| `add <source>` | `[--ref REF] [--sparse PATH] [--json]` | 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. |
1851| `list` | `[--json]` | Show plugin marketplaces Codex is currently considering and the root path for each marketplace. |
1852| `remove <marketplace-name>` | `[--json]` | Remove a configured plugin marketplace. |
1853| `upgrade [marketplace-name]` | `[--json]` | Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided. |
1854
1855Key
1856
1857`add <source>`
1858
1859Type / Values
1860
1861`[--ref REF] [--sparse PATH] [--json]`
1862
1863Details
1864
1865Install 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.
1866
1867Key
1868
1869`list`
1870
1871Type / Values
1872
1873`[--json]`
1874
1875Details
1876
1877Show plugin marketplaces Codex is currently considering and the root path for each marketplace.
1878
1879Key
1880
1881`remove <marketplace-name>`
1882
1883Type / Values
1884
1885`[--json]`
1886
1887Details
1888
1889Remove a configured plugin marketplace.
1890
1891Key
1892
1893`upgrade [marketplace-name]`
1894
1895Type / Values
1896
1897`[--json]`
1898
1899Details
1900
1901Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided.
1902 1262
1903`codex plugin marketplace add` accepts GitHub shorthand such as `owner/repo` or1263`codex plugin marketplace add` accepts GitHub shorthand such as `owner/repo` or
1904`owner/repo@ref`, HTTP or HTTPS Git URLs, SSH Git URLs, and local marketplace1264`owner/repo@ref`, HTTP or HTTPS Git URLs, SSH Git URLs, and local marketplace
1924 1284
1925Continue 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.1285Continue 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.
1926 1286
1927| Key | Type / Values | Details |1287<ConfigTable client:load options={resumeOptions} />
1928| --- | --- | --- |
1929| `--all` | `boolean` | Include sessions outside the current working directory when selecting the most recent session. |
1930| `--last` | `boolean` | Skip the picker and resume the most recent conversation from the current working directory. |
1931| `SESSION_ID` | `uuid` | Resume the specified session. Omit and use `--last` to continue the most recent session. |
1932
1933Key
1934
1935`--all`
1936
1937Type / Values
1938
1939`boolean`
1940
1941Details
1942
1943Include sessions outside the current working directory when selecting the most recent session.
1944
1945Key
1946
1947`--last`
1948
1949Type / Values
1950
1951`boolean`
1952
1953Details
1954
1955Skip the picker and resume the most recent conversation from the current working directory.
1956
1957Key
1958
1959`SESSION_ID`
1960
1961Type / Values
1962
1963`uuid`
1964
1965Details
1966
1967Resume the specified session. Omit and use `--last` to continue the most recent session.
1968 1288
1969### `codex fork`1289### `codex fork`
1970 1290
1971Fork 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.1291Fork 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.
1972 1292
1973| Key | Type / Values | Details |1293<ConfigTable client:load options={forkOptions} />
1974| --- | --- | --- |
1975| `--all` | `boolean` | Show sessions beyond the current working directory in the picker. |
1976| `--last` | `boolean` | Skip the picker and fork the most recent conversation automatically. |
1977| `SESSION_ID` | `uuid` | Fork the specified session. Omit and use `--last` to fork the most recent session. |
1978
1979Key
1980
1981`--all`
1982
1983Type / Values
1984
1985`boolean`
1986
1987Details
1988
1989Show sessions beyond the current working directory in the picker.
1990
1991Key
1992
1993`--last`
1994
1995Type / Values
1996
1997`boolean`
1998
1999Details
2000
2001Skip the picker and fork the most recent conversation automatically.
2002
2003Key
2004
2005`SESSION_ID`
2006
2007Type / Values
2008
2009`uuid`
2010
2011Details
2012
2013Fork the specified session. Omit and use `--last` to fork the most recent session.
2014 1294
2015### `codex sandbox`1295### `codex sandbox`
2016 1296
2018 1298
2019#### macOS seatbelt1299#### macOS seatbelt
2020 1300
2021| Key | Type / Values | Details |1301<ConfigTable client:load options={sandboxMacOptions} />
2022| --- | --- | --- |
2023| `--allow-unix-socket` | `path` | Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths. |
2024| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |
2025| `--config, -c` | `key=value` | Pass configuration overrides into the sandboxed run (repeatable). |
2026| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |
2027| `--log-denials` | `boolean` | Capture macOS sandbox denials with `log stream` while the command runs and print them after exit. |
2028| `--permissions-profile, -P` | `NAME` | Apply a named permissions profile from the active configuration stack. |
2029| `--profile, -p` | `NAME` | Layer `$CODEX_HOME/NAME.config.toml` on top of the base user config. |
2030| `COMMAND...` | `var-args` | Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded. |
2031
2032Key
2033
2034`--allow-unix-socket`
2035
2036Type / Values
2037
2038`path`
2039
2040Details
2041
2042Allow the sandboxed command to bind or connect Unix sockets rooted at this path. Repeat to allow multiple paths.
2043
2044Key
2045
2046`--cd, -C`
2047
2048Type / Values
2049
2050`DIR`
2051
2052Details
2053
2054Working directory used for profile resolution and command execution. Requires `--permissions-profile`.
2055
2056Key
2057
2058`--config, -c`
2059
2060Type / Values
2061
2062`key=value`
2063
2064Details
2065
2066Pass configuration overrides into the sandboxed run (repeatable).
2067
2068Key
2069
2070`--include-managed-config`
2071
2072Type / Values
2073
2074`boolean`
2075
2076Details
2077
2078Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.
2079
2080Key
2081
2082`--log-denials`
2083
2084Type / Values
2085
2086`boolean`
2087
2088Details
2089
2090Capture macOS sandbox denials with `log stream` while the command runs and print them after exit.
2091
2092Key
2093
2094`--permissions-profile, -P`
2095
2096Type / Values
2097
2098`NAME`
2099
2100Details
2101
2102Apply a named permissions profile from the active configuration stack.
2103
2104Key
2105
2106`--profile, -p`
2107
2108Type / Values
2109
2110`NAME`
2111
2112Details
2113
2114Layer `$CODEX_HOME/NAME.config.toml` on top of the base user config.
2115
2116Key
2117
2118`COMMAND...`
2119
2120Type / Values
2121
2122`var-args`
2123
2124Details
2125
2126Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.
2127 1302
2128#### Linux Landlock1303#### Linux Landlock
2129 1304
2130| Key | Type / Values | Details |1305<ConfigTable client:load options={sandboxLinuxOptions} />
2131| --- | --- | --- |
2132| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |
2133| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |
2134| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |
2135| `--permissions-profile, -P` | `NAME` | Apply a named permissions profile from the active configuration stack. |
2136| `--profile, -p` | `NAME` | Layer `$CODEX_HOME/NAME.config.toml` on top of the base user config. |
2137| `COMMAND...` | `var-args` | Command to execute under Landlock + seccomp. Provide the executable after `--`. |
2138
2139Key
2140
2141`--cd, -C`
2142
2143Type / Values
2144
2145`DIR`
2146
2147Details
2148
2149Working directory used for profile resolution and command execution. Requires `--permissions-profile`.
2150
2151Key
2152
2153`--config, -c`
2154
2155Type / Values
2156
2157`key=value`
2158
2159Details
2160
2161Configuration overrides applied before launching the sandbox (repeatable).
2162
2163Key
2164
2165`--include-managed-config`
2166
2167Type / Values
2168
2169`boolean`
2170
2171Details
2172
2173Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.
2174
2175Key
2176
2177`--permissions-profile, -P`
2178
2179Type / Values
2180
2181`NAME`
2182
2183Details
2184
2185Apply a named permissions profile from the active configuration stack.
2186
2187Key
2188
2189`--profile, -p`
2190
2191Type / Values
2192
2193`NAME`
2194
2195Details
2196
2197Layer `$CODEX_HOME/NAME.config.toml` on top of the base user config.
2198
2199Key
2200
2201`COMMAND...`
2202
2203Type / Values
2204
2205`var-args`
2206
2207Details
2208
2209Command to execute under Landlock + seccomp. Provide the executable after `--`.
2210 1306
2211#### Windows1307#### Windows
2212 1308
2213| Key | Type / Values | Details |1309<ConfigTable client:load options={sandboxWindowsOptions} />
2214| --- | --- | --- |
2215| `--cd, -C` | `DIR` | Working directory used for profile resolution and command execution. Requires `--permissions-profile`. |
2216| `--config, -c` | `key=value` | Configuration overrides applied before launching the sandbox (repeatable). |
2217| `--include-managed-config` | `boolean` | Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`. |
2218| `--permissions-profile, -P` | `NAME` | Apply a named permissions profile from the active configuration stack. |
2219| `--profile, -p` | `NAME` | Layer `$CODEX_HOME/NAME.config.toml` on top of the base user config. |
2220| `COMMAND...` | `var-args` | Command to execute under the native Windows sandbox. Provide the executable after `--`. |
2221
2222Key
2223
2224`--cd, -C`
2225
2226Type / Values
2227
2228`DIR`
2229
2230Details
2231
2232Working directory used for profile resolution and command execution. Requires `--permissions-profile`.
2233
2234Key
2235
2236`--config, -c`
2237
2238Type / Values
2239
2240`key=value`
2241
2242Details
2243
2244Configuration overrides applied before launching the sandbox (repeatable).
2245
2246Key
2247
2248`--include-managed-config`
2249
2250Type / Values
2251
2252`boolean`
2253
2254Details
2255
2256Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.
2257
2258Key
2259
2260`--permissions-profile, -P`
2261
2262Type / Values
2263
2264`NAME`
2265
2266Details
2267
2268Apply a named permissions profile from the active configuration stack.
2269
2270Key
2271
2272`--profile, -p`
2273
2274Type / Values
2275
2276`NAME`
2277
2278Details
2279
2280Layer `$CODEX_HOME/NAME.config.toml` on top of the base user config.
2281
2282Key
2283
2284`COMMAND...`
2285
2286Type / Values
2287
2288`var-args`
2289
2290Details
2291
2292Command to execute under the native Windows sandbox. Provide the executable after `--`.
2293 1310
2294### `codex update`1311### `codex update`
2295 1312
