cli/reference.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-12 01:59 UTC

1# Command line options1# Command line options

2 2 

3Options and flags for the Codex terminal client3export 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.",

126 },

127 {

128 key: "codex app",

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

130 type: "stable",

131 description:

132 "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.",

133 },

134 {

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

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

137 type: "experimental",

138 description:

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

140 },

141 {

142 key: "codex debug models",

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

144 type: "experimental",

145 description:

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

147 },

148 {

149 key: "codex apply",

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

151 type: "stable",

152 description:

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

154 },

155 {

156 key: "codex cloud",

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

158 type: "experimental",

159 description:

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

161 },

162 {

163 key: "codex completion",

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

165 type: "stable",

166 description:

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

168 },

169 {

170 key: "codex features",

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

172 type: "stable",

173 description:

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

175 },

176 {

177 key: "codex exec",

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

179 type: "stable",

180 description:

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

182 },

183 {

184 key: "codex execpolicy",

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

186 type: "experimental",

187 description:

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

189 },

190 {

191 key: "codex login",

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

193 type: "stable",

194 description:

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

196 },

197 {

198 key: "codex logout",

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

200 type: "stable",

201 description: "Remove stored authentication credentials.",

202 },

203 {

204 key: "codex mcp",

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

206 type: "experimental",

207 description:

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

209 },

210 {

211 key: "codex plugin marketplace",

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

213 type: "experimental",

214 description:

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

216 },

217 {

218 key: "codex mcp-server",

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

220 type: "experimental",

221 description:

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

223 },

224 {

225 key: "codex resume",

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

227 type: "stable",

228 description:

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

230 },

231 {

232 key: "codex fork",

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

234 type: "stable",

235 description:

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

237 },

238 {

239 key: "codex sandbox",

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

241 type: "experimental",

242 description:

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

244 },

245 {

246 key: "codex update",

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

248 type: "stable",

249 description:

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

251 },

252];

253 

254export const execOptions = [

255 {

256 key: "PROMPT",

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

258 description:

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

260 },

261 {

262 key: "--image, -i",

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

264 description:

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

266 },

267 {

268 key: "--model, -m",

269 type: "string",

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

271 },

272 {

273 key: "--oss",

274 type: "boolean",

275 defaultValue: "false",

276 description:

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

278 },

279 {

280 key: "--sandbox, -s",

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

282 description:

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

284 },

285 {

286 key: "--profile, -p",

287 type: "string",

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

289 },

290 {

291 key: "--full-auto",

292 type: "boolean",

293 defaultValue: "false",

294 description:

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

296 },

297 {

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

299 type: "boolean",

300 defaultValue: "false",

301 description:

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

303 },

304 {

305 key: "--cd, -C",

306 type: "path",

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

308 },

309 {

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

311 type: "boolean",

312 defaultValue: "false",

313 description:

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

315 },

316 {

317 key: "--ephemeral",

318 type: "boolean",

319 defaultValue: "false",

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

321 },

322 {

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

324 type: "boolean",

325 defaultValue: "false",

326 description:

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

328 },

329 {

330 key: "--ignore-rules",

331 type: "boolean",

332 defaultValue: "false",

333 description:

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

335 },

336 {

337 key: "--output-schema",

338 type: "path",

339 description:

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

341 },

342 {

343 key: "--color",

344 type: "always | never | auto",

345 defaultValue: "auto",

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

347 },

348 {

349 key: "--json, --experimental-json",

350 type: "boolean",

351 defaultValue: "false",

352 description:

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

354 },

355 {

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

357 type: "path",

358 description:

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

360 },

361 {

362 key: "Resume subcommand",

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

364 description:

365 "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.",

366 },

367 {

368 key: "-c, --config",

369 type: "key=value",

370 description:

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

372 },

373];

374 

375export const appServerOptions = [

376 {

377 key: "--listen",

378 type: "stdio:// | ws://IP:PORT",

379 defaultValue: "stdio://",

380 description:

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

382 },

383 {

384 key: "--ws-auth",

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

386 description:

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

388 },

389 {

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

391 type: "absolute path",

392 description:

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

394 },

395 {

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

397 type: "absolute path",

398 description:

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

400 },

401 {

402 key: "--ws-issuer",

403 type: "string",

404 description:

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

406 },

407 {

408 key: "--ws-audience",

409 type: "string",

410 description:

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

412 },

413 {

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

415 type: "number",

416 defaultValue: "30",

417 description:

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

419 },

420];

