cli/reference.md Codex Docs, 2026-05-01 18:29 UTC → 2026-05-05 23:00 UTC

1# Command line options1# Command line options

2 2 

3export const globalFlagOptions = [

4 {

5 key: "PROMPT",

6 type: "string",

7 description:

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

9 },

10 {

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

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

13 description:

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

15 },

16 {

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

18 type: "string",

19 description:

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

21 },

22 {

23 key: "--oss",

24 type: "boolean",

25 defaultValue: "false",

26 description:

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

28 },

29 {

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

31 type: "string",

32 description:

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

34 },

35 {

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

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

38 description:

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

40 },

41 {

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

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

44 description:

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

46 },

47 {

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

49 type: "boolean",

50 defaultValue: "false",

51 description:

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

53 },

54 {

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

56 type: "path",

57 description:

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

59 },

60 {

61 key: "--search",

62 type: "boolean",

63 defaultValue: "false",

64 description:

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

66 },

67 {

68 key: "--add-dir",

69 type: "path",

70 description:

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

72 },

73 {

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

75 type: "boolean",

76 defaultValue: "false",

77 description:

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

79 },

80 {

81 key: "--remote",

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

83 description:

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

85 },

86 {

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

88 type: "ENV_VAR",

89 description:

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

91 },

92 {

93 key: "--enable",

94 type: "feature",

95 description:

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

97 },

98 {

99 key: "--disable",

100 type: "feature",

101 description:

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

103 },

104 {

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

106 type: "key=value",

107 description:

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

109 },

110];

111 

