OpenAI Codex CLI commands

Command lines, slash commands and terminal UI keys of OpenAI Codex CLI 0.160.1, checked against the built-in help, OpenAI's Codex documentation and the default keymap in the source code. Words in capitals such as PROMPT or SESSION_ID stand for your own value. Slash commands and keys work only inside the interactive session that codex opens; Vim-mode keys and the agents overview are left out. Most keys can be reassigned with /keymap.

314 commands in 18 sections. Checked row by row against OpenAI Codex documentation: Developer commands (CLI reference, slash commands, interactive shortcuts) on . Edited by Jay.

Starting a session 17

ShortcutWhat it does
codexOpen the terminal UIStarts an interactive session in the current directory; options given without a subcommand go to the TUI.
codex PROMPTStart with an opening promptThe quoted text becomes the first message; leave it out and the composer opens empty.
codex --image FILEAttach images to the first promptShort form -i; give several paths separated by commas, or repeat the flag.
codex --cd DIRSet the working directoryShort form -C; the agent treats that folder as its workspace root instead of the shell's current one.
codex --add-dir DIRAdd a writable directoryGrants write access to one more folder next to the main workspace; repeat it for several.
codex --searchTurn on live web searchWithout the flag, web search results come from a cache rather than live browsing.
codex --profile PROFILELoad a named profileShort form -p; puts the profile's own config file from CODEX_HOME over your normal settings.
codex --config KEY=VALUEOverride one config valueShort form -c; the value is read as TOML, nested keys use dots, and it applies to this run only.
codex --strict-configReject unknown config fieldsStops with an error when config.toml holds a field this release does not know.
codex --no-alt-screenRun the TUI inlineLeaves the alternate screen off, so earlier terminal output stays in scrollback.
codex --worktreeStart in a new Git worktreeCodex creates and manages the worktree that the session then works in.
codex --versionPrint the installed version
codex --helpShow helpWorks after any subcommand too; the short form -h prints a condensed summary.
codex updateUpdate the CLILooks for a newer release and installs it when this build can update itself.
codex appOpen the ChatGPT desktop appmacOS and Windows only; when the app is missing, the installer starts instead.
codex app PATHOpen a workspace in the desktop appOn macOS the app opens that folder; on Windows the command only prints which path to open.
codex app --download-url URLUse another installer URLAdvanced option that only matters when the desktop app still has to be installed.

Non-interactive runs 20

The documentation still describes --full-auto as a deprecated alias, but release 0.160.1 answers it with an "unexpected argument" error; use codex exec --sandbox workspace-write.

ShortcutWhat it does
codex exec PROMPTRun one task without the TUIProgress goes to stderr and only the final message to stdout, so the answer can be piped or redirected.
codex eShort alias of codex exec
codex exec -Read the whole prompt from stdinThe lone hyphen makes piped input the full instruction instead of extra context.
cat prompt.txt | codex exec -Pipe a prompt fileThe file's text is what Codex is asked to do.
codex exec --jsonStream events as JSON LinesStdout carries one JSON event per line, such as turn.started and turn.completed, instead of formatted text.
codex exec --output-last-message FILESave the final message to a fileShort form -o; the message is still printed on stdout as well.
codex exec --output-schema FILERequire a JSON Schema replyThe final answer has to match the schema in the file, which gives later pipeline steps structured data.
codex exec --ephemeralRun without saving the sessionSkips writing the session rollout files.
codex exec --skip-git-repo-checkAllow runs outside a Git repoCodex otherwise refuses to work outside a repository, as a guard against destructive changes.
codex exec --color neverTurn off colored outputTakes always, never or auto; auto is what you get without the flag.
codex exec --ignore-user-configSkip the user config fileconfig.toml in CODEX_HOME is left unread, while saved authentication is still used.
codex exec --ignore-rulesSkip execpolicy rule filesNeither your own nor the project's .rules files apply to this run.
codex exec --sandbox workspace-writeLet an unattended run edit filescodex exec is read-only unless told otherwise; this widens it to edits inside the workspace.
codex exec --sandbox danger-full-accessGive an unattended run full accessThe docs reserve it for controlled environments such as an isolated CI runner or a container.
codex reviewReview code non-interactivelyPick one target with a flag, or pass your own review instructions as the prompt.
codex review --uncommittedReview uncommitted workCovers staged, unstaged and untracked files in the working tree.
codex review --base BRANCHReview against a base branchLooks at what the current work adds on top of the branch you name.
codex review --commit SHAReview a single commitLimits the review to what that one commit changed.
codex review --title TITLETitle for the review summaryOnly valid together with --commit; the text is displayed as that commit's title.
codex review PROMPTReview with custom instructionsCannot be combined with the target flags; a single hyphen reads the instructions from stdin.

