Codex CLI cheatsheet

Every command below was checked against the installed codex-cli 0.147.0 binary or the official OpenAI Docs on 2026-08-18. “First-hand” means it appeared in codex --help or subcommand help; “docs” means the official documentation is the source of truth for that behavior.

Command drill

16 verified Codex CLI commands. Read the task, type the command, press Enter. Every answer is on this page's tables - this drill only asks what the verified data already states.

Answer key - all 16 commands

Print the installed CLI version. codex --version
Update Codex to the latest version. codex update
Authenticate with ChatGPT OAuth, device auth, an API key, or an access token from stdin. codex login
Remove stored authentication credentials. codex logout
Generate a diagnostic report for installation, config, auth, runtime, Git, and session issues. codex doctor
Start an interactive terminal session in the current directory. codex
Choose or change the model and reasoning effort in the TUI. /model
Show current session configuration. /status
Review changes and find issues from inside a session. /review
Open the permissions picker and change the active permissions profile. /permissions
Allow read-only inspection; edits and commands requiring approval remain blocked unless approved. codex -s read-only
Use the common local-work preset: workspace writes plus approval when Codex needs escalation. codex -s workspace-write -a on-request
Ask before commands outside the trusted command set. codex -a untrusted
Never ask for approval; command failures return to the model. codex -a never
Route eligible approval requests through automatic review with workspace-write sandboxing. codex --approve-for-me
Skip confirmation prompts and sandboxing. codex --dangerously-bypass-approvals-and-sandbox

69 commands · verified against the installed binary v0.147.0 and the official docs · checked 2026-08-18 source source source source source source source source

Install & authenticate

Put Codex on the machine, sign in, and check the installation.

Command	What it does	Notes
`curl -fsSL https://chatgpt.com/codex/install.sh \| sh` docs	Install or update the standalone CLI on macOS and Linux.
`npm i -g @openai/codex` docs	Install Codex from npm.
`brew install --cask codex` docs	Install Codex with Homebrew.
`codex --version`	Print the installed CLI version.
`codex update`	Update Codex to the latest version.
`codex login`	Authenticate with ChatGPT OAuth, device auth, an API key, or an access token from stdin.
`codex logout`	Remove stored authentication credentials.
`codex doctor`	Generate a diagnostic report for installation, config, auth, runtime, Git, and session issues.

Start & steer a session

Launch the TUI in the right directory with the right model and context.

Command	What it does	Notes
`codex`	Start an interactive terminal session in the current directory.
`codex "explain this repository"`	Start a session with an initial prompt.
`codex -C <dir> "run the tests"`	Use a specific directory as the working root.	Long form: `--cd`.
`codex --add-dir <dir>`	Add another writable directory alongside the primary workspace.
`codex -m <model>`	Choose the model for the session.	Long form: `--model`.
`codex -i screenshot.png "fix the layout"`	Attach one or more images to the initial prompt.	Repeat `-i`/`--image` for multiple files.
`/model`	Choose or change the model and reasoning effort in the TUI.
`/status`	Show current session configuration.
`/review`	Review changes and find issues from inside a session.
`/permissions`	Open the permissions picker and change the active permissions profile.

Approvals & sandbox

Keep filesystem, network, and approval boundaries explicit.

Command	What it does	Notes
`codex -s read-only`	Allow read-only inspection; edits and commands requiring approval remain blocked unless approved.	Other modes: `workspace-write` and `danger-full-access`.
`codex -s workspace-write -a on-request`	Use the common local-work preset: workspace writes plus approval when Codex needs escalation.	`-a` is short for `--ask-for-approval`.
`codex -a untrusted`	Ask before commands outside the trusted command set.
`codex -a never`	Never ask for approval; command failures return to the model.	Pairing this with `danger-full-access` removes the safety boundary.
`codex --approve-for-me`	Route eligible approval requests through automatic review with workspace-write sandboxing.
`codex --dangerously-bypass-approvals-and-sandbox`	Skip confirmation prompts and sandboxing.	Use only inside an external sandbox; it is explicitly dangerous.
`codex --search`	Enable live web search for the session.
`codex --strict-config`	Fail when config.toml contains fields this CLI version does not recognize.

Resume & automate

Continue work interactively, or make a repeatable CI-shaped run.

