cli/features.md Codex Docs, 2026-03-31 06:35 UTC → 2026-04-23 18:31 UTC

22- Watch Codex explain its plan before making a change, and approve or reject steps inline.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.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.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` 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.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.

26- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.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.

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

28 30 

29## Resuming conversations31## Resuming conversations

44 46 

45Each 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.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.

46 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 Codex terminal UI from another machine. This is useful when the code, credentials, or execution environment live on a remote host, but you want the local interactive TUI experience.

52 

53Start the app server on the machine that should own the workspace and run commands:

54 

55```bash

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

57```

58 

59Then connect from the machine running the TUI:

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, for example:

66 

67```bash

68codex app-server --listen ws://0.0.0.0:4500

69```

70 

71`--remote` accepts explicit `ws://host:port` and `wss://host:port` addresses only. For plain WebSocket connections, prefer local-host addresses or SSH port forwarding. If you expose the listener beyond the local host, configure authentication before real remote use and put authenticated non-local connections behind TLS.

72 

73Codex supports these WebSocket authentication modes for remote TUI connections:

74 

75- **No WebSocket auth**: Best for local-host listeners or SSH port-forwarded connections. Codex can start non-local listeners without auth, but logs a warning and the startup banner reminds you to configure auth before real remote use.

76- **Capability token**: Store a shared token in a file on the app-server host, start the server with `--ws-auth capability-token --ws-token-file /abs/path/to/token`, then set the same token in an environment variable on the TUI host and pass `--remote-auth-token-env <ENV_VAR>`.

77- **Signed bearer token**: Store an HMAC shared secret in a file on the app-server host, start the server with `--ws-auth signed-bearer-token --ws-shared-secret-file /abs/path/to/secret`, and have the TUI send a signed JWT bearer token through `--remote-auth-token-env <ENV_VAR>`. The shared secret must be at least 32 bytes. Signed tokens use HS256 and must include `exp`; Codex also validates `nbf`, `iss`, and `aud` when those claims or server options are present.

78 

79To create a capability token on the app-server host, generate a random token file with permissions that only your user can read:

80 

81```bash

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

83install -d -m 700 "$(dirname "$TOKEN_FILE")"

84openssl rand -base64 32 > "$TOKEN_FILE"

85chmod 600 "$TOKEN_FILE"

86```

87 

88Treat the token file like a password, and regenerate it if it leaks.

89 

90Then start the app server with that token file. For example, with a capability token behind a TLS proxy:

91 

92```bash

93# Remote host

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

95codex app-server \

96 --listen ws://0.0.0.0:4500 \

97 --ws-auth capability-token \

98 --ws-token-file "$TOKEN_FILE"

99 

100# TUI host

101export CODEX_REMOTE_AUTH_TOKEN="$(ssh devbox 'cat ~/.codex/codex-app-server-token')"

102codex --remote wss://codex-devbox.example.com:4500 \

103 --remote-auth-token-env CODEX_REMOTE_AUTH_TOKEN

104```

105 

106The TUI sends remote auth tokens as `Authorization: Bearer <token>` during the WebSocket handshake. Codex only sends those tokens over `wss://` URLs or `ws://` URLs whose host is `localhost`, `127.0.0.1`, or `::1`, so put non-local remote listeners behind TLS if clients need to authenticate over the network.

107 

47## Models and reasoning108## Models and reasoning

48 109 

49For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the110For most tasks in Codex, `gpt-5.5` is the recommended model when it is

50industry-leading coding capabilities of `gpt-5.3-codex` to OpenAI’s flagship111available. It is OpenAI's newest frontier model for complex coding, computer

51frontier model, combining frontier coding performance with stronger reasoning,112use, knowledge work, and research workflows, with stronger planning, tool use,

52native computer use, and broader professional workflows. For extra fast tasks,113and follow-through on multi-step tasks. If `gpt-5.5` is not yet available,

53ChatGPT Pro subscribers have access to the GPT-5.3-Codex-Spark model in114continue using `gpt-5.4`. For extra fast tasks, ChatGPT Pro subscribers have

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

55 116 

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

57 118 

58```bash119```bash

59codex --model gpt-5.4120codex --model gpt-5.5

60```121```

61 122 

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

95 156 

96Codex 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.157Codex 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.

97 158 

159## Image generation

160 

161Ask 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.

162 

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

164 

165Built-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).

166 

167For 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.

168 

98## Syntax highlighting and themes169## Syntax highlighting and themes

99 170 

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

202## Tips and shortcuts273## Tips and shortcuts

203 274 

204- 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.275- 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.

205- Press `Enter` while Codex is running to inject new instructions into the current turn, or press `Tab` to queue a follow-up prompt for the next turn.276- 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.

206- 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.277- 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.

207- 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.278- 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.

208- 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.279- 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.