cli/reference.md Codex Docs, 2026-04-30 18:36 UTC → 2026-05-18 22:01 UTC

1# Command line options1# Command line options

2 2 

3export const globalFlagOptions = [

4 {

5 key: "PROMPT",

6 type: "string",

7 description:

8 "Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.",

9 },

10 {

11 key: "--image, -i",

12 type: "path[,path...]",

13 description:

14 "Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.",

15 },

16 {

17 key: "--model, -m",

18 type: "string",

19 description:

20 "Override the model set in configuration (for example `gpt-5.4`).",

21 },

22 {

23 key: "--oss",

24 type: "boolean",

25 defaultValue: "false",

26 description:

27 'Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running.',

28 },

29 {

30 key: "--profile, -p",

31 type: "string",

32 description:

33 "Configuration profile name to load from `~/.codex/config.toml`.",

34 },

35 {

36 key: "--sandbox, -s",

37 type: "read-only | workspace-write | danger-full-access",

38 description:

39 "Select the sandbox policy for model-generated shell commands.",

40 },

41 {

42 key: "--ask-for-approval, -a",

43 type: "untrusted | on-request | never",

44 description:

45 "Control when Codex pauses for human approval before running a command. `on-failure` is deprecated; prefer `on-request` for interactive runs or `never` for non-interactive runs.",

46 },

47 {

48 key: "--dangerously-bypass-approvals-and-sandbox, --yolo",

49 type: "boolean",

50 defaultValue: "false",

51 description:

52 "Run every command without approvals or sandboxing. Only use inside an externally hardened environment.",

53 },

54 {

55 key: "--cd, -C",

56 type: "path",

57 description:

58 "Set the working directory for the agent before it starts processing your request.",

59 },

60 {

61 key: "--search",

62 type: "boolean",

63 defaultValue: "false",

64 description:

65 'Enable live web search (sets `web_search = "live"` instead of the default `"cached"`).',

66 },

67 {

68 key: "--add-dir",

69 type: "path",

70 description:

71 "Grant additional directories write access alongside the main workspace. Repeat for multiple paths.",

72 },

73 {

74 key: "--no-alt-screen",

75 type: "boolean",

76 defaultValue: "false",

77 description:

78 "Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run).",

79 },

80 {

81 key: "--remote",

82 type: "ws://host:port | wss://host:port",

83 description:

84 "Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode.",

85 },

86 {

87 key: "--remote-auth-token-env",

88 type: "ENV_VAR",

89 description:

90 "Read a bearer token from this environment variable and send it when connecting with `--remote`. Requires `--remote`; tokens are only sent over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`.",

91 },

92 {

93 key: "--enable",

94 type: "feature",

95 description:

96 "Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable.",

97 },

98 {

99 key: "--disable",

100 type: "feature",

101 description:

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

103 },

104 {

105 key: "--config, -c",

106 type: "key=value",

107 description:

108 "Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.",

109 },

110];

111 

112export const commandOverview = [

113 {

114 key: "codex",

115 href: "/codex/cli/reference#codex-interactive",

116 type: "stable",

117 description:

118 "Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.",

119 },

120 {

121 key: "codex app-server",

122 href: "/codex/cli/reference#codex-app-server",

123 type: "experimental",

124 description:

125 "Launch the Codex app server for local development or debugging over stdio, WebSocket, or a Unix socket.",

126 },

127 {

128 key: "codex remote-control",

129 href: "/codex/cli/reference#codex-remote-control",

130 type: "experimental",

131 description:

132 "Ensure the local app-server daemon is running with remote-control support enabled.",

133 },

134 {

135 key: "codex app",

136 href: "/codex/cli/reference#codex-app",

137 type: "stable",

138 description:

139 "Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open.",

140 },

141 {

142 key: "codex debug app-server send-message-v2",

143 href: "/codex/cli/reference#codex-debug-app-server-send-message-v2",

144 type: "experimental",

145 description:

146 "Debug app-server by sending a single V2 message through the built-in test client.",

147 },

148 {

149 key: "codex debug models",

150 href: "/codex/cli/reference#codex-debug-models",

151 type: "experimental",

152 description:

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

154 },

155 {

156 key: "codex apply",

157 href: "/codex/cli/reference#codex-apply",

158 type: "stable",

159 description:

160 "Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.",

161 },

162 {

163 key: "codex cloud",

164 href: "/codex/cli/reference#codex-cloud",

165 type: "experimental",

166 description:

167 "Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.",

168 },

169 {

170 key: "codex completion",

171 href: "/codex/cli/reference#codex-completion",

172 type: "stable",

173 description:

174 "Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.",

175 },

176 {

177 key: "codex features",

178 href: "/codex/cli/reference#codex-features",

179 type: "stable",

180 description:

181 "List feature flags and persistently enable or disable them in `config.toml`.",

182 },

183 {

184 key: "codex exec",

185 href: "/codex/cli/reference#codex-exec",

186 type: "stable",

187 description:

188 "Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.",

189 },

190 {

191 key: "codex execpolicy",

192 href: "/codex/cli/reference#codex-execpolicy",

193 type: "experimental",

194 description:

195 "Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.",

196 },

197 {

198 key: "codex login",

199 href: "/codex/cli/reference#codex-login",

200 type: "stable",

201 description:

202 "Authenticate Codex using ChatGPT OAuth, device auth, an API key, or an access token piped over stdin.",

203 },

204 {

205 key: "codex logout",

206 href: "/codex/cli/reference#codex-logout",

207 type: "stable",

208 description: "Remove stored authentication credentials.",

209 },

210 {

211 key: "codex mcp",

212 href: "/codex/cli/reference#codex-mcp",

213 type: "experimental",

214 description:

215 "Manage Model Context Protocol servers (list, add, remove, authenticate).",

216 },

217 {

218 key: "codex plugin marketplace",

219 href: "/codex/cli/reference#codex-plugin-marketplace",

220 type: "experimental",

221 description:

222 "Add, upgrade, or remove plugin marketplaces from Git or local sources.",

223 },

224 {

225 key: "codex mcp-server",

226 href: "/codex/cli/reference#codex-mcp-server",

227 type: "experimental",

228 description:

229 "Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.",

230 },

231 {

232 key: "codex resume",

233 href: "/codex/cli/reference#codex-resume",

234 type: "stable",

235 description:

236 "Continue a previous interactive session by ID or resume the most recent conversation.",

237 },

238 {

239 key: "codex fork",

240 href: "/codex/cli/reference#codex-fork",

241 type: "stable",

242 description:

243 "Fork a previous interactive session into a new thread, preserving the original transcript.",

244 },

245 {

246 key: "codex sandbox",

247 href: "/codex/cli/reference#codex-sandbox",

248 type: "experimental",

249 description:

250 "Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes.",

251 },

252 {

253 key: "codex update",

254 href: "/codex/cli/reference#codex-update",

255 type: "stable",

256 description:

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

258 },

259];