Resuming and managing sessions 17

ShortcutWhat it does
codex resumePick a session to resumeOpens a picker of saved interactive sessions and reloads the one you choose.
codex resume --lastResume the latest sessionNo picker is shown; only sessions from the current directory count unless --all is added.
codex resume --allList sessions from every directoryTurns off the current-directory filter and adds a CWD column to the picker.
codex resume SESSION_IDResume a specific sessionTakes the session UUID or its name; a value that parses as a UUID is tried first.
codex resume --include-non-interactiveInclude codex exec sessionsAdds sessions from non-interactive runs to the picker and to what --last can choose.
codex forkFork a saved sessionOpens the session picker and copies the chosen transcript into a new chat; the original stays as it was.
codex fork --lastFork the latest sessionBranches straight from your newest session, with no picker in between.
codex fork SESSION_IDFork a session by IDThe ID is the UUID of the saved conversation to copy.
codex exec resume --lastContinue the last exec runAdd a follow-up prompt after the flag to keep working in the same session.
codex exec resume SESSION_IDContinue an exec run by IDTakes a session UUID or a thread name; a UUID is tried first.
codex exec resume --allSearch every directoryWithout it, only sessions recorded in the current working directory are considered.
codex exec fork SESSION_IDFork an exec sessionStarts a new non-interactive session from a copy of the one named.
codex archive SESSIONArchive a saved sessionHides it from the session picker while the transcript is kept; takes an ID or a name.
codex unarchive SESSIONRestore an archived sessionBrings a session hidden with codex archive back into the active lists.
codex delete SESSIONDelete a saved sessionRemoves the transcript for good, after a confirmation prompt.
codex delete SESSION_UUID --forceDelete without confirmationWorks only with a UUID; a session name still asks before anything is removed.
codex queue --thread THREAD --message TEXTQueue a message for a sessionTHREAD is a session UUID or the exact session name.

Approvals and sandbox 18

ShortcutWhat it does
codex --sandbox read-onlySandbox: read-onlyShort form -s; commands the model runs can read files but not change them.
codex --sandbox workspace-writeSandbox: write inside the workspaceEdits are allowed in the working directory and in folders added with --add-dir.
codex --sandbox danger-full-accessSandbox: full accessThe docs advise --add-dir instead when all you need is one more writable folder.
codex --ask-for-approval on-requestAsk when the model requests itShort form -a; the model itself decides which commands to put in front of you.
codex --ask-for-approval neverNever stop for approvalA command that fails goes straight back to the model; combine it with any sandbox mode.
codex --sandbox workspace-write --ask-for-approval on-requestAuto preset as flagsCodex reads, edits and runs commands in the workspace on its own and asks before going beyond it.
codex --sandbox read-only --ask-for-approval on-requestRead-only preset as flagsEquivalent to setting sandbox_mode and approval_policy in config.toml for one session.
codex --approve-for-meSend approvals to auto reviewApproval prompts are answered by the automatic reviewer, and the session runs with the workspace-write policy.
codex --dangerously-bypass-approvals-and-sandboxSkip approvals and the sandboxEvery command runs unconfirmed and unconfined; meant only for machines that are isolated from outside.
--yoloAlias of the full bypass flagAccepted by codex and codex exec in place of --dangerously-bypass-approvals-and-sandbox.
codex --dangerously-bypass-hook-trustRun hooks without saved trustEnabled hooks run even if you never trusted them; for pipelines that check hook sources themselves.
codex sandbox COMMANDRun a command in the sandboxExecutes any program under the policies Codex applies to model-run commands, which lets you test them.
codex sandbox --permission-profile NAMEApply a permissions profileShort form -P; the profile is looked up by name in your configuration.
codex sandbox --include-managed-configHonor managed requirementsUsed with --permission-profile, so organisation-managed rules are part of the resolved profile.
--log-denialsLog sandbox denials (macOS)codex sandbox option on macOS: records what the sandbox blocked during the run and prints it afterwards.
--allow-unix-socket PATHAllow a Unix socket (macOS)codex sandbox option on macOS: lets the confined program use sockets under that path; repeatable.
codex execpolicy check --rules PATH COMMANDTest a command against rulesPrints JSON with the strictest decision and the matching rules; repeat --rules to combine files.
codex execpolicy check --prettyPretty-print the decisionFormats the JSON result over several lines for reading.

