cli/reference.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-18 22:01 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 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];

4 880 

5## How to read this reference881## How to read this reference

6 882 

13 889 

14## Global flags890## Global flags

15 891 

16| Key | Type / Values | Details |892<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 893 

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

36 895When 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 896 

884`path`897## Command overview

885 898 

886Details899The Maturity column uses feature maturity labels such as Experimental, Beta,

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

901 interpret these labels.

887 902 

888Write the assistant’s final message to a file. Useful for downstream scripting.903<ConfigTable

904 client:load

905 options={commandOverview}

906 secondColumnTitle="Maturity"

907 secondColumnVariant="maturity"

908/>

889 909 

890Key910## Command details

891 911 

892`--output-schema`912### `codex` (interactive)

893 913 

894Type / Values914Running `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`.

895 915 

896`path`916Use `--remote ws://host:port` or `--remote wss://host:port` to connect the TUI to an app server started with `codex app-server --listen ws://IP:PORT`. Add `--remote-auth-token-env <ENV_VAR>` when the server requires a bearer token for WebSocket authentication.

897 917 

898Details918### `codex app-server`

899 919 

900JSON Schema file describing the expected final response shape. Codex validates tool output against it.920Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.

901 921 

902Key922<ConfigTable client:load options={appServerOptions} />

903 923 

904`--profile, -p`924`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior. `--listen ws://IP:PORT` enables WebSocket transport for app-server clients. The server accepts `ws://` listen URLs; use TLS termination or a secure proxy when clients connect with `wss://`. Use `--listen unix://` to accept WebSocket handshakes on Codex's default Unix socket, or `--listen unix:///absolute/path.sock` to choose a socket path. If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.

905 925 

906Type / Values926### `codex remote-control`

907 927 

908`string`928Ensure the app-server daemon is running with remote-control support enabled.

929Managed remote-control clients and SSH remote workflows use this command; it's

930not a replacement for `codex app-server --listen` when you are building a local

931protocol client.

909 932 

910Details933### `codex app`

911 934 

912Select a configuration profile defined in config.toml.935Launch Codex Desktop from the terminal on macOS or Windows. On macOS, Codex can open a specific workspace path; on Windows, Codex prints the path to open.

913 936 

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

915 938 

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

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

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

917 942 

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

919 944 

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

921 946 

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

923 948 

924Sandbox policy for model-generated commands. Defaults to configuration.949This debug flow initializes with `experimentalApi: true`, starts a thread, sends a turn, and streams server notifications. Use it to reproduce and inspect app-server protocol behavior locally.

925 950 

926Key951### `codex debug models`

927 952 

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

929 954 

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

931 956 

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

933 958 

934Details959### `codex apply`

935 960 

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

937 962 

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

939 964 

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

941 966 

942Type / Values967### `codex cloud`

943 968 

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

945 970 

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

947 972 

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

949 974 

950Key975#### `codex cloud list`

951 976 

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

953 978 

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

955 980 

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

957 982 

958Details983### `codex completion`

959 984 

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

961 986 

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

963 988 

964`Resume subcommand`989### `codex features`

965 990 

966Type / Values991Manage 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 992 

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