260 

261export const execOptions = [

262 {

263 key: "PROMPT",

264 type: "string | - (read stdin)",

265 description:

266 "Initial instruction for the task. Use `-` to pipe the prompt from stdin.",

267 },

268 {

269 key: "--image, -i",

270 type: "path[,path...]",

271 description:

272 "Attach images to the first message. Repeatable; supports comma-separated lists.",

273 },

274 {

275 key: "--model, -m",

276 type: "string",

277 description: "Override the configured model for this run.",

278 },

279 {

280 key: "--oss",

281 type: "boolean",

282 defaultValue: "false",

283 description:

284 "Use the local open source provider (requires a running Ollama instance).",

285 },

286 {

287 key: "--sandbox, -s",

288 type: "read-only | workspace-write | danger-full-access",

289 description:

290 "Sandbox policy for model-generated commands. Defaults to configuration.",

291 },

292 {

293 key: "--profile, -p",

294 type: "string",

295 description: "Select a configuration profile defined in config.toml.",

296 },

297 {

298 key: "--full-auto",

299 type: "boolean",

300 defaultValue: "false",

301 description:

302 "Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.",

303 },

304 {

305 key: "--dangerously-bypass-approvals-and-sandbox, --yolo",

306 type: "boolean",

307 defaultValue: "false",

308 description:

309 "Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.",

310 },

311 {

312 key: "--cd, -C",

313 type: "path",

314 description: "Set the workspace root before executing the task.",

315 },

316 {

317 key: "--skip-git-repo-check",

318 type: "boolean",

319 defaultValue: "false",

320 description:

321 "Allow running outside a Git repository (useful for one-off directories).",

322 },

323 {

324 key: "--ephemeral",

325 type: "boolean",

326 defaultValue: "false",

327 description: "Run without persisting session rollout files to disk.",

328 },

329 {

330 key: "--ignore-user-config",

331 type: "boolean",

332 defaultValue: "false",

333 description:

334 "Do not load `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`.",

335 },

336 {

337 key: "--ignore-rules",

338 type: "boolean",

339 defaultValue: "false",

340 description:

341 "Do not load user or project execpolicy `.rules` files for this run.",

342 },

343 {

344 key: "--output-schema",

345 type: "path",

346 description:

347 "JSON Schema file describing the expected final response shape. Codex validates tool output against it.",

348 },

349 {

350 key: "--color",

351 type: "always | never | auto",

352 defaultValue: "auto",

353 description: "Control ANSI color in stdout.",

354 },

355 {

356 key: "--json, --experimental-json",

357 type: "boolean",

358 defaultValue: "false",

359 description:

360 "Print newline-delimited JSON events instead of formatted text.",

361 },

362 {

363 key: "--output-last-message, -o",

364 type: "path",

365 description:

366 "Write the assistant’s final message to a file. Useful for downstream scripting.",

367 },

368 {

369 key: "Resume subcommand",

370 type: "codex exec resume [SESSION_ID]",

371 description:

372 "Resume an exec session by ID or add `--last` to continue the most recent session from the current working directory. Add `--all` to consider sessions from any directory. Accepts an optional follow-up prompt.",

373 },

374 {

375 key: "-c, --config",

376 type: "key=value",

377 description:

378 "Inline configuration override for the non-interactive run (repeatable).",

379 },

380];

381 

382export const appServerOptions = [

383 {

384 key: "--listen",

385 type: "stdio:// | ws://IP:PORT | unix:// | unix://PATH | off",

386 defaultValue: "stdio://",

387 description:

388 "Transport listener URL. Use `stdio://` for JSONL, `ws://IP:PORT` for a TCP WebSocket endpoint, `unix://` for the default Unix socket, `unix://PATH` for a custom Unix socket, or `off` to disable the local transport.",

389 },

390 {

391 key: "--ws-auth",

392 type: "capability-token | signed-bearer-token",

393 description:

394 "Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup.",

395 },

396 {

397 key: "--ws-token-file",

398 type: "absolute path",

399 description:

400 "File containing the shared capability token. Required with `--ws-auth capability-token`.",

401 },

402 {

403 key: "--ws-shared-secret-file",

404 type: "absolute path",

405 description:

406 "File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.",

407 },

408 {

409 key: "--ws-issuer",

410 type: "string",

411 description:

412 "Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.",

413 },

414 {

415 key: "--ws-audience",

416 type: "string",

417 description:

418 "Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.",

419 },

420 {

421 key: "--ws-max-clock-skew-seconds",

422 type: "number",

423 defaultValue: "30",

424 description:

425 "Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.",

426 },

427 {

428 key: "--analytics-default-enabled",

429 type: "boolean",

430 defaultValue: "false",

431 description:

432 "Defaults analytics to enabled for first-party app-server clients unless the user opts out in config.",

433 },

434];