Model and reasoning options 11

ShortcutWhat it does
codex --model MODELChoose the model for a runShort form -m; replaces the model named in config.toml for this session only.
codex --ossUse a local open source providerCodex takes the provider from --local-provider or the oss_provider setting, or lets you pick one.
codex --oss --local-provider ollamaRun against OllamaOverrides the oss_provider setting for this one run.
codex --oss --local-provider lmstudioRun against LM Studiolmstudio and ollama are the two values the flag accepts.
/modelPick the model and reasoning effortOpens a picker limited to the models your account can use; /status confirms the change.
Alt+.orShift+UpRaise reasoning effortMoves the session's reasoning effort up one step from the chat view.
Alt+,orShift+DownLower reasoning effortMoves the session's reasoning effort down one step from the chat view.
/fastToggle the Fast tierTyping it again switches the tier off; the command is hidden when the current model has no Fast tier.
/personalityChoose a response styleOffers friendly, pragmatic and none; hidden when the active model has no personality support.
codex debug modelsPrint the model catalogOutputs the catalog Codex sees, in JSON.
codex debug models --bundledPrint only the built-in catalogSkips the refresh from the remote models endpoint.

Authentication 8

ShortcutWhat it does
codex loginSign in with ChatGPTWith no flags a browser opens for the ChatGPT OAuth flow.
codex login --device-authSign in with a device codeUses the OAuth device code flow, so no browser has to open on this machine.
printenv OPENAI_API_KEY | codex login --with-api-keySign in with an API keyThe key arrives on stdin rather than as an argument.
printenv CODEX_ACCESS_TOKEN | codex login --with-access-tokenSign in with an access tokenThe token is piped in on stdin in the same way as an API key.
codex login statusShow the login statusReports which sign-in method is in use; exit code 0 means credentials are present.
codex logoutRemove saved credentialsClears both API key and ChatGPT sign-in data; the command takes no flags.
CODEX_API_KEYAPI key for a single runEnvironment variable read by codex exec and codex review, so CI can pass a key without a stored login.
/logoutSign out inside the TUIClears the local credentials, which matters on a machine you share.

MCP servers 17

ShortcutWhat it does
codex mcp listList configured MCP serversReads the server entries stored in config.toml.
codex mcp list --jsonList servers as JSON
codex mcp get NAMEShow one server entryAdd --json to print the raw configuration entry instead.
codex mcp add NAME -- COMMANDAdd a stdio MCP serverEverything after the double hyphen is the program and arguments that start the server.
codex mcp add context7 -- npx -y @upstash/context7-mcpExample: add Context7The docs' own example: a documentation server that is started through npx.
codex mcp add NAME --env KEY=VALUE -- COMMANDAdd a server with environment variablesRepeat --env for each variable; it applies to stdio servers only.
codex mcp add NAME --url URLAdd a streamable HTTP serverRegisters a remote server by address; this form and the launch command exclude each other.
codex mcp add NAME --url URL --bearer-token-env-var ENV_VARBearer token from an env variableNames the variable whose content is sent as the token; HTTP servers only.
codex mcp add NAME --url URL --oauth-client-id CLIENT_IDSet the OAuth client IDNeeded when the authorization server expects a client that was registered beforehand.
codex mcp add NAME --url URL --oauth-resource RESOURCESet the OAuth resource valueThe value is passed along when you log in to that server.
codex mcp login NAMEStart OAuth login for a serverWorks only for streamable HTTP servers that support OAuth.
codex mcp login NAME --scopes SCOPE,SCOPERequest specific OAuth scopesThe scopes are written as one list with commas and no spaces.
codex mcp login NAME --no-browserLog in from a headless shellShows the authorization link and waits for the callback address you paste back.
codex mcp logout NAMERemove a server's OAuth credentials
codex mcp remove NAMEDelete a server entryTakes the stored definition out of config.toml.
/mcpList MCP tools in the sessionShows which servers and tools Codex can call right now.
/mcp verboseShow MCP server diagnosticsAny other argument just prints the command usage.

