1# Codex CLI features1# Codex CLI

2 2 

3Codex supports workflows beyond chat. Use this guide to learn what each one unlocks and when to use it.3<CodexCliLanding />

4 

5## Running in interactive mode

6 

7Codex launches into a full-screen terminal UI that can read your repository, make edits, and run commands as you iterate together. Use it whenever you want a conversational workflow where you can review Codex's actions in real time.

8 

9```bash

10codex

11```

12 

13You can also specify an initial prompt on the command line.

14 

15```bash

16codex "Explain this codebase to me"

17```

18 

19Once the session is open, you can:

20 

21- Send prompts, code snippets, or screenshots (see [image inputs](#image-inputs)) directly into the composer.

22- Watch Codex explain its plan before making a change, and approve or reject steps inline.

23- Read syntax-highlighted markdown code blocks and diffs in the TUI, then use `/theme` to preview and save a preferred theme.

24- Use `/clear` to wipe the terminal and start a fresh chat, or press <kbd>Ctrl</kbd>+<kbd>L</kbd> to clear the screen without starting a new conversation.

25- Use `/copy` or press <kbd>Ctrl</kbd>+<kbd>O</kbd> to copy the latest completed Codex output. If a turn is still running, Codex copies the most recent finished output instead of in-progress text.

26- Press <kbd>Tab</kbd> while Codex is running to queue follow-up text, slash commands, or `!` shell commands for the next turn.

27- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.

28- Press <kbd>Ctrl</kbd>+<kbd>R</kbd> to search prompt history from the composer, then press <kbd>Enter</kbd> to accept a match or <kbd>Esc</kbd> to cancel.

29- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.

30 

31## Resuming conversations

32 

33Codex stores your transcripts locally so you can pick up where you left off instead of repeating context. Use the `resume` subcommand when you want to reopen an earlier thread with the same repository state and instructions.

34 

35- `codex resume` launches a picker of recent interactive sessions. Highlight a run to see its summary and press <kbd>Enter</kbd> to reopen it.

36- `codex resume --all` shows sessions beyond the current working directory, so you can reopen any local run.

37- `codex resume --last` skips the picker and jumps straight to your most recent session from the current working directory (add `--all` to ignore the current working directory filter).

38- `codex resume <SESSION_ID>` targets a specific run. You can copy the ID from the picker, `/status`, or the files under `~/.codex/sessions/`.

39 

40Non-interactive automation runs can resume too:

41 

42```bash

43codex exec resume --last "Fix the race conditions you found"

44codex exec resume 7f9f9a2e-1b3c-4c7a-9b0e-.... "Implement the plan"

45```

46 

47Each resumed run keeps the original transcript, plan history, and approvals, so Codex can use prior context while you supply new instructions. Override the working directory with `--cd` or add extra roots with `--add-dir` if you need to steer the environment before resuming.

48 

49## Connect the TUI to a remote app server

50 

51Remote TUI mode lets you run the Codex app server on one machine and use the

52Codex terminal UI from another machine. Start the app server with a WebSocket

53listener:

54 

55```bash

56codex app-server --listen ws://127.0.0.1:4500

57```

58 

59Then connect the TUI to that endpoint:

60 

61```bash

62codex --remote ws://127.0.0.1:4500

63```

64 

65For access from another machine, bind the app server to a reachable interface

66and configure WebSocket auth before remote use:

67 

68```bash

69TOKEN_FILE="$HOME/.codex/app-server-token"

70openssl rand -base64 32 > "$TOKEN_FILE"

71chmod 600 "$TOKEN_FILE"

72codex app-server --listen ws://0.0.0.0:4500 --ws-auth capability-token --ws-token-file "$TOKEN_FILE"

73```

74 

75`--remote` accepts explicit `ws://host:port`, `wss://host:port`, `unix://`, and

76`unix://PATH` addresses. Use `unix://` for Codex's default local Unix socket or

77`unix://PATH` for an explicit local socket path. Plain WebSocket connections are

78appropriate for localhost and SSH port-forwarding workflows. For non-local

79clients, use WebSocket auth and put the connection behind TLS.

80 

81Codex supports these WebSocket authentication modes:

82 

83- Capability token: start the server with `--ws-auth capability-token` and

84 either `--ws-token-file /absolute/path` or `--ws-token-sha256 HEX`.

85- Signed bearer token: start the server with

86 `--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path`, plus

87 optional `--ws-issuer`, `--ws-audience`, and `--ws-max-clock-skew-seconds`.

88 

89The TUI sends the remote auth token as an `Authorization: Bearer <token>` header

90during the WebSocket handshake. Codex only accepts remote auth tokens over

91`wss://` URLs or local-only `ws://` URLs.

92 

93```bash

94export CODEX_REMOTE_TOKEN="$(cat "$TOKEN_FILE")"

95codex --remote wss://remote-host:4500 --remote-auth-token-env CODEX_REMOTE_TOKEN

96```

97 

98For SSH remote projects in the Codex app, use

99[Remote connections](https://developers.openai.com/codex/remote-connections). For managed remote-control

100clients, `codex remote-control` starts an app-server process with

101remote-control support enabled.

102 

103## Models and reasoning

104 

105For most tasks in Codex, `gpt-5.5` is the recommended model. It's OpenAI's newest frontier model for complex coding, computer

106use, knowledge work, and research workflows, with stronger planning, tool use,

107and follow-through on multi-step tasks. For extra fast tasks, ChatGPT Pro subscribers have

108access to the GPT-5.3-Codex-Spark model in research preview.

109 

110Switch models mid-session with the `/model` command, or specify one when launching the CLI.

111 

112```bash

113codex --model gpt-5.5

114```

115 

116 

117[Learn more about the models available in Codex](https://developers.openai.com/codex/models).

118 

119## Feature flags

120 

121Codex includes a small set of feature flags. Use the `features` subcommand to inspect what's available and to persist changes in your configuration.

122 

123```bash

124codex features list

125codex features enable unified_exec

126codex features disable shell_snapshot

127```

128 

129`codex features enable <feature>` and `codex features disable <feature>` write

130to `$CODEX_HOME/config.toml`. The `features` subcommand doesn't accept

131`--profile`.

132 

133## Subagents

134 

135Use Codex subagent workflows to parallelize larger tasks. For setup, role configuration (`[agents]` in `config.toml`), and examples, see [Subagents](https://developers.openai.com/codex/subagents).

136 

137Codex only spawns subagents when you explicitly ask it to. Because each

138subagent does its own model and tool work, subagent workflows consume more

139tokens than comparable single-agent runs.

140 

141## Image inputs

142 

143Attach screenshots or design specs so Codex can read image details alongside your prompt. You can paste images into the interactive composer or provide files on the command line.

144 

145```bash

146codex -i screenshot.png "Explain this error"

147```

148 

149```bash

150codex --image img1.png,img2.jpg "Summarize these diagrams"

151```

152 

153Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.

154 

155## Image generation

156 

157Ask Codex to generate or edit images directly in the CLI. This works well for assets such as icons, banners, illustrations, sprite sheets, and placeholder art. If you want Codex to transform or extend an existing asset, attach a reference image with your prompt.

158 

159You can ask in natural language or explicitly invoke the image generation skill by including `$imagegen` in your prompt.

160 

161Built-in image generation uses `gpt-image-2`, counts toward your general Codex usage limits, and uses included limits 3-5x faster on average than similar turns without image generation, depending on image quality and size. For details, see [Pricing](https://developers.openai.com/codex/pricing#image-generation-usage-limits). For prompting tips and model details, see the [image generation guide](https://developers.openai.com/api/docs/guides/image-generation).

162 

163For larger batches of image generation, set `OPENAI_API_KEY` in your environment variables and ask Codex to generate images through the API so API pricing applies instead.

164 

165## Syntax highlighting and themes

166 

167The TUI syntax-highlights fenced markdown code blocks and file diffs so code is easier to scan during reviews and debugging.

168 

169Use `/theme` to open the theme picker, preview themes live, and save your selection to `tui.theme` in `~/.codex/config.toml`. You can also add custom `.tmTheme` files under `$CODEX_HOME/themes` and select them in the picker.

170 

171## Running local code review

172 

173Type `/review` in the CLI to open Codex's review presets. The CLI launches a dedicated reviewer that reads the diff you select and reports prioritized, actionable findings without touching your working tree. By default it uses the current session model; set `review_model` in `config.toml` to override.

174 

175- **Review against a base branch** lets you pick a local branch; Codex finds the merge base against its upstream, diffs your work, and highlights the biggest risks before you open a pull request.

176- **Review uncommitted changes** inspects everything that's staged, not staged, or not tracked so you can address issues before committing.

177- **Review a commit** lists recent commits and has Codex read the exact change set for the SHA you choose.

178- **Custom review instructions** accepts your own wording (for example, "Focus on accessibility regressions") and runs the same reviewer with that prompt.

179 

180Each run shows up as its own turn in the transcript, so you can rerun reviews as the code evolves and compare the feedback.

181 

182## Web search

183 

184Codex ships with a first-party web search tool. For local tasks in the Codex CLI, Codex enables web search by default and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/agent-approvals-security), web search defaults to live results. To fetch the most recent data, pass `--search` for a single run or set `web_search = "live"` in [Config basics](https://developers.openai.com/codex/config-basic). You can also set `web_search = "disabled"` to turn the tool off.

185 

186You'll see `web_search` items in the transcript or `codex exec --json` output whenever Codex looks something up.

187 

188## Running with an input prompt

189 

190When you just need a quick answer, run Codex with a single prompt and skip the interactive UI.

191 

192```bash

193codex "explain this codebase"

194```

195 

196Codex will read the working directory, craft a plan, and stream the response back to your terminal before exiting. Pair this with flags like `--path` to target a specific directory or `--model` to dial in the behavior up front.

197 

198## Shell completions

199 

200Speed up everyday usage by installing the generated completion scripts for your shell:

201 

202```bash

203codex completion bash

204codex completion zsh

205codex completion fish

206```

207 

208Run the completion script in your shell configuration file to set up completions for new sessions. For example, if you use `zsh`, you can add the following to the end of your `~/.zshrc` file:

209 

210```bash

211# ~/.zshrc

212eval "$(codex completion zsh)"

213```

214 

215Start a new session, type `codex`, and press <kbd>Tab</kbd> to see the completions. If you see a `command not found: compdef` error, add `autoload -Uz compinit && compinit` to your `~/.zshrc` file before the `eval "$(codex completion zsh)"` line, then restart your shell.

216 

217## Approval modes

218 

219Approval modes define how much Codex can do without stopping for confirmation. Use `/permissions` inside an interactive session to switch modes as your comfort level changes.

220 

221- **Auto** (default) lets Codex read files, edit, and run commands within the working directory. It still asks before touching anything outside that scope or using the network.

222- **Read-only** keeps Codex in a consultative mode. It can browse files but won't make changes or run commands until you approve a plan.

223- **Full Access** grants Codex the ability to work across your machine, including network access, without asking. Use it sparingly and only when you trust the repository and task.

224 

225Codex always surfaces a transcript of its actions, so you can review or roll back changes with your usual git workflow.

226 

227## Scripting Codex

228 

229Automate workflows or wire Codex into your existing scripts with the `exec` subcommand. This runs Codex non-interactively, piping the final plan and results back to `stdout`.

230 

231```bash

232codex exec "fix the CI failure"

233```

234 

235Combine `exec` with shell scripting to build custom workflows, such as automatically updating changelogs, sorting issues, or enforcing editorial checks before a PR ships.

236 

237## Working with Codex cloud

238 

239The `codex cloud` command lets you triage and launch [Codex cloud tasks](https://developers.openai.com/codex/cloud) without leaving the terminal. Run it with no arguments to open an interactive picker, browse active or finished tasks, and apply the changes to your local project.

240 

241You can also start a task directly from the terminal:

242 

243```bash

244codex cloud exec --env ENV_ID "Summarize open bugs"

245```

246 

247Add `--attempts` (1–4) to request best-of-N runs when you want Codex cloud to generate more than one solution. For example, `codex cloud exec --env ENV_ID --attempts 3 "Summarize open bugs"`.

248 

249Environment IDs come from your Codex cloud configuration—use `codex cloud` and press <kbd>Ctrl</kbd>+<kbd>O</kbd> to choose an environment or the web dashboard to confirm the exact value. Authentication follows your existing CLI login, and the command exits non-zero if submission fails so you can wire it into scripts or CI.

250 

251## Slash commands

252 

253Slash commands give you quick access to specialized workflows like `/review`, `/fork`, `/side`, or your own reusable prompts. Codex ships with a curated set of built-ins, and you can create custom ones for team-specific tasks or personal shortcuts.

254 

255See the [slash commands guide](https://developers.openai.com/codex/guides/slash-commands) to browse the catalog of built-ins, learn how to author custom commands, and understand where they live on disk.

256 

257## Prompt editor

258 

259When you're drafting a longer prompt, it can be easier to switch to a full editor and then send the result back to the composer.

260 

261In the prompt input, press <kbd>Ctrl</kbd>+<kbd>G</kbd> to open the editor defined by the `VISUAL` environment variable (or `EDITOR` if `VISUAL` isn't set).

262 

263## Model Context Protocol (MCP)

264 

265Connect Codex to more tools by configuring Model Context Protocol servers. Add STDIO or streaming HTTP servers in `~/.codex/config.toml`, or manage them with the `codex mcp` CLI commands—Codex launches them automatically when a session starts and exposes their tools next to the built-ins. You can even run Codex itself as an MCP server when you need it inside another agent.

266 

267See [Model Context Protocol](https://developers.openai.com/codex/mcp) for example configurations, supported auth flows, and a more detailed guide.

268 

269## Tips and shortcuts

270 

271- Type `@` in the composer to open a fuzzy file search over the workspace root; press <kbd>Tab</kbd> or <kbd>Enter</kbd> to drop the highlighted path into your message.

272- Press <kbd>Enter</kbd> while Codex is running to inject new instructions into the current turn, or press <kbd>Tab</kbd> to queue follow-up input for the next turn. Queued input can be a normal prompt, a slash command such as `/review`, or a `!` shell command. Codex parses queued slash commands when they run.

273- Prefix a line with `!` to run a local shell command (for example, `!ls`). Codex treats the output like a user-provided command result and still applies your approval and sandbox settings.

274- Tap <kbd>Esc</kbd> twice while the composer is empty to edit your previous user message. Continue pressing <kbd>Esc</kbd> to walk further back in the transcript, then hit <kbd>Enter</kbd> to fork from that point.

275- Launch Codex from any directory using `codex --cd <path>` to set the working root without running `cd` first. The active path appears in the TUI header.

276- Expose more writable roots with `--add-dir` (for example, `codex --cd apps/frontend --add-dir ../backend --add-dir ../shared`) when you need to coordinate changes across more than one project.

277- Make sure your environment is already set up before launching Codex so it doesn't spend tokens probing what to activate. For example, source your Python virtual environment (or other language environments), start any required daemons, and export the environment variables you expect to use ahead of time.