435 

436export const appOptions = [

437 {

438 key: "PATH",

439 type: "path",

440 defaultValue: ".",

441 description:

442 "Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.",

443 },

444 {

445 key: "--download-url",

446 type: "url",

447 description:

448 "Advanced override for the Codex desktop installer URL used during install.",

449 },

450];

451 

452export const debugAppServerSendMessageV2Options = [

453 {

454 key: "USER_MESSAGE",

455 type: "string",

456 description:

457 "Message text sent to app-server through the built-in V2 test-client flow.",

458 },

459];

460 

461export const debugModelsOptions = [

462 {

463 key: "--bundled",

464 type: "boolean",

465 defaultValue: "false",

466 description:

467 "Skip refresh and print only the model catalog bundled with the current Codex binary.",

468 },

469];

470 

471export const resumeOptions = [

472 {

473 key: "SESSION_ID",

474 type: "uuid",

475 description:

476 "Resume the specified session. Omit and use `--last` to continue the most recent session.",

477 },

478 {

479 key: "--last",

480 type: "boolean",

481 defaultValue: "false",

482 description:

483 "Skip the picker and resume the most recent conversation from the current working directory.",

484 },

485 {

486 key: "--all",

487 type: "boolean",

488 defaultValue: "false",

489 description:

490 "Include sessions outside the current working directory when selecting the most recent session.",

491 },

492];

493 

494export const featuresOptions = [

495 {

496 key: "List subcommand",

497 type: "codex features list",

498 description:

499 "Show known feature flags, their maturity stage, and their effective state.",

500 },

501 {

502 key: "Enable subcommand",

503 type: "codex features enable <feature>",

504 description:

505 "Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.",

506 },

507 {

508 key: "Disable subcommand",

509 type: "codex features disable <feature>",

510 description:

511 "Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.",

512 },

513];

514 

515export const execResumeOptions = [

516 {

517 key: "SESSION_ID",

518 type: "uuid",

519 description:

520 "Resume the specified session. Omit and use `--last` to continue the most recent session.",

521 },

522 {

523 key: "--last",

524 type: "boolean",

525 defaultValue: "false",

526 description:

527 "Resume the most recent conversation from the current working directory.",

528 },

529 {

530 key: "--all",

531 type: "boolean",

532 defaultValue: "false",

533 description:

534 "Include sessions outside the current working directory when selecting the most recent session.",

535 },

536 {

537 key: "--image, -i",

538 type: "path[,path...]",

539 description:

540 "Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.",

541 },

542 {

543 key: "PROMPT",

544 type: "string | - (read stdin)",

545 description:

546 "Optional follow-up instruction sent immediately after resuming.",

547 },

548];

549 

550export const forkOptions = [

551 {

552 key: "SESSION_ID",

553 type: "uuid",

554 description:

555 "Fork the specified session. Omit and use `--last` to fork the most recent session.",

556 },

557 {

558 key: "--last",

559 type: "boolean",

560 defaultValue: "false",

561 description:

562 "Skip the picker and fork the most recent conversation automatically.",

563 },

564 {

565 key: "--all",

566 type: "boolean",

567 defaultValue: "false",

568 description:

569 "Show sessions beyond the current working directory in the picker.",

570 },

571];

572 

573export const execpolicyOptions = [

574 {

575 key: "--rules, -r",

576 type: "path (repeatable)",

577 description:

578 "Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.",

579 },

580 {

581 key: "--pretty",

582 type: "boolean",

583 defaultValue: "false",

584 description: "Pretty-print the JSON result.",

585 },

586 {

587 key: "COMMAND...",

588 type: "var-args",

589 description: "Command to be checked against the specified policies.",

590 },

591];

592 

593export const loginOptions = [

594 {

595 key: "--with-api-key",

596 type: "boolean",

597 description:

598 "Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`).",

599 },

600 {

601 key: "--with-access-token",

602 type: "boolean",

603 description:

604 "Read an access token from stdin (for example `printenv CODEX_ACCESS_TOKEN | codex login --with-access-token`).",

605 },

606 {

607 key: "--device-auth",

608 type: "boolean",

609 description:

610 "Use OAuth device code flow instead of launching a browser window.",

611 },

612 {

613 key: "status subcommand",

614 type: "codex login status",

615 description:

616 "Print the active authentication mode and exit with 0 when logged in.",

617 },

618];

619 

620export const applyOptions = [

621 {

622 key: "TASK_ID",

623 type: "string",

624 description:

625 "Identifier of the Codex Cloud task whose diff should be applied.",

626 },

627];

628 

629export const sandboxMacOptions = [

630 {

631 key: "--permissions-profile",

632 type: "NAME",

633 description:

634 "Apply a named permissions profile from the active configuration stack.",

635 },

636 {

637 key: "--cd, -C",

638 type: "DIR",

639 description:

640 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",

641 },

642 {

643 key: "--include-managed-config",

644 type: "boolean",

645 defaultValue: "false",

646 description:

647 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",

648 },

649 {

650 key: "--allow-unix-socket",

651 type: "path",

652 description:

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

654 },

655 {

656 key: "--log-denials",

657 type: "boolean",

658 defaultValue: "false",

659 description:

660 "Capture macOS sandbox denials with `log stream` while the command runs and print them after exit.",

661 },

662 {

663 key: "--config, -c",

664 type: "key=value",

665 description:

666 "Pass configuration overrides into the sandboxed run (repeatable).",

667 },

668 {

669 key: "COMMAND...",

670 type: "var-args",

671 description:

672 "Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.",

673 },

674];

