cli/reference.md Codex Docs, 2026-04-29 00:50 UTC → 2026-05-18 22:01 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 over stdio, WebSocket, or a Unix socket.",

126 126 },

127Details127 {

128 128 key: "codex remote-control",

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

130 130 type: "experimental",

131Key131 description:

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

133`--image, -i`133 },

134 134 {

135Type / Values135 key: "codex app",

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

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

138 138 description:

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

140 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 app-server send-message-v2",

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

144 144 type: "experimental",

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

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

147Type / Values147 },

148 148 {

149`string`149 key: "codex debug models",

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

151Details151 type: "experimental",

152 152 description:

153Override the model set in configuration (for example `gpt-5.4`).153 "Print the raw model catalog Codex sees, including an option to inspect only the bundled catalog.",

154 154 },

155Key155 {

156 156 key: "codex apply",

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

158 158 type: "stable",

159Type / Values159 description:

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

161`boolean`161 },

162 162 {

163Details163 key: "codex cloud",

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

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

166 166 description:

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

168 168 },

169`--oss`169 {

170 170 key: "codex completion",

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

172 172 type: "stable",

173`boolean`173 description:

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

175Details175 },

176 176 {

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

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

179Key179 type: "stable",

180 180 description:

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

182 182 },

183Type / Values183 {

184 184 key: "codex exec",

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

186 186 type: "stable",

187Details187 description:

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

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

190 190 {

191Key191 key: "codex execpolicy",

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

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

194 194 description:

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

196 196 },

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

198 198 key: "codex login",

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

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:

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

203Key203 },

204 204 {

205`--remote-auth-token-env`205 key: "codex logout",

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

207Type / Values207 type: "stable",

208 208 description: "Remove stored authentication credentials.",

209`ENV_VAR`209 },

210 210 {

211Details211 key: "codex mcp",

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

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 "Manage Model Context Protocol servers (list, add, remove, authenticate).",

216 216 },

217`--sandbox, -s`217 {

218 218 key: "codex plugin marketplace",

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

220 220 type: "experimental",

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

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

223Details223 },

224 224 {

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

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

227Key227 type: "experimental",

228 228 description:

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

230 230 },