Cloud tasks 17

ShortcutWhat it does
codex cloudOpen the cloud task pickerInteractive browser for Codex Cloud tasks; it is also where environment IDs can be looked up.
codex cloud-tasksAlias of codex cloud
codex cloud exec --env ENV_ID QUERYSubmit a cloud taskThe environment ID is required; leave the prompt out and Codex asks for the details.
codex cloud exec --env ENV_ID --attempts ATTEMPTSRun several attemptsAsks for best-of-N attempts, from one to four; a single attempt is the default.
codex cloud exec --env ENV_ID --branch BRANCHRun on a chosen Git branchWithout it the task uses the branch you are on.
codex cloud listList recent cloud tasksPlain output gives a task URL followed by status details.
codex cloud list --jsonList tasks as JSONThe payload holds a tasks array and, when there are more pages, a cursor value.
codex cloud list --limit NLimit the number of tasksAccepts 1 to 20; twenty is what you get without the flag.
codex cloud list --cursor CURSORFetch the next pagePass the cursor value that the last list request handed back.
codex cloud list --env ENV_IDFilter tasks by environmentShows only the tasks that belong to the named environment.
codex cloud status TASK_IDShow a task's status
codex cloud diff TASK_IDShow a task's diffPrints the unified diff the task produced, without applying it.
codex cloud diff TASK_ID --attempt NShow the diff of one attemptN counts from 1 when the task ran more than one attempt.
codex cloud apply TASK_IDApply a task's diff locally
codex cloud apply TASK_ID --attempt NApply the diff of one attemptChooses which of several attempts is patched into your working tree.
codex apply TASK_IDApply the latest cloud diffPatches the working tree through git apply and exits non-zero when that fails, for example on conflicts.
codex aShort alias of codex apply

Slash commands for chats and sessions 37

ShortcutWhat it does
/newStart a new chatUnlike /clear, the terminal view is not wiped first.
/new NAMEStart a named chatText typed after the command is used to label the chat.
/clearClear the screen and start freshWipes the terminal and resets the chat context in one step; disabled while a task runs.
/resumeResume a saved chatOpens the saved-session picker and reloads the transcript you choose.
/forkFork the current chatClones the chat under a new ID and leaves the original transcript untouched.
/sideOpen a side chatA temporary fork with its own transcript; /btw is the same command.
/btwAlias of /side
/side TEXTAsk a question in a side chatThe inline text is sent as the first message of the side chat.
/renameRename the current chatOpens a naming prompt; the transcript itself does not change.
/rename NAMERename with an inline name
/archiveArchive this session and exitAsks for confirmation; the transcript stays on disk and codex unarchive brings it back.
/deleteDelete this session and exitPermanent, and sessions spawned from this one go too; asks for confirmation first.
/compactCompact the conversationReplaces earlier turns with a short summary so the context window has room again.
/statusShow session statusLists the model in use, the approval policy, which roots are writable and the context left; remote sessions add the server address.
/usageView account token usageOpens a menu for token activity or for redeeming an earned rate-limit reset.
/usage dailyOpen daily token activityweekly and cumulative are the other two views that can be named.
/goalView the current goal
/goal OBJECTIVESet a task goalThe goal stays attached to the chat while work continues; the text may be up to 4,000 characters.
/goal editRevise the goal
/goal pausePause the goal
/goal resumeResume a paused goal
/goal clearRemove the goal
/planSwitch to plan modeCodex proposes a plan before it implements anything; unavailable while it is already working.
/plan PROMPTPlan from an inline promptThe text after the command becomes the first planning request.
/initCreate an AGENTS.md scaffoldWritten to the directory you run it in; edit the file to match the repository's conventions.
/reviewReview the working treeSummarizes problems in your local changes; uses the session model unless review_model is set.
/diffShow the Git diffCovers staged and unstaged changes as well as untracked files.
/mention PATHAdd a file to the conversationPick the matching result from the popup; later turns then refer to that file directly.
/copyCopy the last replyTakes the last finished output even while a new turn is still running.
/rawToggle raw scrollbackMakes transcript text easier to select and copy; the setting can be kept with tui.raw_output_mode.
/raw onTurn raw scrollback on
/raw offTurn raw scrollback off
/appContinue in the desktop appmacOS and Windows only; the same saved chat opens in the ChatGPT app.
/agentSwitch agent thread/subagents is the same command; a picker lists the threads to inspect or continue.
/subagentsAlias of /agent
/quitExit the CLILeaves at once, so save or commit important work first.
/exitExit (same as /quit)

