cli/reference.md Codex Docs, 2026-04-24 12:28 UTC → 2026-05-07 20:02 UTC

1# Command line options1# Command line options

2 2 

3## How to read this reference3export const globalFlagOptions = [

4 4 {

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.5 key: "PROMPT",

6 6 type: "string",

7The CLI inherits most defaults from <code>~/.codex/config.toml</code>. Any7 description:

8 <code>-c key=value</code> overrides you pass at the command line take8 "Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.",

9 precedence for that invocation. See [Config9 },

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

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

12## Global flags12 type: "path[,path...]",

13 13 description:

14| Key | Type / Values | Details |14 "Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.",

15| --- | --- | --- |15 },

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

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. |17 key: "--model, -m",

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

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

20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |20 "Override the model set in configuration (for example `gpt-5.4`).",

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

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

23| `--full-auto` | `boolean` | Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`. |23 key: "--oss",

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

25| `--model, -m` | `string` | Override the model set in configuration (for example `gpt-5.4`). |25 defaultValue: "false",

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

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

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

29| `--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 {

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

31| `--sandbox, -s` | `read-only | workspace-write | danger-full-access` | Select the sandbox policy for model-generated shell commands. |31 type: "string",

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

33| `PROMPT` | `string` | Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message. |33 "Configuration profile name to load from `~/.codex/config.toml`.",

34 34 },

35Key35 {

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

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

38 38 description:

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

40 40 },

41`path`41 {

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

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

44 44 description:

45Grant additional directories write access alongside the main workspace. Repeat for multiple paths.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 46 },

47Key47 {

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

49`--ask-for-approval, -a`49 type: "boolean",

50 50 defaultValue: "false",

51Type / Values51 description:

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

53`untrusted | on-request | never`53 },

54 54 {

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

56 56 type: "path",

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.57 description:

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

59Key59 },

60 60 {

61`--cd, -C`61 key: "--search",

62 62 type: "boolean",

63Type / Values63 defaultValue: "false",

64 64 description:

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

66 66 },

67Details67 {

68 68 key: "--add-dir",

69Set the working directory for the agent before it starts processing your request.69 type: "path",

70 70 description:

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

72 72 },

73`--config, -c`73 {

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

75Type / Values75 type: "boolean",

76 76 defaultValue: "false",

77`key=value`77 description:

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

79Details79 },

80 80 {

81Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.81 key: "--remote",

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

83Key83 description:

84 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`--dangerously-bypass-approvals-and-sandbox, --yolo`85 },

86 86 {

87Type / Values87 key: "--remote-auth-token-env",

88 88 type: "ENV_VAR",

89`boolean`89 description:

90 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`.",

91Details91 },

92 92 {

93Run every command without approvals or sandboxing. Only use inside an externally hardened environment.93 key: "--enable",

94 94 type: "feature",

95Key95 description:

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

97`--disable`97 },

98 98 {

99Type / Values99 key: "--disable",

100 100 type: "feature",

101`feature`101 description:

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

103Details103 },

104 104 {

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

106 106 type: "key=value",

107Key107 description:

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

109`--enable`109 },

110 110];

111Type / Values111 

112 112export const commandOverview = [

113`feature`113 {

114 114 key: "codex",

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

116 116 type: "stable",

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

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

119Key119 },

120 120 {

121`--full-auto`121 key: "codex app-server",

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

123Type / Values123 type: "experimental",

124 124 description:

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

126 126 },

127Details127 {

128 128 key: "codex app",

129Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`.129 href: "/codex/cli/reference#codex-app",

130 130 type: "stable",

131Key131 description:

132 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`--image, -i`133 },

134 134 {

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

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

137`path[,path...]`137 type: "experimental",

138 138 description:

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

140 140 },

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

142 142 key: "codex debug models",

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

144 144 type: "experimental",

145`--model, -m`145 description:

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

147Type / Values147 },

148 148 {

149`string`149 key: "codex apply",

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

151Details151 type: "stable",

152 152 description:

153Override the model set in configuration (for example `gpt-5.4`).153 "Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.",

154 154 },

