cli/reference.md Codex Docs, 2026-05-05 23:00 UTC → 2026-05-18 22:01 UTC

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

123 type: "experimental",123 type: "experimental",

124 description:124 description:

125 "Launch the Codex app server for local development or debugging.",125 "Launch the Codex app server for local development or debugging over stdio, WebSocket, or a Unix socket.",

126 },

127 {

128 key: "codex remote-control",

129 href: "/codex/cli/reference#codex-remote-control",

130 type: "experimental",

131 description:

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

126 },133 },

127 {134 {

128 key: "codex app",135 key: "codex app",

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

193 type: "stable",200 type: "stable",

194 description:201 description:

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

196 },203 },

197 {204 {

198 key: "codex logout",205 key: "codex logout",

375export const appServerOptions = [382export const appServerOptions = [

376 {383 {

377 key: "--listen",384 key: "--listen",

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

379 defaultValue: "stdio://",386 defaultValue: "stdio://",

380 description:387 description:

381 "Transport listener URL. Use `ws://IP:PORT` to expose a WebSocket endpoint for remote clients.",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.",

382 },389 },

383 {390 {

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

417 description:424 description:

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

419 },426 },

427 {

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

429 type: "boolean",

430 defaultValue: "false",

431 description:

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

433 },

420];434];

421 435 

422export const appOptions = [436export const appOptions = [

583 description:597 description:

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

585 },599 },

600 {

601 key: "--with-access-token",

602 type: "boolean",

603 description:

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

605 },

586 {606 {

587 key: "--device-auth",607 key: "--device-auth",

588 type: "boolean",608 type: "boolean",

893 913 

894Running `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. For low-friction local work, use `--sandbox workspace-write --ask-for-approval on-request`.914Running `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. For low-friction local work, use `--sandbox workspace-write --ask-for-approval on-request`.

895 915 

896Use `--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.916Use `--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.

897 917 

898### `codex app-server`918### `codex app-server`

899 919 

901 921 

902<ConfigTable client:load options={appServerOptions} />922<ConfigTable client:load options={appServerOptions} />

903 923 

904`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.924`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://`. Use `--listen unix://` to accept WebSocket handshakes on Codex's default Unix socket, or `--listen unix:///absolute/path.sock` to choose a socket path. If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.

925 

926### `codex remote-control`

927 

928Ensure the app-server daemon is running with remote-control support enabled.

929Managed remote-control clients and SSH remote workflows use this command; it's

930not a replacement for `codex app-server --listen` when you are building a local

931protocol client.

905 932 

906### `codex app`933### `codex app`

907 934 

983 1010 

984### `codex login`1011### `codex login`

985 1012 

986Authenticate the CLI with a ChatGPT account or API key. With no flags, Codex opens a browser for the ChatGPT OAuth flow.1013Authenticate the CLI with a ChatGPT account, API key, or access token. With no flags, Codex opens a browser for the ChatGPT OAuth flow.

987 1014 

988<ConfigTable client:load options={loginOptions} />1015<ConfigTable client:load options={loginOptions} />

989 1016