112export const commandOverview = [

113 {

114 key: "codex",

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

116 type: "stable",

117 description:

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

119 },

120 {

121 key: "codex app-server",

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

123 type: "experimental",

124 description:

125 "Launch the Codex app server for local development or debugging.",

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];

860 

3## How to read this reference861## How to read this reference

4 862 

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

11 869 

12## Global flags870## Global flags

13 871 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

33 

34Key

35 

36`--add-dir`

37 

38Type / Values

39 

40`path`

41 

42Details

43 

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

45 

46Key

47 

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

49 

50Type / Values

51 

52`untrusted | on-request | never`

53 

54Details

55 

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

57 

58Key

59 

60`--cd, -C`

61 

62Type / Values

63 

64`path`

65 

66Details

67 

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

69 

70Key

71 

72`--config, -c`

73 

74Type / Values

75 

76`key=value`

77 

78Details

79 

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

81 

82Key

83 

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

85 

86Type / Values

87 

88`boolean`

89 

90Details

91 

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

93 

94Key

95 

96`--disable`

97 

98Type / Values

99 

100`feature`

101 

102Details

103 

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

105 

106Key

107 

108`--enable`

109 

110Type / Values

111 

112`feature`

113 

114Details

115 

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

117 

118Key

119 

120`--image, -i`

121 

122Type / Values

123 

124`path[,path...]`

125 

126Details

127 

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

129 

130Key

131 

132`--model, -m`

133 

134Type / Values

135 

136`string`

137 

138Details

139 

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

141 

142Key

143 

144`--no-alt-screen`

145 

146Type / Values

147 

148`boolean`

149 

150Details

151 

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

153 

154Key

155 

156`--oss`

157 

158Type / Values

159 

160`boolean`

161 

162Details

163 

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

165 

166Key

167 

168`--profile, -p`

169 

170Type / Values

171 

172`string`

173 

174Details

175 

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

177 

178Key

179 

180`--remote`

181 

182Type / Values

183 

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

185 

186Details

187 

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

189 

190Key

191 

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

193 

194Type / Values

195 

196`ENV_VAR`

197 

198Details

199 

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

201 

202Key

203 

204`--sandbox, -s`

205 

206Type / Values

207 

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

209 

210Details

211 

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

213 

214Key

215 

216`--search`

217 

218Type / Values

219 

220`boolean`

221 

222Details

223 

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

225 

226Key

227 

228`PROMPT`

229 

230Type / Values

231 

232`string`

233 

234Details

235 

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

237 

238Expand to view all

239 

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

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

242 

243## Command overview

244 

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

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

247 interpret these labels.

248 

249| Key | Maturity | Details |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

271 

272Key

273 

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

275 

276Maturity

277 

278Stable

279 

280Details

281 

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

283 

284Key

285 

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

287 

288Maturity

289 

290Stable

291 

292Details

293 

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

295 

296Key

297 

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

299 

300Maturity

301 

302Experimental

303 

304Details

305 

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

307 

308Key

309 

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

311 

312Maturity

313 

314Stable

315 

316Details

317 

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

319 

320Key

321 

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

323 

324Maturity

325 

326Experimental

327 

328Details

329 

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

331 

332Key

333 

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

335 

336Maturity

337 

338Stable

339 

340Details

341 

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

343 

344Key

345 

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

347 

348Maturity

349 

350Experimental

351 

352Details

353 

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

355 

356Key

357 

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

359 

360Maturity

361 

362Experimental

363 

364Details

365 

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

367 

368Key

369 

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

371 

372Maturity

373 

374Stable

375 

376Details

377 

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

379 

380Key

381 

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

383 

384Maturity

385 

386Experimental

387 

388Details

389 

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

391 

392Key

393 

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

395 

396Maturity

397 

398Stable

399 

400Details

401 

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

403 

404Key

405 

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

407 

408Maturity

409 

410Stable

411 

412Details

413 

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

415 

416Key

417 

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

419 

420Maturity

421 

422Stable

423 

424Details

425 

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

427 

428Key

429 

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

431 

432Maturity

433 

434Stable

435 

436Details

437 

438Remove stored authentication credentials.

439 

440Key

441 

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

443 

444Maturity

445 

446Experimental

447 

448Details

449 

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

451 

452Key

453 

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

455 

456Maturity

457 

458Experimental

459 

460Details

461 

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

463 

464Key

465 

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

467 

468Maturity

469 

470Experimental

471 

472Details

473 

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

475 

476Key

477 

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

479 

480Maturity

481 

482Stable

483 

484Details

485 

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

487 

488Key

489 

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

491 

492Maturity

493 

494Experimental

495 

496Details

497 

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

499 

500Key

501 

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

503 

504Maturity

505 

506Stable

507 

508Details

509 

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

511 

512Expand to view all

513 

514## Command details

515 

516### `codex` (interactive)

517 

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

519 

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

521 

522### `codex app-server`

523 

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

525 

526| Key | Type / Values | Details |

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

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

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

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

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

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

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

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

535 

536Key

537 

538`--listen`

539 

540Type / Values

541 

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

543 

544Details

545 

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

547 

548Key

549 

550`--ws-audience`

551 

552Type / Values

553 

554`string`

555 

556Details

557 

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

559 

560Key

561 

562`--ws-auth`

563 

564Type / Values

565 

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

567 

568Details

569 

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

571 

572Key

573 

574`--ws-issuer`

575 

576Type / Values

577 

578`string`

579 

580Details

581 

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

583 

584Key

585 

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

587 

588Type / Values

589 

590`number`

591 

592Details

593 

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

595 

596Key

597 

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

599 

600Type / Values

601 

602`absolute path`

603 

604Details

605 

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

607 

608Key

609 

610`--ws-token-file`

611 

612Type / Values

613 

614`absolute path`

615 

616Details

617 

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

619 

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

621 

622### `codex app`

623 

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

625 

626| Key | Type / Values | Details |

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

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

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

630 

631Key

632 

633`--download-url`

634 

635Type / Values

636 

637`url`

638 

639Details

640 

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

642 

643Key

644 

645`PATH`

646 

647Type / Values

648 

649`path`

650 

651Details

652 

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

654 

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

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

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

658 

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

660 

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

662 

663| Key | Type / Values | Details |

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

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

666 

667Key

668 

669`USER_MESSAGE`

670 

671Type / Values

672 

673`string`

674 

675Details

676 

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

678 

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

680 

681### `codex debug models`

682 

683Print the raw model catalog Codex sees as JSON.

684 

685| Key | Type / Values | Details |

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

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

688 

689Key

690 

691`--bundled`

692 

693Type / Values

694 

695`boolean`

696 

697Details

698 

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

700 

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

702 

703### `codex apply`

704 

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

706 

707| Key | Type / Values | Details |

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

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

710 

711Key

712 

713`TASK_ID`

714 

715Type / Values

716 

717`string`

718 

719Details

720 

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

722 

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

724 

725### `codex cloud`

726 

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

728 

729| Key | Type / Values | Details |

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

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

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

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

734 

735Key

736 

737`--attempts`

738 

739Type / Values

740 

741`1-4`

742 

743Details

744 

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

746 

747Key

748 

749`--env`

750 

751Type / Values

752 

753`ENV_ID`

754 

755Details

756 

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

758 

759Key

760 

761`QUERY`

762 

763Type / Values

764 

765`string`

766 

767Details

768 

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

770 

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

772 

773#### `codex cloud list`

774 

775List recent cloud tasks with optional filtering and pagination.

776 

777| Key | Type / Values | Details |

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

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

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

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

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

783 

784Key

785 

786`--cursor`

787 

788Type / Values

789 

790`string`

791 

792Details

793 

794Pagination cursor returned by a previous request.

795 

796Key

797 

798`--env`

799 

800Type / Values

801 

802`ENV_ID`

803 

804Details

805 

806Filter tasks by environment identifier.

807 

808Key

809 

810`--json`

811 

812Type / Values

813 

814`boolean`

815 

816Details

817 

818Emit machine-readable JSON instead of plain text.

819 

820Key

821 

822`--limit`

823 

824Type / Values

825 

826`1-20`

827 

828Details

829 

830Maximum number of tasks to return.

831 

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

833 

834### `codex completion`

835 

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

837 

838| Key | Type / Values | Details |

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

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

841 

842Key

843 

844`SHELL`

845 

846Type / Values

847 

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

849 

850Details

851 

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

853 

854### `codex features`

855 

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

857 

858| Key | Type / Values | Details |

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

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

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

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

863 

864Key

865 

866`Disable subcommand`

867 

868Type / Values

869 

870`codex features disable <feature>`

871 

872Details

873 

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

875 

876Key

877 

878`Enable subcommand`

879 

880Type / Values

881 

882`codex features enable <feature>`

883 

884Details

885 

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

887 

888Key

889 

890`List subcommand`

891 

892Type / Values

893 

894`codex features list`

895 

896Details

897 

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

899 

900### `codex exec`

901 

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

903 

904| Key | Type / Values | Details |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

925 

926Key

927 

928`--cd, -C`

929 

930Type / Values

931 

932`path`

933 

934Details

935 

936Set the workspace root before executing the task.

937 

938Key

939 

940`--color`

941 

942Type / Values

943 

944`always | never | auto`

945 

946Details

947 

948Control ANSI color in stdout.

949 

950Key

951 

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

953 

954Type / Values

955 

956`boolean`

957 

958Details

959 

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

961 

962Key

963 

964`--ephemeral`

965 

966Type / Values

967 

968`boolean`

969 

970Details

971 

972Run without persisting session rollout files to disk.

973 

974Key

975 

976`--full-auto`

977 

978Type / Values

979 

980`boolean`

981 

982Details

983 

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

985 

986Key

987 

988`--ignore-rules`

989 

990Type / Values

991 

992`boolean`

993 

994Details

995 

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

997 

998Key

999 

1000`--ignore-user-config`

1001 

1002Type / Values

1003 

1004`boolean`

1005 

1006Details

1007 

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

1009 

1010Key

1011 

1012`--image, -i`

1013 

1014Type / Values

1015 

1016`path[,path...]`

1017 

1018Details

1019 

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

1021 

1022Key

1023 

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

1025 

1026Type / Values

1027 

1028`boolean`

1029 

1030Details

1031 

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

1033 

1034Key

1035 

1036`--model, -m`

1037 

1038Type / Values

1039 

1040`string`

1041 

1042Details

1043 

1044Override the configured model for this run.

1045 

1046Key

1047 

1048`--oss`

1049 

1050Type / Values

1051 

1052`boolean`

1053 

1054Details

1055 

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

1057 

1058Key

1059 

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

1061 

1062Type / Values

1063 

1064`path`

1065 

1066Details

1067 

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

1069 

1070Key

1071 

1072`--output-schema`

1073 

1074Type / Values

1075 

1076`path`

1077 

1078Details

1079 

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

1081 

1082Key

1083 

1084`--profile, -p`

1085 

1086Type / Values

1087 

1088`string`

1089 

1090Details

1091 

1092Select a configuration profile defined in config.toml.

1093 

1094Key

1095 

1096`--sandbox, -s`

1097 

1098Type / Values

1099 

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

1101 

1102Details

1103 

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

1105 

1106Key

1107 

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

1109 

1110Type / Values

1111 

1112`boolean`

1113 

1114Details

1115 

1116Allow running outside a Git repository (useful for one-off directories).

1117 

1118Key

1119 

1120`-c, --config`

1121 

1122Type / Values

1123 

1124`key=value`

1125 

1126Details

1127 

1128Inline configuration override for the non-interactive run (repeatable).

1129 

1130Key

1131 

1132`PROMPT`

1133 

1134Type / Values

1135 

1136`string | - (read stdin)`