Command	What it does	Notes
`codex resume`	Open the picker for a previous interactive session.
`codex resume --last`	Resume the most recent session from the current working directory.	Add `--all` to include sessions from other directories.
`codex resume <session-id> "follow up"`	Resume a session by UUID or session name with an optional follow-up prompt.
`codex fork --last`	Fork the most recent interactive session into a new chat.
`codex exec "summarize the repo"`	Run non-interactively and exit after the task completes.	Alias: `codex e`.
`cat prompt.txt \| codex exec -`	Read the prompt from stdin for scripts and pipelines.
`codex exec --json "run the checks"`	Emit machine-readable JSONL events to stdout.
`codex exec -o result.txt "summarize failures"`	Write the final agent message to a file.	Long form: `--output-last-message`.
`codex exec --output-schema schema.json -o result.json "extract metadata"`	Request a final response matching a JSON Schema and save it.
`codex review`	Run a non-interactive review of uncommitted changes, a branch diff, or a commit.

Config & profiles

Layer persistent TOML settings and select a task-specific profile.

Command	What it does	Notes
`~/.codex/config.toml` docs	User-level Codex configuration.
`.codex/config.toml` docs	Project-scoped configuration for a trusted project.
`codex -c key=value`	Override a TOML config value for one invocation.	Use dotted paths for nested values; repeat the flag.
`codex -p <profile>`	Layer `$CODEX_HOME/<profile>.config.toml` over the base user config.	Long form: `--profile`.
`CODEX_HOME=<dir> codex` docs	Use an alternate Codex home for isolated config, auth, and session state.
`AGENTS.md` docs	Project or parent-directory instructions Codex loads as standing guidance.
`codex features`	Inspect feature flags and persistently enable or disable them in config.toml.

MCP servers

Connect local stdio tools or remote Streamable HTTP tools.

Command	What it does	Notes
`codex mcp add <name> -- <stdio-command>`	Register a local stdio MCP server.
`codex mcp add <name> --env KEY=value -- <command>`	Pass environment variables to a stdio MCP server.
`codex mcp list`	List configured MCP servers.
`codex mcp get <name>`	Show one configured MCP server.
`codex mcp login <name>`	Start OAuth login for an MCP server that supports it.
`codex mcp remove <name>`	Remove an MCP server registration.
`/mcp`	Show active MCP servers in the TUI.
`[mcp_servers.<name>]` docs	Configure a server in config.toml; use `command`/`args` for stdio or `url` for Streamable HTTP.
`codex mcp-server`	Run Codex itself as an MCP server over stdio.

Skills & agents

Package repeatable workflows and delegate focused work.

Command	What it does	Notes
`.agents/skills/<name>/SKILL.md` docs	Repository skill location; the file needs `name` and `description` frontmatter.	Codex also scans user, admin, and system skill locations.
`$skill-name` docs	Explicitly invoke a skill in the CLI.	The TUI also exposes skills through `/skills`.
`/skills`	List or select available skills in the TUI.
`[[skills.config]]` docs	Enable or disable a local skill from config.toml.
`spawn two agents ...` docs	Ask Codex to delegate independent work to parallel subagents and combine the results.	Subagents inherit the parent sandbox and approval policy.
`~/.codex/agents/<name>.toml` docs	Define a personal custom agent.	Project-scoped agents live in `.codex/agents/`.
`[agents]` docs	Configure multi-agent enablement, concurrency, default model, and reasoning effort.
`codex plugin`	Install, list, and remove Codex plugins from marketplace sources.

Useful commands

Session housekeeping, shell integration, and less-common surfaces.

Command	What it does	Notes
`codex completion zsh`	Generate shell completion scripts.
`codex apply <TASK_ID>`	Apply a diff generated by a Codex cloud task to the local working tree.	Alias: `codex a <TASK_ID>`.
`codex archive <session>`	Archive a saved session by ID or name.
`codex unarchive <session>`	Restore an archived session.
`codex delete <session>`	Permanently delete a saved session.	Destructive; verify the session identifier first.
`codex sandbox -- <command>`	Run a command inside a Codex-provided sandbox.	Choose the agent-session sandbox separately with `-s`/`--sandbox`.
`codex app`	Launch the ChatGPT desktop app on macOS or Windows.
`codex --no-alt-screen`	Use inline TUI mode and preserve terminal scrollback.
`codex --remote <addr>`	Connect the TUI to a remote app-server over WebSocket or Unix socket.	Experimental workflow; use `--remote-auth-token-env` for a bearer token.