421 

422export const appOptions = [

423 {

424 key: "PATH",

425 type: "path",

426 defaultValue: ".",

427 description:

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

429 },

430 {

431 key: "--download-url",

432 type: "url",

433 description:

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

435 },

436];

437 

438export const debugAppServerSendMessageV2Options = [

439 {

440 key: "USER_MESSAGE",

441 type: "string",

442 description:

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

444 },

445];

446 

447export const debugModelsOptions = [

448 {

449 key: "--bundled",

450 type: "boolean",

451 defaultValue: "false",

452 description:

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

454 },

455];

456 

457export const resumeOptions = [

458 {

459 key: "SESSION_ID",

460 type: "uuid",

461 description:

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

463 },

464 {

465 key: "--last",

466 type: "boolean",

467 defaultValue: "false",

468 description:

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

470 },

471 {

472 key: "--all",

473 type: "boolean",

474 defaultValue: "false",

475 description:

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

477 },

478];

479 

480export const featuresOptions = [

481 {

482 key: "List subcommand",

483 type: "codex features list",

484 description:

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

486 },

487 {

488 key: "Enable subcommand",

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

490 description:

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

492 },

493 {

494 key: "Disable subcommand",

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

496 description:

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

498 },

499];

500 

501export const execResumeOptions = [

502 {

503 key: "SESSION_ID",

504 type: "uuid",

505 description:

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

507 },

508 {

509 key: "--last",

510 type: "boolean",

511 defaultValue: "false",

512 description:

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

514 },

515 {

516 key: "--all",

517 type: "boolean",

518 defaultValue: "false",

519 description:

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

521 },

522 {

523 key: "--image, -i",

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

525 description:

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

527 },

528 {

529 key: "PROMPT",

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

531 description:

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

533 },

534];

535 

536export const forkOptions = [

537 {

538 key: "SESSION_ID",

539 type: "uuid",

540 description:

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

542 },

543 {

544 key: "--last",

545 type: "boolean",

546 defaultValue: "false",

547 description:

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

549 },

550 {

551 key: "--all",

552 type: "boolean",

553 defaultValue: "false",

554 description:

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

556 },

557];

558 

559export const execpolicyOptions = [

560 {

561 key: "--rules, -r",

562 type: "path (repeatable)",

563 description:

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

565 },

566 {

567 key: "--pretty",

568 type: "boolean",

569 defaultValue: "false",

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

571 },

572 {

573 key: "COMMAND...",

574 type: "var-args",

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

576 },

577];

578 

579export const loginOptions = [

580 {

581 key: "--with-api-key",

582 type: "boolean",

583 description:

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

585 },

586 {

587 key: "--device-auth",

588 type: "boolean",

589 description:

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

591 },

592 {

593 key: "status subcommand",

594 type: "codex login status",

595 description:

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

597 },

598];

599 

600export const applyOptions = [

601 {

602 key: "TASK_ID",

603 type: "string",

604 description:

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

606 },

607];

608 

609export const sandboxMacOptions = [

610 {

611 key: "--permissions-profile",

612 type: "NAME",

613 description:

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

615 },

616 {

617 key: "--cd, -C",

618 type: "DIR",

619 description:

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

621 },

622 {

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

624 type: "boolean",

625 defaultValue: "false",

626 description:

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

628 },

629 {

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

631 type: "path",

632 description:

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

634 },

635 {

636 key: "--log-denials",

637 type: "boolean",

638 defaultValue: "false",

639 description:

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

641 },

642 {

643 key: "--config, -c",

644 type: "key=value",

645 description:

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

647 },

648 {

649 key: "COMMAND...",

650 type: "var-args",

651 description:

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

653 },

654];

655 

656export const sandboxLinuxOptions = [

657 {

658 key: "--permissions-profile",

659 type: "NAME",

660 description:

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

662 },

663 {

664 key: "--cd, -C",

665 type: "DIR",

666 description:

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

668 },

669 {

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

671 type: "boolean",

672 defaultValue: "false",

673 description:

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

675 },

676 {

677 key: "--config, -c",

678 type: "key=value",

679 description:

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

681 },

682 {

683 key: "COMMAND...",

684 type: "var-args",

685 description:

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

687 },

688];