675 

676export const sandboxLinuxOptions = [

677 {

678 key: "--permissions-profile",

679 type: "NAME",

680 description:

681 "Apply a named permissions profile from the active configuration stack.",

682 },

683 {

684 key: "--cd, -C",

685 type: "DIR",

686 description:

687 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",

688 },

689 {

690 key: "--include-managed-config",

691 type: "boolean",

692 defaultValue: "false",

693 description:

694 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",

695 },

696 {

697 key: "--config, -c",

698 type: "key=value",

699 description:

700 "Configuration overrides applied before launching the sandbox (repeatable).",

701 },

702 {

703 key: "COMMAND...",

704 type: "var-args",

705 description:

706 "Command to execute under Landlock + seccomp. Provide the executable after `--`.",

707 },

708];

709 

710export const sandboxWindowsOptions = [

711 {

712 key: "--permissions-profile",

713 type: "NAME",

714 description:

715 "Apply a named permissions profile from the active configuration stack.",

716 },

717 {

718 key: "--cd, -C",

719 type: "DIR",

720 description:

721 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",

722 },

723 {

724 key: "--include-managed-config",

725 type: "boolean",

726 defaultValue: "false",

727 description:

728 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",

729 },

730 {

731 key: "--config, -c",

732 type: "key=value",

733 description:

734 "Configuration overrides applied before launching the sandbox (repeatable).",

735 },

736 {

737 key: "COMMAND...",

738 type: "var-args",

739 description:

740 "Command to execute under the native Windows sandbox. Provide the executable after `--`.",

741 },

742];

743 

744export const completionOptions = [

745 {

746 key: "SHELL",

747 type: "bash | zsh | fish | power-shell | elvish",

748 defaultValue: "bash",

749 description: "Shell to generate completions for. Output prints to stdout.",

750 },

751];

752 

753export const cloudExecOptions = [

754 {

755 key: "QUERY",

756 type: "string",

757 description:

758 "Task prompt. If omitted, Codex prompts interactively for details.",

759 },

760 {

761 key: "--env",

762 type: "ENV_ID",

763 description:

764 "Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.",

765 },

766 {

767 key: "--attempts",

768 type: "1-4",

769 defaultValue: "1",

770 description:

771 "Number of assistant attempts (best-of-N) Codex Cloud should run.",

772 },

773];

774 

775export const cloudListOptions = [

776 {

777 key: "--env",

778 type: "ENV_ID",

779 description: "Filter tasks by environment identifier.",

780 },

781 {

782 key: "--limit",

783 type: "1-20",

784 defaultValue: "20",

785 description: "Maximum number of tasks to return.",

786 },

787 {

788 key: "--cursor",

789 type: "string",

790 description: "Pagination cursor returned by a previous request.",

791 },

792 {

793 key: "--json",

794 type: "boolean",

795 defaultValue: "false",

796 description: "Emit machine-readable JSON instead of plain text.",

797 },

798];

799 

800export const mcpCommands = [

801 {

802 key: "list",

803 type: "--json",

804 description:

805 "List configured MCP servers. Add `--json` for machine-readable output.",

806 },

807 {

808 key: "get <name>",

809 type: "--json",

810 description:

811 "Show a specific server configuration. `--json` prints the raw config entry.",

812 },

813 {

814 key: "add <name>",

815 type: "-- <command...> | --url <value>",

816 description:

817 "Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports.",

818 },

819 {

820 key: "remove <name>",

821 description: "Delete a stored MCP server definition.",

822 },

823 {

824 key: "login <name>",

825 type: "--scopes scope1,scope2",

826 description:

827 "Start an OAuth login for a streamable HTTP server (servers that support OAuth only).",

828 },

829 {

830 key: "logout <name>",

831 description:

832 "Remove stored OAuth credentials for a streamable HTTP server.",

833 },

834];

835 

836export const mcpAddOptions = [

837 {

838 key: "COMMAND...",

839 type: "stdio transport",

840 description:

841 "Executable plus arguments to launch the MCP server. Provide after `--`.",

842 },

843 {

844 key: "--env KEY=VALUE",

845 type: "repeatable",

846 description:

847 "Environment variable assignments applied when launching a stdio server.",

848 },

849 {

850 key: "--url",

851 type: "https://…",

852 description:

853 "Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`.",

854 },

855 {

856 key: "--bearer-token-env-var",

857 type: "ENV_VAR",

858 description:

859 "Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.",

860 },

861];

862 

863export const marketplaceCommands = [

864 {

865 key: "add <source>",

866 type: "[--ref REF] [--sparse PATH]",

867 description:

868 "Install a plugin marketplace from GitHub shorthand, a Git URL, an SSH URL, or a local marketplace root directory. `--sparse` is supported only for Git sources and can be repeated.",

869 },

870 {

871 key: "upgrade [marketplace-name]",

872 description:

873 "Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided.",

874 },

875 {

876 key: "remove <marketplace-name>",

877 description: "Remove a configured plugin marketplace.",

878 },

879];

880 

3## How to read this reference881## How to read this reference

4 882 

5This page catalogs every documented Codex CLI command and flag. Use the interactive tables to search by key or description. Each section indicates whether the option is stable or experimental and calls out risky combinations.883This page catalogs every documented Codex CLI command and flag. Use the interactive tables to search by key or description. Each section indicates whether the option is stable or experimental and calls out risky combinations.

6 884 

