cli/features.md Codex Docs, 2026-04-15 06:44 UTC → 2026-05-18 22:01 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

46 48 

47## Connect the TUI to a remote app server49## Connect the TUI to a remote app server

48 50 

49Remote 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.51Remote TUI mode lets you run the Codex app server on one machine and use the

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

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

52 54 

53```bash55```bash

54codex app-server --listen ws://127.0.0.1:450056codex app-server --listen ws://127.0.0.1:4500

55```57```

56 58 

57Then connect from the machine running the TUI:59Then connect the TUI to that endpoint:

58 60 

59```bash61```bash

60codex --remote ws://127.0.0.1:450062codex --remote ws://127.0.0.1:4500

61```63```

62 64 

63For access from another machine, bind the app server to a reachable interface, for example:65For access from another machine, bind the app server to a reachable interface

64 66and configure WebSocket auth before remote use:

65```bash

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

67```

68 

69`--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.

70 

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

72 

73- **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.

74- **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>`.

75- **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.

76 

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

78 67 

79```bash68```bash

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

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

82openssl rand -base64 32 > "$TOKEN_FILE"70openssl rand -base64 32 > "$TOKEN_FILE"

83chmod 600 "$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"

84```73```

85 74 

86Treat the token file like a password, and regenerate it if it leaks.75`--remote` accepts explicit `ws://host:port` and `wss://host:port` addresses.

76Plain WebSocket connections are appropriate for localhost and SSH

77port-forwarding workflows. For non-local clients, use WebSocket auth and put the

78connection behind TLS.

87 79 

88Then start the app server with that token file. For example, with a capability token behind a TLS proxy:80Codex supports these WebSocket authentication modes:

81 

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

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

84- Signed bearer token: start the server with

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

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

87 

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

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

90`wss://` URLs or loopback `ws://` URLs.

89 91 

90```bash92```bash

91# Remote host93export CODEX_REMOTE_TOKEN="$(cat "$TOKEN_FILE")"

92TOKEN_FILE="$HOME/.codex/codex-app-server-token"94codex --remote wss://remote-host:4500 --remote-auth-token-env CODEX_REMOTE_TOKEN

93codex app-server \

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

95 --ws-auth capability-token \

96 --ws-token-file "$TOKEN_FILE"

97 

98# TUI host

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

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

101 --remote-auth-token-env CODEX_REMOTE_AUTH_TOKEN

102```95```

103 96 

104The 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.97For SSH remote projects in the Codex app, use

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

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

100remote-control support enabled.

105 101 

106## Models and reasoning102## Models and reasoning

107 103 

108For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the104For most tasks in Codex, `gpt-5.5` is the recommended model when it's

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

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

111native computer use, and broader professional workflows. For extra fast tasks,107and follow-through on multi-step tasks. If `gpt-5.5` isn't yet available,

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

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

114 110 

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

116 112 

117```bash113```bash

118codex --model gpt-5.4114codex --model gpt-5.5

119```115```

120 116 

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

154 150 

155Codex 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.151Codex 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.

156 152 

153## Image generation

154 

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

156 

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

158 

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

160 

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

162 

157## Syntax highlighting and themes163## Syntax highlighting and themes

158 164 

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

242 248 

243## Slash commands249## Slash commands

244 250 

245Slash commands give you quick access to specialized workflows like `/review`, `/fork`, 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.251Slash 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.

246 252 

247See 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.253See 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.

248 254 

261## Tips and shortcuts267## Tips and shortcuts

262 268 

263- 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.269- 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.

264- 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.270- 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.

265- 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.271- 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.

266- 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.272- 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.

267- 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.273- 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.