Slash commands for permissions and tools 14

ShortcutWhat it does
/permissionsChange approval settingsPick a preset such as Auto or Read Only; custom permission profiles show up in the same picker.
/approveRetry a denied action onceFor something the automatic reviewer just refused; Codex asks you to confirm the retry.
/appsBrowse apps (connectors)The chosen app lands in the composer as a $app-slug mention.
/hooksManage lifecycle hooksTrust, disable or re-enable hooks per event; managed hooks are listed but cannot be switched off here.
/skillsPick a skillThe selected skill's context is inserted so the next request follows its instructions.
/memoriesConfigure memoriesChoose whether Codex uses existing memories, generates new ones, or does neither.
/ideInclude IDE contextAdds what is open or selected in your editor to the next prompt.
/importImport from another agentBrings setup, project files and recent chats over from Claude Code or Cursor; local TUI sessions only.
/experimentalToggle experimental featuresChoices such as Network proxy are saved to config and may need a restart to apply.
/psList background terminalsEach entry shows its command and up to three recent lines of output.
/stopStop background terminalsEnds every background terminal of this session; /clean still works as an alias.
/cleanAlias of /stop
/setup-default-sandboxSet up elevated sandbox (Windows)Appears only on Windows while Codex runs with the degraded restricted-token sandbox.
/sandbox-add-read-dir C:\absolute\directory\pathGrant read access (Windows)Native Windows only; the path must be an existing absolute directory.

Slash commands for display and settings 10

ShortcutWhat it does
/statuslineConfigure the footer status lineToggle and reorder items such as model, git branch and token counters; saved as tui.status_line.
/titleConfigure the terminal titleChooses what the window or tab title shows, for example project, status or branch.
/themeChoose a syntax themePreviews themes for code blocks and diffs and stores the pick as tui.theme.
/petsChoose a terminal petOpens the pet picker; /pet is the same command.
/petAlias of /pets
/pets offHide the terminal pet
/keymapRemap TUI shortcutsPick a context and an action, then enter a new key; the binding is written to tui.keymap.
/vimToggle Vim mode in the composerLasts for the current session; tui.vim_mode_default = true makes it the default.
/debug-configPrint config diagnosticsLists config layers from lowest precedence up, to show why a setting differs from config.toml.
/feedbackSend feedbackPrompts let you attach logs or diagnostics to the report.

Composer and chat keys 33

Bindings other than the fixed ones can be changed with /keymap; in config.toml the keys are written like ctrl-a, shift-enter and page-down.

ShortcutWhat it does
EnterSend the promptWhile Codex is working, Enter injects the new instructions into the turn that is running.
TabQueue a follow-upWhile Codex is working, what you typed is held back and runs as the next turn.
Ctrl+JorShift+EnterorAlt+EnterInsert a line breakPlain Enter sends the prompt in the composer, so multi-line text needs one of these.
@Search for a fileLooks through the workspace and inserts the chosen path into the prompt.
!Run a shell commandStart the line with it; the command runs under the session's approval and sandbox settings.
UporDownBrowse draft historyBrings earlier drafts back into the composer.
Ctrl+RSearch prompt historyEnter uses the match and Esc cancels; pressing it again steps to the previous match.
Ctrl+SNext history search matchOnly useful after Ctrl + R has opened the reverse history search.
EscInterrupt the running turnStops the work Codex is doing at that moment.
EscthenEscEdit the previous messageNeeds an empty composer; the chat is forked from that earlier message.
Ctrl+CInterrupt or quitA fixed interrupt-or-quit key; the docs list it next to /exit for closing the session.
Ctrl+DQuit CodexA fixed binding: the keymap reserves it, so /keymap cannot give it to another action.
Ctrl+VPaste an imageReserved for image paste in the composer, together with Ctrl + Alt + V.
Shift+TabCycle collaboration mode
Alt+LeftPrevious agent
Alt+RightNext agent
/Open the slash command popupTyped in the composer; keep typing to filter the list of commands.
$Mention an app (connector)Apps chosen with /apps are inserted in the same $app-slug form.
Ctrl+LClear the terminal viewThe chat itself continues, unlike /clear; not available during a running task.
Ctrl+GWrite the prompt in your editorOpens the program named in VISUAL, or EDITOR if that is unset; saving and closing returns the text.
Ctrl+OCopy the last replySame result as /copy without opening the slash command menu.
Ctrl+TOpen the transcriptShows the whole conversation in a pager overlay; the same key closes it again.
F3Find in the transcript
F4Focus activity groupsPuts the focus on activity groups in the transcript so their details can be inspected.
F2Open warnings
Alt+RToggle raw scrollbackDefault binding for what /raw does.
Ctrl+/Switch to or from a side chatJumps between the side chat and the main chat; both stay open.
?Show the shortcut overlay
Shift+LeftorAlt+UpEdit the last queued messageSteps back through pending questions first, then reopens the newest queued message.
Shift+RightorAlt+DownReturn toward the composerWalks the pending questions in the other direction, back to the input box.
Ctrl+]Skip the focused question
F8Toggle voice conversation
Ctrl+XMute or unmute the microphoneOnly has an effect during an active voice conversation.