7The CLI inherits most defaults from <code>~/.codex/config.toml</code>. Any885The CLI inherits most defaults from <code>~/.codex/config.toml</code>. Any

8 <code>-c key=value</code> overrides you pass at the command line take886 <code>-c key=value</code> overrides you pass at the command line take

9 precedence for that invocation. See [Config887 precedence for that invocation. See [Config

10 basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.888 basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.

11 

12## Global flags

13 

14| Key | Type / Values | Details |

15| --- | --- | --- |

16| `--add-dir` | `path` | Grant additional directories write access alongside the main workspace. Repeat for multiple paths. |

17| `--ask-for-approval, -a` | `untrusted | on-request | never` | Control when Codex pauses for human approval before running a command. `on-failure` is deprecated; prefer `on-request` for interactive runs or `never` for non-interactive runs. |

18| `--cd, -C` | `path` | Set the working directory for the agent before it starts processing your request. |

19| `--config, -c` | `key=value` | Override configuration values. Values parse as JSON if possible; otherwise the literal string is used. |

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

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

22| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |

23| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |

24| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |

25| `--no-alt-screen` | `boolean` | Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run). |

26| `--oss` | `boolean` | Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running. |

27| `--profile, -p` | `string` | Configuration profile name to load from `~/.codex/config.toml`. |

28| `--remote` | `ws://host:port | wss://host:port` | Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode. |

29| `--remote-auth-token-env` | `ENV_VAR` | Read a bearer token from this environment variable and send it when connecting with `--remote`. Requires `--remote`; tokens are only sent over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`. |

30| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Select the sandbox policy for model-generated shell commands. |

31| `--search` | `boolean` | Enable live web search (sets `web_search = "live"` instead of the default `"cached"`). |

32| `PROMPT` | `string` | Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message. |

33 

34Key

35 

36`--add-dir`

37 

38Type / Values

39 

40`path`

41 

42Details

43 

44Grant additional directories write access alongside the main workspace. Repeat for multiple paths.

45 

46Key

47 

48`--ask-for-approval, -a`

49 

50Type / Values

51 

52`untrusted | on-request | never`

53 

54Details

55 

56Control when Codex pauses for human approval before running a command. `on-failure` is deprecated; prefer `on-request` for interactive runs or `never` for non-interactive runs.

57 

58Key

59 

60`--cd, -C`

61 

62Type / Values

63 

64`path`

65 

66Details

67 

68Set the working directory for the agent before it starts processing your request.

69 

70Key

71 

72`--config, -c`

73 

74Type / Values

75 

76`key=value`

77 

78Details

79 

80Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.

81 

82Key

83 

84`--dangerously-bypass-approvals-and-sandbox, --yolo`

85 

86Type / Values

87 

88`boolean`

89 

90Details

91 

92Run every command without approvals or sandboxing. Only use inside an externally hardened environment.

93 

94Key

95 

96`--disable`

97 

98Type / Values

99 

100`feature`

101 

102Details

103 

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

105 

106Key

107 

108`--enable`

109 

110Type / Values

111 

112`feature`

113 

114Details

115 

116Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable.

117 

118Key

119 

120`--image, -i`

121 

122Type / Values

123 

124`path[,path...]`

125 

126Details

127 

128Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.

129 

130Key

131 

132`--model, -m`

133 

134Type / Values

135 

136`string`

137 

138Details

139 

140Override the model set in configuration (for example `gpt-5.4`).

141 

142Key

143 

144`--no-alt-screen`

145 

146Type / Values

147 

148`boolean`

149 

150Details

151 

152Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run).

153 

154Key

155 

156`--oss`

157 

158Type / Values

159 

160`boolean`

161 

162Details

163 

164Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running.

165 

166Key

167 

168`--profile, -p`

169 

170Type / Values

171 

172`string`

173 

174Details

175 

176Configuration profile name to load from `~/.codex/config.toml`.

177 

178Key

179 

180`--remote`

181 

182Type / Values

183 

184`ws://host:port | wss://host:port`

185 

186Details

187 

188Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode.

189 

190Key

191 

192`--remote-auth-token-env`

193 

194Type / Values

195 

196`ENV_VAR`

197 

198Details

199 

200Read a bearer token from this environment variable and send it when connecting with `--remote`. Requires `--remote`; tokens are only sent over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`.

201 

202Key

203 

204`--sandbox, -s`

205 

206Type / Values

207 

208`read-only | workspace-write | danger-full-access`

209 

210Details

211 

212Select the sandbox policy for model-generated shell commands.

213 

214Key

215 

216`--search`

217 

218Type / Values

219 

220`boolean`

221 

222Details

223 

224Enable live web search (sets `web_search = "live"` instead of the default `"cached"`).

225 

226Key

227 

228`PROMPT`

229 

230Type / Values

231 

232`string`

233 

234Details

235 

236Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.

237 

238Expand to view all

239 

240These options apply to the base `codex` command and propagate to each subcommand unless a section below specifies otherwise.

241When you run a subcommand, place global flags after it (for example, `codex exec --oss ...`) so Codex applies them as intended.

242 

243## Command overview

244 

245The Maturity column uses feature maturity labels such as Experimental, Beta,

246 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to

247 interpret these labels.

248 

249| Key | Maturity | Details |

250| --- | --- | --- |

251| [`codex`](https://developers.openai.com/codex/cli/reference#codex-interactive) | Stable | Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments. |

252| [`codex app`](https://developers.openai.com/codex/cli/reference#codex-app) | Stable | Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open. |

253| [`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server) | Experimental | Launch the Codex app server for local development or debugging. |