231Type / Values231 {

232 232 key: "codex resume",

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

234 234 type: "stable",

235Details235 description:

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

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

238 238 {

239Key239 key: "codex fork",

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

241`PROMPT`241 type: "stable",

242 242 description:

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

244 244 },

245`string`245 {

246 246 key: "codex sandbox",

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

248 248 type: "experimental",

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

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

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 key: "codex update",

254When you run a subcommand, place global flags after it (for example, `codex exec --oss ...`) so Codex applies them as intended.254 href: "/codex/cli/reference#codex-update",

255 255 type: "stable",

256## Command overview256 description:

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

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

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

260 interpret these labels.260 

261 261export const execOptions = [

262| Key | Maturity | Details |262 {

263| --- | --- | --- |263 key: "PROMPT",

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 type: "string | - (read stdin)",

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

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 "Initial instruction for the task. Use `-` to pipe the prompt from stdin.",

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 {

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

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 type: "path[,path...]",

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

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

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 },

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 {

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

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

277| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |277 description: "Override the configured model for this run.",

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: "--oss",

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: "boolean",

282 282 defaultValue: "false",

283Key283 description:

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

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

286 286 {

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

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

289Stable289 description:

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

291Details291 },

292 292 {

293Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.293 key: "--profile, -p",

294 294 type: "string",

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

296 296 },

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

298 298 key: "--full-auto",

299Maturity299 type: "boolean",

300 300 defaultValue: "false",

301Stable301 description:

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

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: "--dangerously-bypass-approvals-and-sandbox, --yolo",

306 306 type: "boolean",

307Key307 defaultValue: "false",

308 308 description:

309[`codex app-server`](https://developers.openai.com/codex/cli/reference#codex-app-server)309 "Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.",

310 310 },

311Maturity311 {

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

313Experimental313 type: "path",

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

315Details315 },

316 316 {

317Launch the Codex app server for local development or debugging.317 key: "--skip-git-repo-check",

318 318 type: "boolean",

319Key319 defaultValue: "false",

320 320 description:

321[`codex apply`](https://developers.openai.com/codex/cli/reference#codex-apply)321 "Allow running outside a Git repository (useful for one-off directories).",

322 322 },

323Maturity323 {

324 324 key: "--ephemeral",

325Stable325 type: "boolean",

326 326 defaultValue: "false",

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

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-user-config",

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 `$CODEX_HOME/config.toml`. Authentication still uses `CODEX_HOME`.",

335Maturity335 },

336 336 {

337Experimental337 key: "--ignore-rules",

338 338 type: "boolean",

339Details339 defaultValue: "false",

340 340 description:

341Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.341 "Do not load user or project execpolicy `.rules` files for this run.",

342 342 },

343Key343 {

344 344 key: "--output-schema",

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

346 346 description:

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

348 348 },

349Stable349 {

350 350 key: "--color",

351Details351 type: "always | never | auto",

352 352 defaultValue: "auto",

353Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.353 description: "Control ANSI color in stdout.",

354 354 },

355Key355 {

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

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

358 358 defaultValue: "false",

359Maturity359 description:

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

361Experimental361 },

362 362 {

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

364 364 type: "path",

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

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

367Key367 },

368 368 {

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

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

371Maturity371 description:

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

373Stable373 },

374 374 {

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

376 376 type: "key=value",

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

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

379Key379 },

380 380];

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

382 382export const appServerOptions = [

383Maturity383 {

384 384 key: "--listen",

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

386 386 defaultValue: "stdio://",

387Details387 description:

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

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

390 390 {

391Key391 key: "--ws-auth",

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

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

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

395Maturity395 },

396 396 {

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

398 398 type: "absolute path",

399Details399 description:

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

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

402 402 {

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

404 404 type: "absolute path",

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

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

407Maturity407 },

408 408 {

409Stable409 key: "--ws-issuer",

410 410 type: "string",

411Details411 description:

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

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

414 414 {

415Key415 key: "--ws-audience",

416 416 type: "string",

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

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

419Maturity419 },

420 420 {

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

422 422 type: "number",

423Details423 defaultValue: "30",

424 424 description:

425Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.425 "Clock skew allowance when validating signed bearer token `exp` and `nbf` claims. Requires `--ws-auth signed-bearer-token`.",

426 426 },

427Key427 {

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

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

430 430 defaultValue: "false",

431Maturity431 description:

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

433Stable433 },

434 434];

435Details435 

436 436export const appOptions = [

437Remove stored authentication credentials.437 {

438 438 key: "PATH",

439Key439 type: "path",

440 440 defaultValue: ".",

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

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

443Maturity443 },

444 444 {

445Experimental445 key: "--download-url",

446 446 type: "url",

447Details447 description:

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

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

450 450];

451Key451 

452 452export const debugAppServerSendMessageV2Options = [

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

454 454 key: "USER_MESSAGE",

455Maturity455 type: "string",

456 456 description:

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

458 458 },

459Details459];

460 460 

461Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.461export const debugModelsOptions = [

462 462 {

463Key463 key: "--bundled",

464 464 type: "boolean",

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

466 466 description:

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

468 468 },

469Experimental469];

470 470 

471Details471export const resumeOptions = [

472 472 {

473Add, upgrade, or remove plugin marketplaces from Git or local sources.473 key: "SESSION_ID",

474 474 type: "uuid",

475Key475 description:

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

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

478 478 {

479Maturity479 key: "--last",

480 480 type: "boolean",

481Stable481 defaultValue: "false",

482 482 description:

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

484 484 },

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

486 486 key: "--all",

487Key487 type: "boolean",

488 488 defaultValue: "false",

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

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

491Maturity491 },

492 492];

493Experimental493 

494 494export const featuresOptions = [

495Details495 {

496 496 key: "List subcommand",

497Run arbitrary commands inside Codex-provided macOS seatbelt or Linux bubblewrap sandboxes.497 type: "codex features list",

498 498 description:

499Expand to view all499 "Show known feature flags, their maturity stage, and their effective state.",

500 500 },

501## Command details501 {

502 502 key: "Enable subcommand",

503### `codex` (interactive)503 type: "codex features enable <feature>",

504 504 description:

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 "Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.",

506 506 },

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 key: "Disable subcommand",

509### `codex app-server`509 type: "codex features disable <feature>",

510 510 description:

511Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.511 "Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.",

512 512 },

513| Key | Type / Values | Details |513];

514| --- | --- | --- |514 

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

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

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 key: "SESSION_ID",

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

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 "Resume the specified session. Omit and use `--last` to continue 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: "--last",

524 524 type: "boolean",

525`--listen`525 defaultValue: "false",

526 526 description:

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

528 528 },

529`stdio:// | ws://IP:PORT`529 {

530 530 key: "--all",

531Details531 type: "boolean",

532 532 defaultValue: "false",

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

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

535Key535 },

536 536 {

537`--ws-audience`537 key: "--image, -i",

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

539Type / Values539 description:

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

541`string`541 },

542 542 {

543Details543 key: "PROMPT",

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

545Expected `aud` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.545 description:

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

547Key547 },

548 548];

549`--ws-auth`549 

550 550export const forkOptions = [

551Type / Values551 {

552 552 key: "SESSION_ID",

553`capability-token | signed-bearer-token`553 type: "uuid",

554 554 description:

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

556 556 },

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

558 558 key: "--last",

559Key559 type: "boolean",

560 560 defaultValue: "false",

561`--ws-issuer`561 description:

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

563Type / Values563 },

564 564 {

565`string`565 key: "--all",

566 566 type: "boolean",

567Details567 defaultValue: "false",

568 568 description:

569Expected `iss` claim for signed bearer tokens. Requires `--ws-auth signed-bearer-token`.569 "Show sessions beyond the current working directory in the picker.",

570 570 },

571Key571];

572 572 

573`--ws-max-clock-skew-seconds`573export const execpolicyOptions = [

574 574 {

575Type / Values575 key: "--rules, -r",

576 576 type: "path (repeatable)",

577`number`577 description:

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

579Details579 },

580 580 {

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

582 582 type: "boolean",

583Key583 defaultValue: "false",

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

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

586 586 {

587Type / Values587 key: "COMMAND...",

588 588 type: "var-args",

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

590 590 },

591Details591];

592 592 

593File containing the HMAC shared secret used to validate signed JWT bearer tokens. Required with `--ws-auth signed-bearer-token`.593export const loginOptions = [

594 594 {

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

596 596 type: "boolean",

597`--ws-token-file`597 description:

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

599Type / Values599 },

600 600 {

601`absolute path`601 key: "--with-access-token",

602 602 type: "boolean",

603Details603 description:

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

605File containing the shared capability token. Required with `--ws-auth capability-token`.605 },

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 key: "--device-auth",

608 608 type: "boolean",

609### `codex app`609 description:

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

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 },

612 612 {

613| Key | Type / Values | Details |613 key: "status subcommand",

614| --- | --- | --- |614 type: "codex login status",

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

616| `PATH` | `path` | Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path. |616 "Print the active authentication mode and exit with 0 when logged in.",

617 617 },

618Key618];

619 619 

620`--download-url`620export const applyOptions = [

621 621 {

622Type / Values622 key: "TASK_ID",

623 623 type: "string",

624`url`624 description:

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

626Details626 },

627 627];

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

629 629export const sandboxMacOptions = [

630Key630 {

631 631 key: "--permissions-profile",

632`PATH`632 type: "NAME",

633 633 description:

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

635 635 },

636`path`636 {

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

638Details638 type: "DIR",

639 639 description:

640Workspace path for Codex Desktop. On macOS, Codex opens this path; on Windows, Codex prints the path.640 "Working directory used for profile resolution and command execution. Requires `--permissions-profile`.",

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: "--include-managed-config",

644Windows, it prints the path to open after installation.644 type: "boolean",

645 645 defaultValue: "false",

646### `codex debug app-server send-message-v2`646 description:

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

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

649 649 {

650| Key | Type / Values | Details |650 key: "--allow-unix-socket",

651| --- | --- | --- |651 type: "path",

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

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

654Key654 },

655 655 {

656`USER_MESSAGE`656 key: "--log-denials",

657 657 type: "boolean",

658Type / Values658 defaultValue: "false",

659 659 description:

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

661 661 },

662Details662 {

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

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

665 665 description:

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 "Pass configuration overrides into the sandboxed run (repeatable).",

667 667 },

668### `codex apply`668 {

669 669 key: "COMMAND...",

670Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.670 type: "var-args",

671 671 description:

672| Key | Type / Values | Details |672 "Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.",

673| --- | --- | --- |673 },

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

675 675 

676Key676export const sandboxLinuxOptions = [

677 677 {

678`TASK_ID`678 key: "--permissions-profile",

679 679 type: "NAME",

680Type / Values680 description:

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

682`string`682 },

683 683 {

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

685 685 type: "DIR",

686Identifier of the Codex Cloud task whose diff should be applied.686 description:

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

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

689 689 {

690### `codex cloud`690 key: "--include-managed-config",

691 691 type: "boolean",

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 defaultValue: "false",

693 693 description:

694| Key | Type / Values | Details |694 "Include managed requirements while resolving an explicit permissions profile. Requires `--permissions-profile`.",

695| --- | --- | --- |695 },

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 key: "--config, -c",

698| `QUERY` | `string` | Task prompt. If omitted, Codex prompts interactively for details. |698 type: "key=value",

699 699 description:

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

701 701 },

702`--attempts`702 {

703 703 key: "COMMAND...",

704Type / Values704 type: "var-args",

705 705 description:

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

707 707 },

708Details708];

709 709 

710Number of assistant attempts (best-of-N) Codex Cloud should run.710export const sandboxWindowsOptions = [

711 711 {

712Key712 key: "--permissions-profile",

713 713 type: "NAME",

714`--env`714 description:

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

716Type / Values716 },

717 717 {

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

719 719 type: "DIR",

720Details720 description:

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

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

723 723 {

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

725 725 type: "boolean",

726`QUERY`726 defaultValue: "false",

727 727 description:

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

729 729 },

730`string`730 {

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

732Details732 type: "key=value",

733 733 description:

734Task prompt. If omitted, Codex prompts interactively for details.734 "Configuration overrides applied before launching the sandbox (repeatable).",

735 735 },

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

737 737 key: "COMMAND...",

738#### `codex cloud list`738 type: "var-args",

739 739 description:

740List recent cloud tasks with optional filtering and pagination.740 "Command to execute under the native Windows sandbox. Provide the executable after `--`.",

741 741 },

742| Key | Type / Values | Details |742];

743| --- | --- | --- |743 

744| `--cursor` | `string` | Pagination cursor returned by a previous request. |744export const completionOptions = [

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

746| `--json` | `boolean` | Emit machine-readable JSON instead of plain text. |746 key: "SHELL",

747| `--limit` | `1-20` | Maximum number of tasks to return. |747 type: "bash | zsh | fish | power-shell | elvish",

748 748 defaultValue: "bash",

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

750 750 },

751`--cursor`751];

752 752 

753Type / Values753export const cloudExecOptions = [

754 754 {

755`string`755 key: "QUERY",

756 756 type: "string",

757Details757 description:

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

759Pagination cursor returned by a previous request.759 },

760 760 {

761Key761 key: "--env",

762 762 type: "ENV_ID",

763`--env`763 description:

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

765Type / Values765 },

766 766 {

767`ENV_ID`767 key: "--attempts",

768 768 type: "1-4",

769Details769 defaultValue: "1",

770 770 description:

771Filter tasks by environment identifier.771 "Number of assistant attempts (best-of-N) Codex Cloud should run.",

772 772 },

773Key773];

774 774 

775`--json`775export const cloudListOptions = [

776 776 {

777Type / Values777 key: "--env",

778 778 type: "ENV_ID",

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

780 780 },

781Details781 {

782 782 key: "--limit",

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

784 784 defaultValue: "20",

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

786 786 },

787`--limit`787 {

788 788 key: "--cursor",

789Type / Values789 type: "string",

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

791`1-20`791 },

792 792 {

793Details793 key: "--json",

794 794 type: "boolean",

795Maximum number of tasks to return.795 defaultValue: "false",

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

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 },

798 798];

799### `codex completion`799 

800 800export const mcpCommands = [

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

802 802 key: "list",

803| Key | Type / Values | Details |803 type: "--json",

804| --- | --- | --- |804 description:

805| `SHELL` | `bash | zsh | fish | power-shell | elvish` | Shell to generate completions for. Output prints to stdout. |805 "List configured MCP servers. Add `--json` for machine-readable output.",

806 806 },

807Key807 {

808 808 key: "get <name>",

809`SHELL`809 type: "--json",

810 810 description:

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

812 812 },

813`bash | zsh | fish | power-shell | elvish`813 {

814 814 key: "add <name>",

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

816 816 description:

817Shell to generate completions for. Output prints to stdout.817 "Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports.",

818 818 },

819### `codex features`819 {

820 820 key: "remove <name>",

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 description: "Delete a stored MCP server definition.",

822 822 },

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

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

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

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 "Start an OAuth login for a streamable HTTP server (servers that support OAuth only).",

828 828 },

829Key829 {

830 830 key: "logout <name>",

831`Disable subcommand`831 description:

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

833Type / Values833 },

834 834];

835`codex features disable <feature>`835 

836 836export const mcpAddOptions = [

837Details837 {

838 838 key: "COMMAND...",

839Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.839 type: "stdio transport",

840 840 description:

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

842 842 },

843`Enable subcommand`843 {

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

845Type / Values845 type: "repeatable",

846 846 description:

847`codex features enable <feature>`847 "Environment variable assignments applied when launching a stdio server.",

848 848 },

849Details849 {

850 850 key: "--url",

851Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.851 type: "https://…",

852 852 description:

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

854 854 },

855`List subcommand`855 {

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

857Type / Values857 type: "ENV_VAR",

858 858 description:

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

860 860 },

861Details861];

862 862 

863Show known feature flags, their maturity stage, and their effective state.863export const marketplaceCommands = [

864 864 {

865### `codex exec`865 key: "add <source>",

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

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