Editing the prompt 15

/vim switches the composer to Vim normal and insert modes; the Vim-mode keys have their own keymap contexts and are not listed here.

ShortcutWhat it does
LeftorCtrl+BMove left one character
RightorCtrl+FMove right one character
UporCtrl+PMove up one lineMoves by visual line, so a wrapped paragraph counts as several lines.
DownorCtrl+NMove down one line
Alt+BorAlt+LeftorCtrl+LeftGo to start of previous word
Alt+ForAlt+RightorCtrl+RightGo to end of next word
HomeorCtrl+AGo to start of line
EndorCtrl+EGo to end of line
BackspaceorCtrl+HDelete character to the left
DeleteorCtrl+DDelete character to the right
Alt+BackspaceorCtrl+WorCtrl+BackspaceDelete the previous word
Alt+DeleteorAlt+DorCtrl+DeleteDelete the next word
Ctrl+UKill to start of lineThe removed text goes to the kill buffer and can be yanked back.
Ctrl+KKill to end of line
Ctrl+YYank killed textInserts what Ctrl + U or Ctrl + K last removed.

Transcript and list keys 20

ShortcutWhat it does
UporKScroll up one row
DownorJScroll down one row
Page UporCtrl+BScroll up one pageShift + Space is bound to the same pager action.
Page DownorCtrl+FScroll down one pageSpace on its own pages down as well.
Ctrl+UScroll up half a page
Ctrl+DScroll down half a page
HomeJump to the beginning
EndJump to the end
/Search inside the pagerF3 starts the same search in a transcript pager.
QorCtrl+CClose the overlayLeaves the transcript or any other static pager overlay.
UporCtrl+PorCtrl+KorKMove the selection upApplies to popup-style selectable lists such as the pickers.
DownorCtrl+NorCtrl+JorJMove the selection down
LeftorCtrl+HMove left in a pickerOnly pickers that have horizontal actions use it.
RightorCtrl+LMove right in a picker
Page UporCtrl+BSelection up one page
Page DownorCtrl+FSelection down one page
HomeFirst list item
EndLast list item
EnterAccept the selection
EscClose the listCancels the selection view without choosing anything.

Approval prompt keys 8

ShortcutWhat it does
YApproveAccepts the primary option of the approval request.
AApprove for the sessionOffered only when the request has a session-wide option.
PApprove with a command prefixAvailable only when the prompt offers an exec-policy prefix choice.
DDenyRefuses the request and sends no further instructions.
EscorNDecline with guidanceTurns the request down and lets you tell Codex what to do instead.
CCancel an elicitation request
Ctrl+AOpen full-screen detailsExpands the approval request into a full-screen view.
OOpen the requesting threadFor approvals shown from a different thread than the one that asked.

App server and remote control 25

codex mcp-server and the standalone codex-mcp-server binary have been removed; the app server takes their place.

