LaoHandDeveloper Cheatsheet

Codex CLI Cheatsheet - OpenAI Terminal Coding Agent Full Reference

Codex CLI is OpenAI official open-source terminal coding agent (Rust) for developers driving GPT-family models to edit code, run tests, and manage approvals directly in a repo — and for CI engineers adopting AI codegen/review. Unlike cloud chat it adds fine-grained sandbox (read-only/workspace-write/full-access) and approval policies, plus headless codex exec --json for pipelines. This sheet covers install/login, non-interactive execution, and the sandbox trade-offs.

AI CLI·54 commands·Last updated 2026-08-05
codexcodex-cliopenaiaicliagentCoding Agent

Typical Use Case

Codex CLI shines at headless automation: codex exec --json turns one-shot jobs (code review, batch comments, config extraction) into parseable JSONL for CI, no TUI babysitting. Interactively it works like a coachable assistant — it shows step state (Thinking/Looking up/Editing/Finished) and uses -a approvals to gate file edits and commands. It is strong at reading large repos in a local sandbox, supports local open-source models via --oss, and AGENTS.md encodes team conventions. For orgs, -p profiles plus config.toml pin a shared default config across a team.

Install & Auth 7

npm install -g @openai/codex
Install globally via npm (all platforms)
brew install --cask codex
Install on macOS via Homebrew
codex --version
Verify install and show version
codex login
Browser OAuth sign-in to ChatGPT
codex login --with-api-key
Read API key from stdin to log in
codex login --device-auth
Headless/SSH device-code login
codex logout
Sign out

Interactive Mode 5

codex
Start an interactive TUI session
codex "Explain this codebase"
Start the TUI with an initial prompt
codex --search "Fix the login bug"
Enable live web search
codex -i ./screenshot.png "Implement this UI"
Attach an image (comma-separate multiple)
codex --oss
Use a local open-source model (Ollama, etc.)

Non-interactive (codex exec) 5

codex exec "Fix the failing tests"
Non-interactive automation mode (alias codex e)
echo "Refactor utils" | codex exec --oss
Pipe input + local model
codex exec --json "List all API endpoints"
Output JSONL for scripting
codex exec -o result.txt "Summarize the architecture"
Save the final response to a file
codex exec --output-schema '{...}' "Extract config"
Constrain output with a JSON Schema

Session Management 5

codex resume
Resume the previous session
codex fork
Fork the previous session into a new thread
codex apply
Apply the latest diff as git apply (alias codex a)
codex --restore
Restore the previous session (some versions)
codex --history
Browse past session history

Model & Config 5

codex -m gpt-5.4 "Complex task"
Set the model (e.g. gpt-5.4 / gpt-5.4-mini)
codex -p openai "Generate a component"
Load a named config profile
codex -C /path/to/repo
Set the working root directory (--cd)
codex -c
Override config.toml values
codex completion bash
Generate bash completion script

Sandbox & Approval 8

codex -s read-only
Sandbox read-only (default, safest)
codex -s workspace-write
Sandbox can write the working directory
codex -s danger-full-access
Full access (use cautiously in containers)
codex -a untrusted
Prompt for untrusted actions (default)
codex -a never
Never approve (for read-only exploration)
codex --full-auto "Complete the implementation"
Auto-approve: workspace-write + on-failure
codex --yolo "Emergency fix"
Skip all sandbox and approvals (dangerous)
codex --dangerously-bypass-approvals-and-sandbox
Fully bypass sandbox and approvals (in containers)

MCP & Codex Cloud 7

codex mcp list
List configured MCP servers
codex mcp add -- <args...>
Add a stdio MCP server
codex mcp add --url https://example.com/mcp
Add an HTTP MCP server
codex mcp get <name>
Show server configuration
codex mcp remove <name>
Remove a server
codex cloud exec --env "task"
Submit a task to Codex Cloud
codex cloud exec --env --attempts 3 "task"
Submit a task with retry attempts (1-4)

Interactive Slash Commands 12

/clear
Reset UI and conversation
/compact
Summarize conversation to free tokens
/new
Start a fresh conversation in the same session
/fork
Clone current conversation into a new thread
/diff
Show git diff including untracked files
/status
Show session config and token usage
/init
Generate an AGENTS.md project scaffold
/review
Code review of working-tree changes
/plan
Switch to plan (read-only) mode
/model
Choose model and reasoning effort
/permissions
Set what Codex can do without asking
/exit
Quit Codex CLI

Command Examples

Run headless and emit JSON

