# Codex CLI essentials

Source: https://codewiki.com/cheatsheets/codex-cli/

## Install and authenticate

- `npm install -g @openai/codex@0.153.0` — install the exact CLI release used by this sheet
- `codex --version` — print the installed CLI version
- `codex login` — authenticate through the default browser flow
- `codex login --device-auth` — authenticate with a device code instead of opening a browser
- `printenv OPENAI_API_KEY | codex login --with-api-key` — read an API key from standard input
- `codex login status` — show the active authentication mode and return nonzero when logged out
- `codex logout` — remove stored Codex credentials

## Start an interactive task

- `codex` — open the terminal UI in the current directory
- `codex 'Explain the failing test'` — open the terminal UI with an initial task
- `codex -C repo 'Fix the failing test'` — set the working root before the task begins
- `codex -i screenshot.png 'Fix this UI bug'` — attach an image to the initial task
- `codex --search 'Verify the current dependency API'` — enable live web search for this run
- `codex --no-alt-screen` — keep the terminal UI in normal scrollback

## Bound permissions

- `codex -s read-only` — allow model-generated commands to read but not write
- `codex -s workspace-write -a on-request` — allow workspace writes and let Codex request approval
- `codex -s workspace-write -a never` — allow workspace writes without interactive approval prompts
- `codex --add-dir ../shared` — grant another directory write access for this run
- `codex --approve-for-me` — route approval requests through automatic review in workspace-write mode
- `codex --dangerously-bypass-approvals-and-sandbox` — remove both safeguards only inside an externally hardened sandbox

## Control the terminal UI

- `/init` — generate an AGENTS.md scaffold for the current project
- `/status` — show the active session configuration and usage
- `/model` — choose the model and reasoning effort
- `/permissions` — change the approval and sandbox preset during the session
- `/mention src/lib/api.ts` — add a specific workspace file to the prompt
- `/compact` — replace earlier turns with a concise context summary
- `/exit` — close the interactive session

## Run non-interactively

- `codex exec 'Run tests and fix failures'` — run one task without opening the terminal UI
- `printf '%s\n' 'Explain this diff' | codex exec -` — read the task from standard input
- `codex exec --ephemeral 'Explain this repository'` — run without persisting session files
- `codex exec --json 'Run the targeted tests'` — stream machine-readable events as JSONL
- `codex exec -o final.txt 'Summarize the change'` — write the final agent message to a file
- `codex exec --output-schema schema.json 'Report findings'` — constrain the final response with a JSON Schema

## Continue or branch a session

- `codex resume` — choose a saved interactive session from the current directory
- `codex resume --last` — continue the most recent saved interactive session
- `codex resume SESSION_ID` — continue one saved session by identifier or name
- `codex resume --all` — show sessions outside the current-directory filter
- `codex fork SESSION_ID` — start a new chat from an earlier session
- `codex fork --last` — fork the most recent saved interactive session
- `codex exec resume --last 'Run the remaining checks'` — continue the latest non-interactive session with a new task

## Review changes

- `/diff` — show staged, unstaged, and untracked workspace changes
- `/review` — review the working tree inside the current session
- `codex review --uncommitted` — review staged, unstaged, and untracked changes non-interactively
- `codex review --base main` — review the current branch against main
- `codex review --commit COMMIT` — review the changes introduced by one commit
- `printf '%s\n' 'Focus on correctness and missing tests' | codex review -` — read custom review instructions from standard input

## Override configuration

- `codex -m MODEL` — override the configured model for this run
- `codex -p PROFILE` — layer a named profile over the base configuration
- `codex -c key=value` — override one configuration value for this invocation
- `codex --strict-config` — fail when config.toml contains an unknown field
- `codex features list` — show known feature flags, stages, and effective states
- `codex features enable FEATURE` — persistently enable one feature in config.toml
- `codex features disable FEATURE` — persistently disable one feature in config.toml

## Manage MCP servers

- `codex mcp list` — list configured Model Context Protocol servers
- `codex mcp list --json` — list configured servers as JSON
- `codex mcp get NAME --json` — show one server configuration as JSON
- `codex mcp add NAME -- COMMAND ARG` — register a server launched over standard input and output
- `codex mcp add NAME --url URL` — register a server reached through streamable HTTP
- `codex mcp login NAME` — authenticate one HTTP server with OAuth
- `codex mcp remove NAME` — remove one server configuration

## Diagnose and integrate

- `codex doctor` — inspect installation, configuration, authentication, runtime, Git, and terminal health
- `codex doctor --summary` — print only grouped diagnostic checks and totals
- `codex doctor --json` — emit a redacted machine-readable diagnostic report
- `codex completion bash` — generate a Bash completion script
- `codex sandbox -- COMMAND ARG` — run an arbitrary command inside the Codex-provided sandbox
- `codex update` — check for and apply a supported CLI self-update