ShortcutWhat it does
codex app-serverStart the app serverExperimental; speaks JSONL over stdio unless another listener is chosen.
codex app-server --listen ws://IP:PORTListen on a WebSocketClients connect over TCP instead of stdio; put TLS termination or a proxy in front for wss.
codex app-server --listen unix://Listen on the default Unix socketunix://PATH picks a socket file of your own instead.
codex app-server --listen offDisable the local transport
codex app-server --stdioUse the stdio transportSame as --listen stdio:// and cannot be combined with --listen.
codex app-server --ws-auth capability-tokenRequire a capability tokenPair it with --ws-token-file or --ws-token-sha256; without --ws-auth, WebSocket clients are not authenticated.
codex app-server --ws-auth signed-bearer-tokenRequire signed bearer tokensNeeds --ws-shared-secret-file with the HMAC secret that validates the JWTs.
codex app-server --ws-token-file PATHFile holding the capability tokenThe path has to be absolute.
codex app-server --ws-token-sha256 HEXToken digest instead of a fileFor setups where the client token comes from another source than a local file.
codex app-server --ws-shared-secret-file PATHSecret for signed tokensRequired whenever --ws-auth is set to signed-bearer-token.
codex app-server --ws-issuer ISSUERExpected token issuerCompared with the iss claim of each signed bearer token.
codex app-server --ws-audience AUDIENCEExpected token audienceCompared with the aud claim of each signed bearer token.
codex app-server --ws-max-clock-skew-seconds SECONDSAllowed clock skewTolerance applied when the exp and nbf claims are checked.
codex app-server --analytics-default-enabledTurn analytics on by defaultMeant for first-party clients; app-server analytics otherwise stay off until the user opts in.
codex app-server --code-mode-host URLRemote Code Mode hostOne outbound connection shared by every thread, separate from --listen; use wss for hosts that are not local.
codex app-server generate-ts --out DIRGenerate TypeScript bindingsCovers the app server protocol; add --experimental to include gated methods and fields.
codex app-server generate-json-schema --out DIRGenerate the protocol JSON Schema
codex --remote ws://host:portAttach the TUI to an app serverAlso takes wss://host:port, unix:// for the default socket and unix://PATH.
codex --remote-auth-token-env ENV_VARBearer token for the remote serverRequires --remote; the token is sent only over wss or local-only ws addresses.
codex --no-daemonRun without the background serverApplies even when a shared server is already up.
codex remote-controlStart remote control (foreground)Stays attached to the terminal; the start subcommand runs it as a daemon instead.
codex remote-control startStart the remote-control daemonRuns in the background, unlike plain codex remote-control.
codex remote-control stopStop the daemon
codex remote-control pairCreate a pairing codePrints a code for manual pairing that expires soon; the daemon must be running.
codex agentsOpen the agent session overviewCovers every session that the local background daemon is hosting.

Diagnostics and feature flags 15

ShortcutWhat it does
codex doctorDiagnose the installationChecks install, config, auth, runtime, Git and terminal health; useful before filing a support issue.
codex doctor --summaryShow the short reportLeaves out the details and keeps one row per check group plus the totals.
codex doctor --allExpand long listsApplies to the detailed human-readable report.
codex doctor --jsonExport a redacted JSON report
codex doctor --asciiUse ASCII status labelsSwaps the symbols and separators of the report for plain ASCII.
codex doctor --no-colorTurn off ANSI colors
codex features listList feature flagsShows each known flag with its maturity stage and whether it is currently on.
codex features enable FEATUREEnable a feature permanentlyWrites the change to config.toml, so later sessions start with it.
codex features disable FEATUREDisable a feature permanently
codex --enable FEATUREEnable a feature for one runShorthand for a -c features override set to true; repeat it for several flags.
codex --disable FEATUREDisable a feature for one runShorthand for a -c features override set to false; repeatable.
codex completion zshGenerate shell completionsPrints the script to stdout; bash, fish, powershell and elvish are the other accepted shells.
eval "$(codex completion zsh)"Load completions in zshLine for your shell configuration; run compinit first if zsh reports that compdef is missing.
codex debug prompt-input PROMPTPrint the model-visible promptRenders as JSON the input list the model would receive, to debug instructions and context.
codex debug app-server send-message-v2 USER_MESSAGESend one test messageDebug aid: the text goes through a fresh thread and the server notifications are printed.

Plugins and marketplaces 12