155Key155 {

156 156 key: "codex cloud",

157`--no-alt-screen`157 href: "/codex/cli/reference#codex-cloud",

158 158 type: "experimental",

159Type / Values159 description:

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

161`boolean`161 },

162 162 {

163Details163 key: "codex completion",

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

165Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run).165 type: "stable",

166 166 description:

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

168 168 },

169`--oss`169 {

170 170 key: "codex features",

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

172 172 type: "stable",

173`boolean`173 description:

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

175Details175 },

176 176 {

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

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

179Key179 type: "stable",

180 180 description:

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

182 182 },

183Type / Values183 {

184 184 key: "codex execpolicy",

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

186 186 type: "experimental",

187Details187 description:

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

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

190 190 {

191Key191 key: "codex login",

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

193`--remote`193 type: "stable",

194 194 description:

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

196 196 },

197`ws://host:port | wss://host:port`197 {

198 198 key: "codex logout",

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

200 200 type: "stable",

201Connect the interactive TUI to a remote app-server WebSocket endpoint. Supported for `codex`, `codex resume`, and `codex fork`; other subcommands reject remote mode.201 description: "Remove stored authentication credentials.",

202 202 },

203Key203 {

204 204 key: "codex mcp",

205`--remote-auth-token-env`205 href: "/codex/cli/reference#codex-mcp",

206 206 type: "experimental",

207Type / Values207 description:

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

209`ENV_VAR`209 },

210 210 {

211Details211 key: "codex plugin marketplace",

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

213Read 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`.213 type: "experimental",

214 214 description:

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

216 216 },

217`--sandbox, -s`217 {

218 218 key: "codex mcp-server",

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

220 220 type: "experimental",

221`read-only | workspace-write | danger-full-access`221 description:

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

223Details223 },

224 224 {

225Select the sandbox policy for model-generated shell commands.225 key: "codex resume",

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

227Key227 type: "stable",

228 228 description:

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

230 230 },

231Type / Values231 {

232 232 key: "codex fork",

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

234 234 type: "stable",

235Details235 description:

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

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

238 238 {

239Key239 key: "codex sandbox",

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

241`PROMPT`241 type: "experimental",

242 242 description:

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

244 244 },

245`string`245 {

246 246 key: "codex update",

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

248 248 type: "stable",

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

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

251Expand to view all251 },

252 252];

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

254When you run a subcommand, place global flags after it (for example, `codex exec --oss ...`) so Codex applies them as intended.254export const execOptions = [

255 255 {

256## Command overview256 key: "PROMPT",

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

258The Maturity column uses feature maturity labels such as Experimental, Beta,258 description:

259 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to259 "Initial instruction for the task. Use `-` to pipe the prompt from stdin.",

260 interpret these labels.260 },

261 261 {

262| Key | Maturity | Details |262 key: "--image, -i",

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

264| [`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. |264 description:

265| [`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. |265 "Attach images to the first message. Repeatable; supports comma-separated lists.",

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

267| [`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`. |267 {

268| [`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`. |268 key: "--model, -m",

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

270| [`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. |270 description: "Override the configured model for this run.",

271| [`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. |271 },

272| [`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. |272 {

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

274| [`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. |274 type: "boolean",

275| [`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. |275 defaultValue: "false",

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

277| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |277 "Use the local open source provider (requires a running Ollama instance).",

278| [`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. |278 },

279| [`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. |279 {

280| [`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. |280 key: "--sandbox, -s",

281| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes. |281 type: "read-only | workspace-write | danger-full-access",

282 282 description:

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

284 284 },

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

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

287Maturity287 type: "string",

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

289Stable289 },

290 290 {

291Details291 key: "--full-auto",

292 292 type: "boolean",

293Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.293 defaultValue: "false",

294 294 description:

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

296 296 },

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

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

299Maturity299 type: "boolean",

300 300 defaultValue: "false",

301Stable301 description:

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

303Details303 },

304 304 {

305Launch the Codex desktop app on macOS or Windows. On macOS, Codex can open a workspace path; on Windows, Codex prints the path to open.305 key: "--cd, -C",

306 306 type: "path",

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

308 308 },

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

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

311Maturity311 type: "boolean",

312 312 defaultValue: "false",

313Experimental313 description:

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

315Details315 },

316 316 {

317Launch the Codex app server for local development or debugging.317 key: "--ephemeral",

318 318 type: "boolean",

319Key319 defaultValue: "false",

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

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

322 322 {

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

324 324 type: "boolean",

325Stable325 defaultValue: "false",

326 326 description:

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

328 328 },

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

330 330 key: "--ignore-rules",

331Key331 type: "boolean",

332 332 defaultValue: "false",

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

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

335Maturity335 },

336 336 {

337Experimental337 key: "--output-schema",

338 338 type: "path",

339Details339 description:

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

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

342 342 {

343Key343 key: "--color",

344 344 type: "always | never | auto",

345[`codex completion`](https://developers.openai.com/codex/cli/reference#codex-completion)345 defaultValue: "auto",

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

347Maturity347 },

348 348 {

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

350 350 type: "boolean",

351Details351 defaultValue: "false",

352 352 description:

353Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.353 "Print newline-delimited JSON events instead of formatted text.",

354 354 },

355Key355 {

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

357[`codex debug app-server send-message-v2`](https://developers.openai.com/codex/cli/reference#codex-debug-app-server-send-message-v2)357 type: "path",

358 358 description:

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

360 360 },

361Experimental361 {

362 362 key: "Resume subcommand",

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

364 364 description:

365Debug app-server by sending a single V2 message through the built-in test client.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 366 },

367Key367 {

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

369[`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec)369 type: "key=value",

370 370 description:

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

372 372 },

373Stable373];

374 374 

375Details375export const appServerOptions = [

376 376 {

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

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

379Key379 defaultValue: "stdio://",

380 380 description:

381[`codex execpolicy`](https://developers.openai.com/codex/cli/reference#codex-execpolicy)381 "Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients.",

382 382 },

383Maturity383 {

384 384 key: "--ws-auth",

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

386 386 description:

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

388 388 },

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

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

391Key391 type: "absolute path",

392 392 description:

393[`codex features`](https://developers.openai.com/codex/cli/reference#codex-features)393 "File containing the shared capability token. Required with `--ws-auth capability-token`.",

394 394 },

395Maturity395 {

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

397Stable397 type: "absolute path",

398 398 description:

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

400 400 },

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

402 402 key: "--ws-issuer",

403Key403 type: "string",

404 404 description:

405[`codex fork`](https://developers.openai.com/codex/cli/reference#codex-fork)405 "Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.",

406 406 },

407Maturity407 {

408 408 key: "--ws-audience",

409Stable409 type: "string",

410 410 description:

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

412 412 },

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

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

415Key415 type: "number",

416 416 defaultValue: "30",

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

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

419Maturity419 },

420 420];

421Stable421 

422 422export const appOptions = [

423Details423 {

424 424 key: "PATH",

425Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.425 type: "path",

426 426 defaultValue: ".",

427Key427 description:

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

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

430 430 {

431Maturity431 key: "--download-url",

432 432 type: "url",

433Stable433 description:

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

435Details435 },

436 436];

437Remove stored authentication credentials.437 

438 438export const debugAppServerSendMessageV2Options = [

439Key439 {

440 440 key: "USER_MESSAGE",

441[`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp)441 type: "string",

442 442 description:

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

444 444 },

445Experimental445];

446 446 

447Details447export const debugModelsOptions = [

448 448 {

449Manage Model Context Protocol servers (list, add, remove, authenticate).449 key: "--bundled",

450 450 type: "boolean",

451Key451 defaultValue: "false",

452 452 description:

453[`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server)453 "Skip refresh and print only the model catalog bundled with the current Codex binary.",

454 454 },

455Maturity455];

456 456 

457Experimental457export const resumeOptions = [

458 458 {

459Details459 key: "SESSION_ID",

460 460 type: "uuid",

461Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.461 description:

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

463Key463 },

464 464 {

465[`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace)465 key: "--last",

466 466 type: "boolean",

467Maturity467 defaultValue: "false",

468 468 description:

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

470 470 },

471Details471 {

472 472 key: "--all",

473Add, upgrade, or remove plugin marketplaces from Git or local sources.473 type: "boolean",

474 474 defaultValue: "false",

475Key475 description:

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

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

478 478];

479Maturity479 

480 480export const featuresOptions = [

481Stable481 {

482 482 key: "List subcommand",

483Details483 type: "codex features list",

484 484 description:

485Continue a previous interactive session by ID or resume the most recent conversation.485 "Show known feature flags, their maturity stage, and their effective state.",

486 486 },

487Key487 {

488 488 key: "Enable subcommand",

489[`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox)489 type: "codex features enable <feature>",

490 490 description:

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

492 492 },

493Experimental493 {

494 494 key: "Disable subcommand",

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

496 496 description:

497Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes.497 "Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.",

498 498 },

499Expand to view all499];

500 500 

501## Command details501export const execResumeOptions = [

502 502 {

503### `codex` (interactive)503 key: "SESSION_ID",

504 504 type: "uuid",

505Running `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.505 description:

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

507Use `--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.507 },

508 508 {

509### `codex app-server`509 key: "--last",

510 510 type: "boolean",

511Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.511 defaultValue: "false",

512 512 description:

513| Key | Type / Values | Details |513 "Resume the most recent conversation from the current working directory.",

514| --- | --- | --- |514 },

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

516| `--ws-audience` | `string` | Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |516 key: "--all",

517| `--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. |517 type: "boolean",

518| `--ws-issuer` | `string` | Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`. |518 defaultValue: "false",

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

520| `--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`. |520 "Include sessions outside the current working directory when selecting the most recent session.",

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

522 522 {

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

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

525`--listen`525 description:

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

527Type / Values527 },

528 528 {

529`stdio:// | ws://IP:PORT`529 key: "PROMPT",

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

531Details531 description:

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

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

534 534];

535Key535 

536 536export const forkOptions = [

537`--ws-audience`537 {

538 538 key: "SESSION_ID",

539Type / Values539 type: "uuid",

540 540 description:

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

542 542 },

543Details543 {

544 544 key: "--last",

545Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.545 type: "boolean",

546 546 defaultValue: "false",

547Key547 description:

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

549`--ws-auth`549 },

550 550 {

551Type / Values551 key: "--all",

552 552 type: "boolean",

553`capability-token | signed-bearer-token`553 defaultValue: "false",

554 554 description:

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

556 556 },

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

558 558 

559Key559export const execpolicyOptions = [

560 560 {

561`--ws-issuer`561 key: "--rules, -r",

562 562 type: "path (repeatable)",

563Type / Values563 description:

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

565`string`565 },

566 566 {

567Details567 key: "--pretty",

568 568 type: "boolean",

569Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.569 defaultValue: "false",

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

571Key571 },

572 572 {

573`--ws-max-clock-skew-seconds`573 key: "COMMAND...",

574 574 type: "var-args",

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

576 576 },

577`number`577];

578 578 

579Details579export const loginOptions = [

580 580 {

581Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.581 key: "--with-api-key",

582 582 type: "boolean",

583Key583 description:

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

585`--ws-shared-secret-file`585 },

586 586 {

587Type / Values587 key: "--device-auth",

588 588 type: "boolean",

589`absolute path`589 description:

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

591Details591 },

592 592 {

593File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.593 key: "status subcommand",

594 594 type: "codex login status",

595Key595 description:

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

597`--ws-token-file`597 },

598 598];

599Type / Values599 

600 600export const applyOptions = [

601`absolute path`601 {

602 602 key: "TASK_ID",

603Details603 type: "string",

604 604 description:

605File containing the shared capability token. Required with `--ws-auth capability-token`.605 "Identifier of the Codex Cloud task whose diff should be applied.",

606 606 },

607`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.607];

608 608 

609### `codex app`609export const sandboxMacOptions = [

610 610 {

611Launch 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.611 key: "--permissions-profile",

612 612 type: "NAME",

613| Key | Type / Values | Details |613 description:

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

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

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

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

618Key618 type: "DIR",

619 619 description:

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

621 621 },

622Type / Values622 {

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

624`url`624 type: "boolean",

625 625 defaultValue: "false",

626Details626 description:

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

628Advanced override for the Codex desktop installer URL used during install.628 },

629 629 {

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

631 631 type: "path",

632`PATH`632 description:

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

634Type / Values634 },

635 635 {

636`path`636 key: "--log-denials",

637 637 type: "boolean",

638Details638 defaultValue: "false",

639 639 description:

640Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.640 "Capture macOS sandbox denials with `log stream` while the command runs and print them after exit.",

641 641 },

642`codex app` opens an installed Codex Desktop app, or starts the installer when642 {

643the app is missing. On macOS, Codex opens the provided workspace path; on643 key: "--config, -c",

644Windows, it prints the path to open after installation.644 type: "key=value",

645 645 description:

646### `codex debug app-server send-message-v2`646 "Pass configuration overrides into the sandboxed run (repeatable).",

647 647 },

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

649 649 key: "COMMAND...",

650| Key | Type / Values | Details |650 type: "var-args",

651| --- | --- | --- |651 description:

652| `USER_MESSAGE` | `string` | Message text sent to app-server through the built-in V2 test-client flow. |652 "Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.",

653 653 },

654Key654];

655 655 

656`USER_MESSAGE`656export const sandboxLinuxOptions = [

657 657 {

658Type / Values658 key: "--permissions-profile",

659 659 type: "NAME",

660`string`660 description:

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

662Details662 },

663 663 {

664Message text sent to app-server through the built-in V2 test-client flow.664 key: "--cd, -C",

665 665 type: "DIR",

666This 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.666 description:

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

668### `codex apply`668 },

669 669 {

670Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.670 key: "--include-managed-config",

671 671 type: "boolean",

672| Key | Type / Values | Details |672 defaultValue: "false",

673| --- | --- | --- |673 description:

674| `TASK_ID` | `string` | Identifier of the Codex Cloud task whose diff should be applied. |674 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",

675 675 },

676Key676 {

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

678`TASK_ID`678 type: "key=value",

679 679 description:

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

681 681 },

682`string`682 {

683 683 key: "COMMAND...",

684Details684 type: "var-args",

685 685 description:

686Identifier of the Codex Cloud task whose diff should be applied.686 "Command to execute under Landlock + seccomp. Provide the executable after `--`.",

687 687 },

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

689 689 

690### `codex cloud`690export const sandboxWindowsOptions = [

691 691 {

692Interact 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.692 key: "--permissions-profile",

693 693 type: "NAME",

694| Key | Type / Values | Details |694 description:

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

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

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

698| `QUERY` | `string` | Task prompt. If omitted, Codex prompts interactively for details. |698 key: "--cd, -C",

699 699 type: "DIR",

700Key700 description:

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

702`--attempts`702 },

703 703 {

704Type / Values704 key: "--include-managed-config",

705 705 type: "boolean",

706`1-4`706 defaultValue: "false",

707 707 description:

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

709 709 },

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

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

712Key712 type: "key=value",

713 713 description:

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

715 715 },

716Type / Values716 {

717 717 key: "COMMAND...",

718`ENV_ID`718 type: "var-args",

719 719 description:

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

721 721 },

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

723 723 

724Key724export const completionOptions = [

725 725 {

726`QUERY`726 key: "SHELL",

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

728Type / Values728 defaultValue: "bash",

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

730`string`730 },

731 731];

732Details732 

733 733export const cloudExecOptions = [

734Task prompt. If omitted, Codex prompts interactively for details.734 {

735 735 key: "QUERY",

736Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.736 type: "string",

737 737 description:

738#### `codex cloud list`738 "Task prompt. If omitted, Codex prompts interactively for details.",

739 739 },

740List recent cloud tasks with optional filtering and pagination.740 {

741 741 key: "--env",

742| Key | Type / Values | Details |742 type: "ENV_ID",

743| --- | --- | --- |743 description:

744| `--cursor` | `string` | Pagination cursor returned by a previous request. |744 "Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.",

745| `--env` | `ENV_ID` | Filter tasks by environment identifier. |745 },

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

747| `--limit` | `1-20` | Maximum number of tasks to return. |747 key: "--attempts",

748 748 type: "1-4",

749Key749 defaultValue: "1",

750 750 description:

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

752 752 },

753Type / Values753];

754 754 

755`string`755export const cloudListOptions = [

756 756 {

757Details757 key: "--env",

758 758 type: "ENV_ID",

759Pagination cursor returned by a previous request.759 description: "Filter tasks by environment identifier.",

760 760 },

761Key761 {

762 762 key: "--limit",

763`--env`763 type: "1-20",

764 764 defaultValue: "20",

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

766 766 },

767`ENV_ID`767 {

768 768 key: "--cursor",

769Details769 type: "string",

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

771Filter tasks by environment identifier.771 },

772 772 {

773Key773 key: "--json",

774 774 type: "boolean",

775`--json`775 defaultValue: "false",

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

777Type / Values777 },

778 778];

779`boolean`779 

780 780export const mcpCommands = [

781Details781 {

782 782 key: "list",

783Emit machine-readable JSON instead of plain text.783 type: "--json",

784 784 description:

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

786 786 },

787`--limit`787 {

788 788 key: "get <name>",

789Type / Values789 type: "--json",

790 790 description:

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

792 792 },

793Details793 {

794 794 key: "add <name>",

795Maximum number of tasks to return.795 type: "-- <command...> | --url <value>",

796 796 description:

797Plain-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`.797 "Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports.",

798 798 },

799### `codex completion`799 {

800 800 key: "remove <name>",

801Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.801 description: "Delete a stored MCP server definition.",

802 802 },

803| Key | Type / Values | Details |803 {

804| --- | --- | --- |804 key: "login <name>",

805| `SHELL` | `bash | zsh | fish | power-shell | elvish` | Shell to generate completions for. Output prints to stdout. |805 type: "--scopes scope1,scope2",

806 806 description:

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

808 808 },

809`SHELL`809 {

810 810 key: "logout <name>",

811Type / Values811 description:

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

813`bash | zsh | fish | power-shell | elvish`813 },

814 814];

815Details815 

816 816export const mcpAddOptions = [

817Shell to generate completions for. Output prints to stdout.817 {

818 818 key: "COMMAND...",

819### `codex features`819 type: "stdio transport",

820 820 description:

821Manage 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.821 "Executable plus arguments to launch the MCP server. Provide after `--`.",

822 822 },

823| Key | Type / Values | Details |823 {

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

825| `Disable subcommand` | `codex features disable <feature>` | Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided. |825 type: "repeatable",

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

827| `List subcommand` | `codex features list` | Show known feature flags, their maturity stage, and their effective state. |827 "Environment variable assignments applied when launching a stdio server.",

828 828 },

829Key829 {

830 830 key: "--url",

831`Disable subcommand`831 type: "https://…",

832 832 description:

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

834 834 },

835`codex features disable <feature>`835 {

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

837Details837 type: "ENV_VAR",

838 838 description:

839Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.839 "Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.",

840 840 },

841Key841];

842 842 

843`Enable subcommand`843export const marketplaceCommands = [

844 844 {

845Type / Values845 key: "add <source>",

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

847`codex features enable <feature>`847 description:

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

849Details849 },

850 850 {

851Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.851 key: "upgrade [marketplace-name]",

852 852 description:

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

854 854 },

855`List subcommand`855 {

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

857Type / Values857 description: "Remove a configured plugin marketplace.",

858 858 },

859`codex features list`859];

860 

861Details