689 

690export const sandboxWindowsOptions = [

691 {

692 key: "--permissions-profile",

693 type: "NAME",

694 description:

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

696 },

697 {

698 key: "--cd, -C",

699 type: "DIR",

700 description:

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

702 },

703 {

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

705 type: "boolean",

706 defaultValue: "false",

707 description:

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

709 },

710 {

711 key: "--config, -c",

712 type: "key=value",

713 description:

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

715 },

716 {

717 key: "COMMAND...",

718 type: "var-args",

719 description:

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

721 },

722];

723 

724export const completionOptions = [

725 {

726 key: "SHELL",

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

728 defaultValue: "bash",

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

730 },

731];

732 

733export const cloudExecOptions = [

734 {

735 key: "QUERY",

736 type: "string",

737 description:

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

739 },

740 {

741 key: "--env",

742 type: "ENV_ID",

743 description:

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

745 },

746 {

747 key: "--attempts",

748 type: "1-4",

749 defaultValue: "1",

750 description:

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

752 },

753];

754 

755export const cloudListOptions = [

756 {

757 key: "--env",

758 type: "ENV_ID",

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

760 },

761 {

762 key: "--limit",

763 type: "1-20",

764 defaultValue: "20",

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

766 },

767 {

768 key: "--cursor",

769 type: "string",

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

771 },

772 {

773 key: "--json",

774 type: "boolean",

775 defaultValue: "false",

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

777 },

778];

779 

780export const mcpCommands = [

781 {

782 key: "list",

783 type: "--json",

784 description:

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

786 },

787 {

788 key: "get <name>",

789 type: "--json",

790 description:

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

792 },

793 {

794 key: "add <name>",

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

796 description:

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

798 },

799 {

800 key: "remove <name>",

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

802 },

803 {

804 key: "login <name>",

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

806 description:

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

808 },

809 {

810 key: "logout <name>",

811 description:

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

813 },

814];

815 

816export const mcpAddOptions = [

817 {

818 key: "COMMAND...",

819 type: "stdio transport",

820 description:

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

822 },

823 {

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

825 type: "repeatable",

826 description:

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

828 },

829 {

830 key: "--url",

831 type: "https://…",

832 description:

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

834 },

835 {

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

837 type: "ENV_VAR",

838 description:

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

840 },

841];

842 

843export const marketplaceCommands = [

844 {

845 key: "add <source>",

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

847 description:

848 "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.",

849 },

850 {

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

852 description:

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

854 },

855 {

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

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

858 },

859];

4 860 

5## How to read this reference861## How to read this reference

6 862 

13 869 

14## Global flags870## Global flags

15 871 

16| Key | Type / Values | Details |872<ConfigTable client:load options={globalFlagOptions} />

17| --- | --- | --- |

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

19| `--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. |

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

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

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

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

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

25| `--full-auto` | `boolean` | Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`. |

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

27| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5-codex`). |

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

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

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

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| `PROMPT` | `string` | Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message. |

34 873 

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

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

37`--add-dir`

38 

39Type / Values

40 

41`path`

42 

43Details

44 

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

46 

47Key

48 

49`--ask-for-approval, -a`

50 

51Type / Values

52 

53`untrusted | on-request | never`

54 

55Details

56 

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

58 

59Key

60 

61`--cd, -C`

62 

63Type / Values

64 

65`path`

66 

67Details

68 

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

70 

71Key

72 

73`--config, -c`

74 

75Type / Values

76 

77`key=value`

78 

79Details

80 

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

82 

83Key

84 

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

86 

87Type / Values

88 

89`boolean`

90 

91Details

92 

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

94 

95Key

96 

97`--disable`

98 

99Type / Values

100 

101`feature`

102 

103Details

104 

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

106 

107Key

108 

109`--enable`

110 

111Type / Values

112 

113`feature`

114 

115Details

116 

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

118 

119Key

120 

121`--full-auto`

122 

123Type / Values

124 

125`boolean`

126 

127Details

128 

129Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`.

130 

131Key

132 

133`--image, -i`

134 

135Type / Values

136 

137`path[,path...]`

138 

139Details

140 

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

142 

143Key

144 

145`--model, -m`

146 