codex exec --json "列出项目里所有 API 端点" codex exec -o endpoints.txt "总结架构"

codex exec（别名 codex e）是非交互事实标准，--json 输出 JSONL，-o 把最终回答存为文件。

Output

{"findings":{"endpoint_count":23,"categories":[...]}}
（最终回答同时写入 endpoints.txt，JSONL 便于 CI 解析）

Fully auto-complete an implementation

codex --full-auto "补齐 payment 模块的单测，改动前先看现有测试风格"

默认 --full-auto 等价于 workspace-write 沙箱 + on-failure 批准，安全且省心，是日常首选。

Output

（模型在禁用网络的沙箱内自行读写工作目录，仅在需要联网装依赖时才退出沙箱询问）

Explore a large repo read-only

codex -a never -s read-only "这个项目的构建流程和依赖拓扑是怎样的"

适合审计、调研、理解历史演进；如需写文件再切回 workspace-write 并加批准。

Output

（只读模式可读取全系统文件，不落任何修改、不弹确认）

Add a stdio MCP server

codex mcp add -- npx -y @modelcontextprotocol/server-github codex mcp list

__ 之后的所有参数原样传给服务器，可让模型在会话里直接调用仓库/工具接口。

Output

Added MCP server "server-github" (stdio)

Common Pitfalls

  • --dangerously-bypass-approvals-and-sandbox and --yolo skip all sandbox and approvals so the model can modify the system and run any command — only in isolated/throwaway environments.
  • Only -a never + -s read-only is truly read-only; -a never alone can still let the model edit files in the working directory.
  • Permission rules written into AGENTS.md make Codex follow team conventions by default but also lock in behavior — confirm impact before editing memory files.
  • codex exec runs unattended with no human approvals, so side-effecting commands rely on the sandbox to bound scope (workspace-write), not on -a prompts.

Tips

  • For non-interactive automation always use `codex exec` + `--json` with CI pipelines for codegen/review — Codex's signature use.
  • The default `--full-auto` auto-approves inside a network-disabled sandbox: safe and hands-off; it only exits the sandbox to ask when it needs network (e.g. npm install).
  • Put project conventions in AGENTS.md (repo root or ~/.codex/); Codex merges and loads them automatically — more efficient than repeating them in prompts.
  • For read-only exploration use `-a never -s read-only`: no prompts yet full file read access, ideal for audits/research.

Related Cheatsheets

6 related cheatsheets

Claude Code CLI Cheatsheet - Anthropic AI Coding Agent Full ReferenceFull command reference for Claude Code, Anthropic terminal AI coding agent: install & auth, -p print mode and session resume, --permission-mode/--worktree, dev slash commands, MCP server management, and @ file references, all flags matching official docs.Gemini CLI Cheatsheet - Google Terminal AI Agent Full ReferenceCommand reference for Gemini CLI, Google open-source (Apache 2.0) terminal AI agent: install & auth, run modes and global flags, session slash commands, MCP/extension management, and GEMINI.md project memory, with a 2M context.Cursor Editor CLI Cheatsheet - AI Editor Command Line & Agent FlagsCommand-line and Cursor Agent reference for Cursor, the VS Code-based AI editor: opening files/folders, window management, diff compare, extension management, rendering & performance, remote dev, debugging, cursor-agent non-interactive calls, and git core.editor integration.Aider Cheatsheet - Open-Source Terminal AI Pair Programming Full ReferenceCommand reference for Aider, the open-source Apache 2.0 terminal AI pair programmer (100+ models, auto git commits): install, model & reasoning, files & context, chat modes, Git & run, session tools, and advanced usage.OpenCode CLI Cheatsheet - Open-Source TUI AI Coding Agent Full ReferenceCommand reference for OpenCode, the open-source Claude Code-style TUI terminal AI coding agent: launch & resume, CLI flags, session and subcommands (agent/auth/github/mcp/run/serve/web), and interactive slash commands.Goose CLI Cheatsheet - Block / Linux Foundation AAIF Agent Full ReferenceCommand reference for Goose, the open-source general-purpose terminal AI agent (Rust, Apache-2.0, 15+ providers, 70+ MCP extensions; orig. Block, now Linux Foundation AAIF): sessions, runtime, configure, extensions, and diagnostics, including goose session/run/configure/cook/doctor and --resume.

Official References

Each command links to its official documentation below, so you can verify the latest usage and read deeper.

Maintained by LaoHand

Publicly updated on Aug 5, 2026, continuously proofread against official docs.

Contact Us

Wrong command or description? Send us corrections, business inquiries or product feedback by email.

Contact Us