254| [`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply) | Stable | Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`. |

255| [`codex cloud`](https://developers.openai.com/codex/cli/reference#codex-cloud) | Experimental | Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`. |

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

257| [`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2) | Experimental | Debug app-server by sending a single V2 message through the built-in test client. |

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

259| [`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec) | Stable | Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions. |

260| [`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy) | Experimental | Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked. |

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

262| [`codex fork`](https://developers.openai.com/codex/cli/reference#codex-fork) | Stable | Fork a previous interactive session into a new thread, preserving the original transcript. |

263| [`codex login`](https://developers.openai.com/codex/cli/reference#codex-login) | Stable | Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin. |

264| [`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout) | Stable | Remove stored authentication credentials. |

265| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |

266| [`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server) | Experimental | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex. |

267| [`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace) | Experimental | Add, upgrade, or remove plugin marketplaces from Git or local sources. |

268| [`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume) | Stable | Continue a previous interactive session by ID or resume the most recent conversation. |

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

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

271 

272Key

273 

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

275 

276Maturity

277 

278Stable

279 

280Details

281 

282Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.

283 

284Key

285 

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

287 

288Maturity

289 

290Stable

291 

292Details

293 

294Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open.

295 

296Key

297 

298[`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server)

299 

300Maturity

301 

302Experimental

303 

304Details

305 

306Launch the Codex app server for local development or debugging.

307 

308Key

309 

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

311 

312Maturity

313 

314Stable

315 

316Details

317 

318Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.

319 

320Key

321 

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

323 

324Maturity

325 

326Experimental

327 

328Details

329 

330Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.

331 

332Key

333 

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

335 

336Maturity

337 

338Stable

339 

340Details

341 

342Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.

343 

344Key

345 

346[`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2)

347 

348Maturity

349 

350Experimental

351 

352Details

353 

354Debug app-server by sending a single V2 message through the built-in test client.

355 

356Key

357 

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

359 

360Maturity

361 

362Experimental

363 

364Details

365 

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

367 

368Key

369 

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

371 

372Maturity

373 

374Stable

375 

376Details

377 

378Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.

379 

380Key

381 

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

383 

384Maturity

385 

386Experimental

387 

388Details

389 

390Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.

391 

392Key

393 

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

395 

396Maturity

397 

398Stable

399 

400Details

401 

402List feature flags and persistently enable or disable them in `config.toml`.

403 

404Key

405 

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

407 

408Maturity

409 

410Stable

411 

412Details

413 

414Fork a previous interactive session into a new thread, preserving the original transcript.

415 

416Key

417 

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

419 

420Maturity

421 

422Stable

423 

424Details

425 

426Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.

427 

428Key

429 

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

431 

432Maturity

433 

434Stable

435 

436Details

437 

438Remove stored authentication credentials.

439 

440Key

441 

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

443 

444Maturity

445 

446Experimental

447 

448Details

449 

450Manage Model Context Protocol servers (list, add, remove, authenticate).

451 

452Key

453 

454[`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server)

455 

456Maturity

457 

458Experimental

459 

460Details

461 

462Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.

463 

464Key

465 

466[`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace)

467 

468Maturity

469 

470Experimental

471 

472Details

473 

474Add, upgrade, or remove plugin marketplaces from Git or local sources.

475 

476Key

477 

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

479 

480Maturity

481 

482Stable

483 

484Details

485 

486Continue a previous interactive session by ID or resume the most recent conversation.

487 

488Key

489 

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

491 

492Maturity

493 

494Experimental

495 

496Details

497 

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

499 

500Key

501 

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

503 

504Maturity

505 

506Stable

507 

508Details

509 

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

511 

512Expand to view all

513 

514## Command details

515 

516### `codex` (interactive)

517 

518Running `codex` with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use `--search` to switch to live browsing. For low-friction local work, use `--sandbox workspace-write --ask-for-approval on-request`.

519 

520Use `--remote ws://host:port` or `--remote wss://host:port` to connect the TUI to an app server started with `codex app-server --listen ws://IP:PORT`. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication. See [Codex CLI features](https://developers.openai.com/codex/cli/features#connect-the-tui-to-a-remote-app-server) for setup examples and authentication guidance.

521 

522### `codex app-server`

523 

524Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.

525 

526| Key | Type / Values | Details |

527| --- | --- | --- |

528| `--listen` | `stdio:// | ws://IP:PORT` | Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients. |

529| `--ws-audience` | `string` | Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |

530| `--ws-auth` | `capability-token | signed-bearer-token` | Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup. |

531| `--ws-issuer` | `string` | Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |

532| `--ws-max-clock-skew-seconds` | `number` | Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`. |

533| `--ws-shared-secret-file` | `absolute path` | File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`. |

534| `--ws-token-file` | `absolute path` | File containing the shared capability token. Required with `--ws-auth capability-token`. |

535 

536Key

537 

538`--listen`

539 

540Type / Values

541 

542`stdio:// | ws://IP:PORT`

543 

544Details

545 

546Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients.

547 

548Key

549 

550`--ws-audience`

551 

552Type / Values

553 

554`string`

555 

556Details

557 

558Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.

559 

560Key

561 

562`--ws-auth`

563 

564Type / Values

565 

566`capability-token | signed-bearer-token`

567 

568Details

569 

570Authentication mode for app-server WebSocket clients. If omitted, WebSocket auth is disabled; non-local listeners warn during startup.

571 

572Key

573 

574`--ws-issuer`

575 

576Type / Values

577 

578`string`

579 

580Details

581 

582Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.

583 

584Key

585 

586`--ws-max-clock-skew-seconds`

587 

588Type / Values

589 

590`number`

591 

592Details

593 

594Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.

595 

596Key

597 

598`--ws-shared-secret-file`

599 

600Type / Values

601 

602`absolute path`

603 

604Details

605 

606File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.

607 

608Key

609 

610`--ws-token-file`

611 

612Type / Values

613 

614`absolute path`

615 

616Details

617 

618File containing the shared capability token. Required with `--ws-auth capability-token`.

619 

620`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior. `--listen ws://IP:PORT` enables WebSocket transport for app-server clients. The server accepts `ws://` listen URLs; use TLS termination or a secure proxy when clients connect with `wss://`. If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.

621 

622### `codex app`

623 

624Launch Codex Desktop from the terminal on macOS or Windows. On macOS, Codex can open a specific workspace path; on Windows, Codex prints the path to open.

625 

626| Key | Type / Values | Details |

627| --- | --- | --- |

628| `--download-url` | `url` | Advanced override for the Codex desktop installer URL used during install. |

629| `PATH` | `path` | Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path. |

630 

631Key

632 

633`--download-url`

634 

635Type / Values

636 

637`url`

638 

639Details

640 

641Advanced override for the Codex desktop installer URL used during install.

642 

643Key

644 

645`PATH`

646 

647Type / Values

648 

649`path`

650 

651Details

652 

653Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.

654 

655`codex app` opens an installed Codex Desktop app, or starts the installer when

656the app is missing. On macOS, Codex opens the provided workspace path; on

657Windows, it prints the path to open after installation.

658 

659### `codex debug app-server send-message-v2`

660 

661Send one message through app-server's V2 thread/turn flow using the built-in app-server test client.

662 

663| Key | Type / Values | Details |

664| --- | --- | --- |

665| `USER_MESSAGE` | `string` | Message text sent to app-server through the built-in V2 test-client flow. |

666 

667Key

668 

669`USER_MESSAGE`

670 

671Type / Values

672 

673`string`

674 

675Details

676 

677Message text sent to app-server through the built-in V2 test-client flow.

678 

679This debug flow initializes with `experimentalApi: true`, starts a thread, sends a turn, and streams server notifications. Use it to reproduce and inspect app-server protocol behavior locally.

680 

681### `codex debug models`

682 

683Print the raw model catalog Codex sees as JSON.

684 

685| Key | Type / Values | Details |

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

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

688 

689Key

690 

691`--bundled`

692 

693Type / Values

694 

695`boolean`

696 

697Details

698 

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

700 

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

702 

703### `codex apply`

704 

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

706 

707| Key | Type / Values | Details |

708| --- | --- | --- |

709| `TASK_ID` | `string` | Identifier of the Codex Cloud task whose diff should be applied. |

710 

711Key

712 

713`TASK_ID`

714 

715Type / Values

716 

717`string`

718 

719Details

720 

721Identifier of the Codex Cloud task whose diff should be applied.

722 

723Codex prints the patched files and exits non-zero if `git apply` fails (for example, due to conflicts).

724 

725### `codex cloud`

726 

727Interact with Codex cloud tasks from the terminal. The default command opens an interactive picker; `codex cloud exec` submits a task directly, and `codex cloud list` returns recent tasks for scripting or quick inspection.

728 

729| Key | Type / Values | Details |

730| --- | --- | --- |

731| `--attempts` | `1-4` | Number of assistant attempts (best-of-N) Codex Cloud should run. |

732| `--env` | `ENV_ID` | Target Codex Cloud environment identifier (required). Use `codex cloud` to list options. |

733| `QUERY` | `string` | Task prompt. If omitted, Codex prompts interactively for details. |

734 

735Key

736 

737`--attempts`

738 

739Type / Values

740 

741`1-4`

742 

743Details

744 

745Number of assistant attempts (best-of-N) Codex Cloud should run.

746 

747Key

748 

749`--env`

750 

751Type / Values

752 

753`ENV_ID`

754 

755Details

756 

757Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.

758 

759Key

760 

761`QUERY`

762 

763Type / Values

764 

765`string`

766 

767Details

768 

769Task prompt. If omitted, Codex prompts interactively for details.

770 

771Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.

772 

773#### `codex cloud list`

774 

775List recent cloud tasks with optional filtering and pagination.

776 

777| Key | Type / Values | Details |

778| --- | --- | --- |

779| `--cursor` | `string` | Pagination cursor returned by a previous request. |

780| `--env` | `ENV_ID` | Filter tasks by environment identifier. |

781| `--json` | `boolean` | Emit machine-readable JSON instead of plain text. |

782| `--limit` | `1-20` | Maximum number of tasks to return. |

783 

784Key

785 

786`--cursor`

787 

788Type / Values

789 

790`string`

791 

792Details

793 

794Pagination cursor returned by a previous request.

795 

796Key

797 

798`--env`

799 

800Type / Values

801 

802`ENV_ID`

803 

804Details

805 

806Filter tasks by environment identifier.

807 

808Key

809 

810`--json`

811 

812Type / Values

813 

814`boolean`

815 

816Details

817 

818Emit machine-readable JSON instead of plain text.

819 

820Key

821 

822`--limit`

823 

824Type / Values

825 

826`1-20`

827 

828Details

829 

830Maximum number of tasks to return.

831 

832Plain-text output prints a task URL followed by status details. Use `--json` for automation. The JSON payload contains a `tasks` array plus an optional `cursor` value. Each task includes `id`, `url`, `title`, `status`, `updated_at`, `environment_id`, `environment_label`, `summary`, `is_review`, and `attempt_total`.

833 

834### `codex completion`

835 

836Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.

837 

838| Key | Type / Values | Details |

839| --- | --- | --- |

840| `SHELL` | `bash | zsh | fish | power-shell | elvish` | Shell to generate completions for. Output prints to stdout. |

841 

842Key

843 

844`SHELL`

845 

846Type / Values

847 

848`bash | zsh | fish | power-shell | elvish`

849 

850Details

851 

852Shell to generate completions for. Output prints to stdout.

853 

854### `codex features`

855 

856Manage feature flags stored in `~/.codex/config.toml`. The `enable` and `disable` commands persist changes so they apply to future sessions. When you launch with `--profile`, Codex writes to that profile instead of the root configuration.

857 

858| Key | Type / Values | Details |

859| --- | --- | --- |

860| `Disable subcommand` | `codex features disable <feature>` | Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided. |

861| `Enable subcommand` | `codex features enable <feature>` | Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided. |

862| `List subcommand` | `codex features list` | Show known feature flags, their maturity stage, and their effective state. |

863 

864Key

865 

866`Disable subcommand`

867 

868Type / Values

869 

870`codex features disable <feature>`

871 

872Details

873 

874Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.

875 

876Key

877 

878`Enable subcommand`

879 

880Type / Values

881 

882`codex features enable <feature>`

883 

884Details

885 

886Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.

887 

888Key

889 

890`List subcommand`

891 

892Type / Values

893 

894`codex features list`

895 

896Details

897 

898Show known feature flags, their maturity stage, and their effective state.

899 

900### `codex exec`

901 

902Use `codex exec` (or the short form `codex e`) for scripted or CI-style runs that should finish without human interaction.

903 

904| Key | Type / Values | Details |

905| --- | --- | --- |

906| `--cd, -C` | `path` | Set the workspace root before executing the task. |

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

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

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

910| `--full-auto` | `boolean` | Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used. |

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

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

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

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

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

916| `--oss` | `boolean` | Use the local open source provider (requires a running Ollama instance). |

917| `--output-last-message, -o` | `path` | Write the assistant’s final message to a file. Useful for downstream scripting. |

918| `--output-schema` | `path` | JSON Schema file describing the expected final response shape. Codex validates tool output against it. |

919| `--profile, -p` | `string` | Select a configuration profile defined in config.toml. |

920| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Sandbox policy for model-generated commands. Defaults to configuration. |

921| `--skip-git-repo-check` | `boolean` | Allow running outside a Git repository (useful for one-off directories). |

922| `-c, --config` | `key=value` | Inline configuration override for the non-interactive run (repeatable). |

923| `PROMPT` | `string | - (read stdin)` | Initial instruction for the task. Use `-` to pipe the prompt from stdin. |

924| `Resume subcommand` | `codex exec resume [SESSION_ID]` | Resume an exec session by ID or add `--last` to continue the most recent session from the current working directory. Add `--all` to consider sessions from any directory. Accepts an optional follow-up prompt. |

925 

926Key

927 

928`--cd, -C`

929 

930Type / Values

931 

932`path`

933 

934Details

935 

936Set the workspace root before executing the task.

937 

938Key

939 

940`--color`

941 

942Type / Values

943 

944`always | never | auto`

945 

946Details

947 

948Control ANSI color in stdout.

949 

950Key

951 

952`--dangerously-bypass-approvals-and-sandbox, --yolo`

953 

954Type / Values

955 

956`boolean`

957 

958Details

959 

960Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.

961 

962Key

963 

964`--ephemeral`

965 

966Type / Values

967 

968`boolean`

969 

970Details

971 

972Run without persisting session rollout files to disk.

973 

974Key

975 

976`--full-auto`

977 

978Type / Values

979 

980`boolean`

981 

982Details

983 

984Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used.

985 

986Key

987 

988`--ignore-rules`

989 

990Type / Values

991 

992`boolean`

993 

994Details

995 

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

997 

998Key

999 

1000`--ignore-user-config`

1001 

1002Type / Values

1003 

1004`boolean`

1005 

1006Details

1007 

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

1009 

1010Key

1011 

1012`--image, -i`

1013 

1014Type / Values

1015 

1016`path[,path...]`

1017 

1018Details

1019 

1020Attach images to the first message. Repeatable; supports comma-separated lists.

1021 

1022Key

1023 

1024`--json, --experimental-json`

1025 

1026Type / Values

1027 

1028`boolean`

1029 

1030Details

1031 

1032Print newline-delimited JSON events instead of formatted text.

1033 

1034Key

1035 

1036`--model, -m`

1037 

1038Type / Values

1039 

1040`string`

1041 

1042Details

1043 

1044Override the configured model for this run.

1045 

1046Key

1047 

1048`--oss`

1049 

1050Type / Values

1051 

1052`boolean`

1053 

1054Details

1055 

1056Use the local open source provider (requires a running Ollama instance).

1057 

1058Key

1059 

1060`--output-last-message, -o`

1061 

1062Type / Values

1063 

1064`path`

1065 

1066Details

1067 

1068Write the assistant’s final message to a file. Useful for downstream scripting.

1069 

1070Key

1071 

1072`--output-schema`

1073 

1074Type / Values

1075 

1076`path`

1077 

1078Details

1079 

1080JSON Schema file describing the expected final response shape. Codex validates tool output against it.

1081 

1082Key

1083 

1084`--profile, -p`

1085 

1086Type / Values

1087 

1088`string`

1089 

1090Details

1091 

1092Select a configuration profile defined in config.toml.

1093 

1094Key

1095 

1096`--sandbox, -s`

1097 

1098Type / Values

1099 

1100`read-only | workspace-write | danger-full-access`

1101 

1102Details

1103 

1104Sandbox policy for model-generated commands. Defaults to configuration.

1105 

1106Key

1107 

1108`--skip-git-repo-check`

1109 

1110Type / Values

1111 

1112`boolean`