147Type / Values

148 

149`string`

150 

151Details

152 

153Override the model set in configuration (for example `gpt-5-codex`).

154 

155Key

156 

157`--no-alt-screen`

158 

159Type / Values

160 

161`boolean`

162 

163Details

164 

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

166 

167Key

168 

169`--oss`

170 

171Type / Values

172 

173`boolean`

174 

175Details

176 

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

178 

179Key

180 

181`--profile, -p`

182 

183Type / Values

184 

185`string`

186 

187Details

188 

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

190 

191Key

192 

193`--sandbox, -s`

194 

195Type / Values

196 

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

198 

199Details

200 

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

202 

203Key

204 

205`--search`

206 

207Type / Values

208 

209`boolean`

210 

211Details

212 

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

214 

215Key

216 

217`PROMPT`

218 

219Type / Values

220 

221`string`

222 

223Details

224 

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

226 

227Expand to view all

228 

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

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

231 

232## Command overview

233 

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

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

236 interpret these labels.

237 

238| Key | Maturity | Details |

239| --- | --- | --- |

240| [`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. |

241| [`codex app`](https://developers.openai.com/codex/cli/reference#codex-app) | Stable | Launch the Codex desktop app on macOS, optionally opening a specific workspace path. |

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

243| [`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`. |

244| [`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`. |

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

246| [`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. |

247| [`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. |

248| [`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. |

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

250| [`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. |

251| [`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. |

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

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

254| [`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. |

255| [`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. |

256| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS seatbelt or Linux sandboxes (Landlock by default, optional bubblewrap pipeline). |

257 

258Key

259 

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

261 

262Maturity

263 

264Stable

265 

266Details

267 

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

269 

270Key

271 

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

273 

274Maturity

275 

276Stable

277 

278Details

279 

280Launch the Codex desktop app on macOS, optionally opening a specific workspace path.

281 

282Key

283 

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

285 

286Maturity

287 

288Experimental

289 

290Details

291 

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

293 

294Key

295 

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

297 

298Maturity

299 

300Stable

301 

302Details

303 

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

305 

306Key

307 

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

309 

310Maturity

311 

312Experimental

313 

314Details

315 

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

317 

318Key

319 

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

321 

322Maturity

323 

324Stable

325 

326Details

327 

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

329 

330Key

331 

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

333 

334Maturity

335 

336Experimental

337 

338Details

339 

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

341 

342Key

343 

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

345 

346Maturity

347 

348Stable

349 

350Details

351 

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

353 

354Key

355 

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

357 

358Maturity

359 

360Experimental

361 

362Details

363 

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

365 

366Key

367 

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

369 

370Maturity

371 

372Stable

373 

374Details

375 

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

377 

378Key

379 

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

381 

382Maturity

383 

384Stable

385 

386Details

387 

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

389 

390Key

391 

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

393 

394Maturity

395 

396Stable

397 

398Details

399 

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

401 

402Key

403 

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

405 

406Maturity

407 

408Stable

409 

410Details

411 

412Remove stored authentication credentials.

413 

414Key

415 

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

417 

418Maturity

419 

420Experimental

421 

422Details

423 

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

425 

426Key

427 

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

429 

430Maturity

431 

432Experimental

433 

434Details

435 

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

437 

438Key

439 

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

441 

442Maturity

443 

444Stable

445 

446Details

447 

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

449 

450Key

451 

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

453 

454Maturity

455 

456Experimental

457 

458Details

459 

460Run arbitrary commands inside Codex-provided macOS seatbelt or Linux sandboxes (Landlock by default, optional bubblewrap pipeline).

461 

462Expand to view all

463 

464## Command details

465 

466### `codex` (interactive)

467 

468Running `codex` with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use `--search` to switch to live browsing and `--full-auto` to let Codex run most commands without prompts.

469 

470### `codex app-server`

471 

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

473 

474| Key | Type / Values | Details |

475| --- | --- | --- |

476| `--listen` | `stdio:// | ws://IP:PORT` | Transport listener URL. `ws://` is experimental and intended for development/testing. |

477 

478Key

479 

480`--listen`

481 

482Type / Values

483 

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

485 

486Details

487 

488Transport listener URL. `ws://` is experimental and intended for development/testing.

489 

490`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior. `--listen ws://IP:PORT` enables WebSocket transport (experimental). If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.

491 

492### `codex app`

493 

494Launch Codex Desktop from the terminal on macOS and optionally open a specific workspace path.

495 

496| Key | Type / Values | Details |

497| --- | --- | --- |

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

499| `PATH` | `path` | Workspace path to open in Codex Desktop (`codex app` is available on macOS only). |

500 

501Key

502 

503`--download-url`

504 

505Type / Values

506 

507`url`

508 

509Details

510 

511Advanced override for the Codex desktop DMG download URL used during install.

512 

513Key

514 

515`PATH`

516 

517Type / Values

518 

519`path`

520 

521Details

522 

523Workspace path to open in Codex Desktop (`codex app` is available on macOS only).

524 

525`codex app` installs/opens the desktop app on macOS, then opens the provided workspace path. This subcommand is macOS-only.

526 

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

528 

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

530 

531| Key | Type / Values | Details |

532| --- | --- | --- |

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

534 

535Key

536 

537`USER_MESSAGE`

538 

539Type / Values

540 

541`string`

542 

543Details

544 

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

546 

547This 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.

548 

549### `codex apply`

550 

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

552 

553| Key | Type / Values | Details |

554| --- | --- | --- |

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

556 

557Key

558 

559`TASK_ID`

560 

561Type / Values

562 

563`string`

564 

565Details

566 

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

568 

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

570 

571### `codex cloud`

572 

573Interact 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.

574 

575| Key | Type / Values | Details |

576| --- | --- | --- |

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

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

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

580 

581Key

582 

583`--attempts`

584 

585Type / Values

586 

587`1-4`

588 

589Details

590 

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

592 

593Key

594 

595`--env`

596 

597Type / Values

598 

599`ENV_ID`

600 

601Details

602 

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

604 

605Key

606 

607`QUERY`

608 

609Type / Values

610 

611`string`

612 

613Details

614 

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

616 

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

618 

619#### `codex cloud list`

620 

621List recent cloud tasks with optional filtering and pagination.

622 

623| Key | Type / Values | Details |

624| --- | --- | --- |

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

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

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

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

629 

630Key

631 

632`--cursor`

633 

634Type / Values

635 

636`string`

637 

638Details

639 

640Pagination cursor returned by a previous request.

641 

642Key

643 

644`--env`

645 

646Type / Values

647 

648`ENV_ID`

649 

650Details

651 

652Filter tasks by environment identifier.

653 

654Key

655 

656`--json`

657 

658Type / Values

659 

660`boolean`

661 

662Details

663 

664Emit machine-readable JSON instead of plain text.

665 

666Key

667 

668`--limit`

669 

670Type / Values

671 

672`1-20`

673 

674Details

675 

676Maximum number of tasks to return.

677 

678Plain-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`.

679 

680### `codex completion`

681 

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

683 

684| Key | Type / Values | Details |

685| --- | --- | --- |

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

687 

688Key

689 

690`SHELL`

691 

692Type / Values

693 

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

695 

696Details

697 

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

699 

700### `codex features`

701 

702Manage 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.

703 

704| Key | Type / Values | Details |

705| --- | --- | --- |

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

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

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

709 

710Key

711 

712`Disable subcommand`

713 

714Type / Values

715 

716`codex features disable <feature>`

717 

718Details

719 

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

721 

722Key

723 

724`Enable subcommand`

725 

726Type / Values

727 

728`codex features enable <feature>`

729 

730Details

731 

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

733 

734Key

735 

736`List subcommand`

737 

738Type / Values

739 

740`codex features list`

741 

742Details

743 

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

745 

746### `codex exec`

747 

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

749 

750| Key | Type / Values | Details |

751| --- | --- | --- |

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

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

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

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

756| `--full-auto` | `boolean` | Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals). |

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

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

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

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

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

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

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

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

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

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

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

768| `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. |

769 

770Key

771 

772`--cd, -C`

773 

774Type / Values

775 

776`path`

777 

778Details

779 

780Set the workspace root before executing the task.

781 

782Key

783 

784`--color`

785 

786Type / Values

787 

788`always | never | auto`

789 

790Details

791 

792Control ANSI color in stdout.

793 

794Key

795 

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

797 

798Type / Values

799 

800`boolean`

801 

802Details

803 

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

805 

806Key

807 

808`--ephemeral`

809 

810Type / Values

811 

812`boolean`

813 

814Details

815 

816Run without persisting session rollout files to disk.

817 

818Key

819 

820`--full-auto`

821 

822Type / Values

823 

824`boolean`

825 

826Details

827 

828Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals).

829 

830Key

831 

832`--image, -i`

833 

834Type / Values

835 

836`path[,path...]`

837 

838Details

839 

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

841 

842Key

843 

844`--json, --experimental-json`

845 

846Type / Values

847 

848`boolean`

849 

850Details

851 

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

853 

854Key

855 

856`--model, -m`

857 

858Type / Values

859 

860`string`

861 

862Details

863 

864Override the configured model for this run.

865 

866Key

867 

868`--oss`

869 

870Type / Values

871 

872`boolean`

873 

874Details

875 

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

877 

878Key

879 

880`--output-last-message, -o`

881 

882Type / Values

883 

884`path`

885 

886Details

887 876 

888Write the assistant’s final message to a file. Useful for downstream scripting.877## Command overview

889 878 

890Key879The Maturity column uses feature maturity labels such as Experimental, Beta,

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

881 interpret these labels.

891 882 

892`--output-schema`883<ConfigTable

884 client:load

885 options={commandOverview}

886 secondColumnTitle="Maturity"

887 secondColumnVariant="maturity"

888/>

893 889 

894Type / Values890## Command details

895 891 

896`path`892### `codex` (interactive)

897 893 

898Details894Running `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`.

899 895 

900JSON Schema file describing the expected final response shape. Codex validates tool output against it.896Use `--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.

901 897 

902Key898### `codex app-server`

903 899 

904`--profile, -p`900Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.

905 901 

906Type / Values902<ConfigTable client:load options={appServerOptions} />

907 903 

908`string`904`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.

909 905 

910Details906### `codex app`

911 907 

912Select a configuration profile defined in config.toml.908Launch 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.

913 909 

914Key910<ConfigTable client:load options={appOptions} />

915 911 

916`--sandbox, -s`912`codex app` opens an installed Codex Desktop app, or starts the installer when

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

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

917 915 

918Type / Values916### `codex debug app-server send-message-v2`

919 917 

920`read-only | workspace-write | danger-full-access`918Send one message through app-server's V2 thread/turn flow using the built-in app-server test client.

921 919 

922Details920<ConfigTable client:load options={debugAppServerSendMessageV2Options} />

923 921 

924Sandbox policy for model-generated commands. Defaults to configuration.922This 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.

925 923 

926Key924### `codex debug models`

927 925 

928`--skip-git-repo-check`926Print the raw model catalog Codex sees as JSON.

929 927 

930Type / Values928<ConfigTable client:load options={debugModelsOptions} />

931 929 

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

933 931 

934Details932### `codex apply`

935 933 

936Allow running outside a Git repository (useful for one-off directories).934Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.

937 935 

938Key936<ConfigTable client:load options={applyOptions} />

939 937 

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

941 939 

942Type / Values940### `codex cloud`

943 941 

944`key=value`942Interact 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.

945 943 

946Details944<ConfigTable client:load options={cloudExecOptions} />

947 945 

948Inline configuration override for the non-interactive run (repeatable).946Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.

949 947 

950Key948#### `codex cloud list`

951 949 

952`PROMPT`950List recent cloud tasks with optional filtering and pagination.

953 951 

954Type / Values952<ConfigTable client:load options={cloudListOptions} />

955 953 

956`string | - (read stdin)`954Plain-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`.

957 955 

958Details956### `codex completion`

959 957 

960Initial instruction for the task. Use `-` to pipe the prompt from stdin.958Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.

961 959 

962Key960<ConfigTable client:load options={completionOptions} />

963 961 

964`Resume subcommand`962### `codex features`

965 963 

966Type / Values964Manage 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.

967 965 

968`codex exec resume [SESSION_ID]`966<ConfigTable client:load options={featuresOptions} />

969 967 

970Details968### `codex exec`

971 969 

972Resume 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.970Use `codex exec` (or the short form `codex e`) for scripted or CI-style runs that should finish without human interaction.

973 971 

974Expand to view all972<ConfigTable client:load options={execOptions} />

975 973 

976Codex 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:974Codex 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:

977 975