ShortcutWhat it does
codex plugin add PLUGIN@MARKETPLACEInstall a pluginLeave out @MARKETPLACE and name the marketplace with --marketplace or -m instead.
codex plugin listList pluginsAdd --marketplace NAME to look at a single marketplace.
codex plugin list --available --jsonInclude plugins not yet installed--available only works together with --json; the output then has installed and available arrays.
codex plugin remove PLUGIN@MARKETPLACEUninstall a pluginAlso deletes the local cache of that plugin.
codex plugin marketplace add SOURCEAdd a plugin marketplaceTakes a folder on disk, GitHub owner/repo shorthand or a Git URL.
codex plugin marketplace add SOURCE --ref REFPin a Git refOnly meaningful for marketplaces that come from Git.
codex plugin marketplace add SOURCE --sparse PATHUse a sparse checkoutRepeat the flag for each path you want checked out.
codex plugin marketplace listList marketplacesPrints each marketplace Codex is looking at together with its root path.
codex plugin marketplace upgradeRefresh Git marketplacesWith a name only that marketplace is refreshed; without one, every configured Git marketplace.
codex plugin marketplace remove MARKETPLACE_NAMERemove a marketplace
/pluginsBrowse plugins in the TUIMarketplace tabs list what is installed and what can be added, with each plugin's capabilities.
SpaceEnable or disable a pluginWorks on an installed plugin inside the /plugins browser.

Notes

Starting a session

codex alone opens the terminal UI in the current directory; codex PROMPT sends a first message straight away. codex --model MODEL overrides the configured model for one run, codex --cd DIR sets the working directory, and codex --add-dir DIR grants write access to a second directory such as a shared library next to the app. codex --profile PROFILE layers a named config file over the base one, which is how a team keeps separate settings for reviewing versus generating. codex --image FILE attaches screenshots to the first prompt, useful for "make it look like this".

Approval and the sandbox

codex --ask-for-approval on-request lets the model decide when to stop for confirmation and codex --ask-for-approval never removes the prompts; codex --sandbox workspace-write keeps edits inside the workspace either way. codex --dangerously-bypass-approvals-and-sandbox (alias --yolo) removes both — the flag name is long on purpose, and it belongs only inside a container or a throwaway VM. codex execpolicy check --rules PATH COMMAND evaluates rule files against a command to show whether it would be allowed, prompted or blocked, which is the way to test a policy before trusting it. Inside a session, /permissions changes the approval preset and /status shows what is active.

Running unattended and reviewing

codex exec PROMPT runs one prompt non-interactively for scripts and CI, with progress on stderr and the final message on stdout; add codex exec --json for newline-delimited events, codex exec --output-last-message FILE to write the final answer to a file, and codex exec --output-schema FILE to request a reply that matches a JSON Schema. codex exec resume --last continues the most recent run and codex exec --ephemeral leaves no session files behind. codex review reviews changes — codex review --uncommitted for the working tree, codex review --base BRANCH against a branch, codex review --commit SHA for one commit. codex doctor diagnoses install, auth and Git problems, and codex mcp list shows the registered tool servers.

Keys inside the terminal UI

Enter sends the prompt, Tab queues a follow-up while Codex is working, Esc interrupts the turn, and Esc, Esc on an empty composer goes back to edit the previous message. Ctrl + R searches prompt history, Ctrl + T opens the transcript and Ctrl + G hands the draft to your editor. Ctrl + C and Ctrl + D are fixed; the other bindings can be remapped with /keymap, which stores them under tui.keymap in config.toml.

Questions

What is the difference between codex and codex exec?

codex opens the interactive TUI. codex exec PROMPT runs a single prompt to completion without a UI, for scripts and CI.

How do I stop Codex asking for approval?

Start it with codex --ask-for-approval never, or change the preset during a session with /permissions. --yolo disables approvals and the sandbox entirely and should only run inside a hardened container.

How do I resume yesterday's session?

codex resume --last reopens the most recent interactive session from the current directory and codex resume shows a picker; codex resume --all looks beyond that directory. For non-interactive runs use codex exec resume --last.

How do I get structured output from a run?

Use codex exec --json for a stream of JSON Lines events, or codex exec --output-schema FILE with a JSON Schema file that the final message has to match.

Which keys leave the Codex terminal UI?

Ctrl + D quits and Ctrl + C interrupts or quits; both are fixed bindings. /quit and /exit do the same from the composer.

Sources and checks

Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.

10 rows from the earlier version of this page were removed in that check: duplicates, and bindings the documentation does not list or lists differently.

Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.