Command and Configuration Cheatsheet
📚 Series Navigation: The previous article [34 Capstone Project] took you through running a complete project by stringing all the previous components together, which was the 'integration'. This article does the opposite—extracting all the commands, flags, and configuration keys scattered across more than thirty articles and condensing them into a cheatsheet that you can stick on the side of your monitor. The next article [36 Best Practices] will wrap up the entire Codex series by focusing on 'how to use it right'.
Let me share something embarrassing.
During my first two months using Codex, I had a file named codex-备忘.txt on my computer, with messy notes like 'exporting JSON is --json' and 'writing the last message to a file is -o'. The problem was that my notes were messy. Every time I wanted to use codex exec to write results to a file, I would first check this txt file. If I couldn't find it, I'd check the shell history history | grep codex. If that failed too, I'd open a browser to search the official documentation—what should have been a single command could take me five minutes.
Even dumber was configuration. Once, I wanted to temporarily disable sandbox networking for a project. I remembered there was a key starting with sandbox_workspace_write, but I completely forgot what followed it. Was it network? net_access? I blindly guessed in config.toml until Codex threw a startup error. In the end, I had to look up the config-reference to find out it was sandbox_workspace_write.network_access. At that moment, I decided: Instead of looking things up every single time, it's better to extract all the high-frequency commands and configurations once and arrange them in a table, so I can just glance at whatever I need and get going.
This article is the final product of that table. It doesn't explain the principles (which have already been covered), but does just one thing—allowing you to search quickly, copy accurately, and stop opening your browser.
After reading this article, you will get:
- A cheatsheet covering installation/login, CLI commands and flags, slash commands, and high-frequency configuration items in
config.toml - A comparison table of permission sandbox levels, models, and reasoning effort, allowing you to fill them in without falling into traps
- A list of 'critical entry points' for advanced capabilities like MCP (Model Context Protocol), subagents, and Skills, so you know which command to start with
- A small example to verify and confirm that the commands you found actually take effect on your local machine
⚠️ Commands, flags, and configuration keys are subject to the official documentation and may change with versions; model names and default values change with versions and your account, and are subject to the actual behavior of your local
codex --helpandconfig.toml; confirm the current version withcodex --version. Items marked as 'experimental' below will be noted at the beginning, so pay attention before using them.
01 Installation and Login
Whether installing for the first time, switching machines, or pulling it up again in CI, these are the most commonly used commands. Analogy: This is Codex's 'startup trifecta'—install it, log in, and confirm it logged in successfully. It won't work if any step is missing.
Under domestic networks, the installation script and login via OAuth may require a VPN or proxy, otherwise they are prone to getting stuck at the download or callback step.
| Purpose | Command | Platform / Notes |
|---|---|---|
| Standard Installation (Script) | curl -fsSL https://chatgpt.com/codex/install.sh | sh | macOS / Linux |
| Standard Installation (Script) | powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" | Windows |
| Install via npm | npm install -g @openai/codex | All platforms, requires Node.js |
| Install via Homebrew | brew install --cask codex | macOS |
| Update to latest version | codex update | Available when the distribution supports self-update |
| Login (Browser OAuth) | codex login | Default method, opens browser to log in to ChatGPT |
| Login (Device Code) | codex login --device-auth | Used when a browser cannot be opened (e.g., remote servers) |
| Login with API Key | printenv OPENAI_API_KEY | codex login --with-api-key | Reads key from stdin |
| Check Login Status | codex login status | Exit code is 0 if logged in, suitable for script conditional checks |
| Logout | codex logout | Clears local credentials |
| Diagnostic Checkup | codex doctor | Run after installation or when issues occur to self-check installation, configuration, authentication, Git, etc. |
💡 One-line summary: Run
codex doctorfor a health check first after installation, then usecodex login statusto confirm the login state, which will save you half the detours compared to jumping straight in.
02 Commonly Used codex CLI Commands and Flags
This is the most core part of the entire article. Analogy: codex is the main program, followed by 'subcommands' (where to go), and then --xxx flags (how to get there). Memorize the subcommands first, then the flags, and combining them yields a complete command.
Commonly Used Subcommands
| Subcommand | Function | Maturity |
|---|---|---|
codex | Starts the interactive Terminal User Interface (TUI); this is the default when no subcommand is provided | Stable |
codex exec | Runs non-interactively once and exits immediately; shorthand is codex e | Stable |
codex resume | Resumes the conversation from the last interactive session | Stable |
codex fork | 'Forks' a session into a new thread, leaving the original history untouched | Stable |
codex apply | Applies the diff generated by a cloud task to the local workspace; shorthand is codex a | Stable |
codex mcp | Manages MCP servers (list / add / remove / login) | Experimental |
codex features | Lists feature flags and persistently enables/disables them | Stable |
codex completion | Generates shell completion scripts | Stable |
High-Frequency Global Flags (Following codex or Most Subcommands)
| Flag | Action | Value / Notes |
|---|---|---|
--model / -m | Temporarily switch models | e.g., -m gpt-5.5 |
--image / -i | Attach images to the initial prompt | Separate multiple images with commas or repeat -i |
--cd / -C | Specify the working directory before starting | Accepts a path |
--sandbox / -s | Choose sandbox level | read-only / workspace-write / danger-full-access |
--ask-for-approval / -a | Choose approval policy | untrusted / on-request / never |
--search | Enable live web search | Switches web_search to live (default is cached) |
--add-dir | Grant write permissions to an additional directory | Can be repeated, safer than granting full disk access |
--profile / -p | Apply a configuration profile | Layered on top of the base configuration |
--config / -c | Temporarily modify configuration via command line | -c key=value, parsed as TOML if valid |
--yolo | Skip all approvals and sandbox restrictions | Dangerous, use only in isolated environments |
codex exec (Non-interactive) Exclusive High-Frequency Flags
This is the group most commonly used for writing scripts and running CI. Analogy: Interactive mode is like ordering food at a restaurant, while codex exec is like ordering delivery—you place the order and leave, and the results are sent to your specified location.
| Flag | Action |
|---|---|
PROMPT set to - | Read prompt from stdin (e.g., cat prompt.txt | codex exec -) |
--json | Output a newline-delimited JSON (JSONL) event stream, convenient for jq parsing |
--output-last-message / -o | Write the final reply to a file (while still printing to stdout) |
--output-schema | Provide a JSON Schema to force the final output to match this structure |
--skip-git-repo-check | Allow execution in non-Git directories |
--ephemeral | Do not store session history on disk |
--full-auto | Deprecated compatibility flag, will print a warning; new scripts should switch to --sandbox workspace-write |
codex exec resume --last | Resume from the most recent exec session |
💡 One-line summary: Remember these four things:
-mto switch models,-sto adjust sandboxing,-ato adjust approvals, and-o/--jsonto receive results—and you'll have 80% of command-line scenarios covered.
03 Slash Commands (Entered in the TUI)
Slash commands are only used in the interactive interface—once inside codex's full-screen interface, typing / pops up the menu. Analogy: They are 'shortcut buttons' in the session; you don't need to exit to type a command, just type a slash to switch things on the fly.
Below are the ones I use most frequently. The complete list is subject to the menu that pops up with / on your local machine, which may vary across versions.
| Slash Command | Function |
|---|---|
/model | Switch the current model (and adjust reasoning effort together if available) |
/status | View current model, approval policy, writable directories, and remaining context |
/compact | Condense long conversations into a summary to free up context space |
/diff | View Git diff, displaying even untracked new files |
/permissions | Adjust mid-way what actions Codex can perform without asking |
/review | Have Codex review the changes in your current workspace |
/init | Generate the AGENTS.md scaffolding in the current directory |
/mcp | List MCP tools callable in the current session (add verbose for details) |
/skills | Browse and select local skills |
/agent | Switch between spawned subagent threads |
/fast | Turn on/off the current model's Fast service tier (/fast on/off/status) |
/new | Start a brand new conversation within the same CLI session |
/clear | Clear screen and start a new conversation |
/quit or /exit | Exit the CLI |
A quick reminder: /fast is 'model catalog driven'—if the current model does not provide a Fast tier, /fast will not appear in the menu at all. Don't mistake this for a bug.
💡 One-line summary: The four most high-frequency commands in a session are:
/modelto change brains,/statusto check current status,/compactto clear the space, and/diffto verify results. Train these four into muscle memory first.
04 Commonly Used config.toml Configuration Items
The configuration file is located at ~/.codex/config.toml (TOML format), serving as Codex's 'long-term memory'. Analogy: Command-line flags dictate 'how to run this trip', whereas config.toml dictates 'how to run by default from now on'. You can also place a .codex/config.toml in your project directory for project-level overrides (requires trusting the project first).
Only high-frequency items are listed below; see the official config-reference for the full list.
| Config Key | Action | Value Example |
|---|---|---|
model | Default model | "gpt-5.5" |
model_reasoning_effort | Reasoning effort | minimal / low / medium / high / xhigh |
model_reasoning_summary | Reasoning summary detail level | auto / concise / detailed / none |
service_tier | Service tier | flex / fast (speed-up related, used in conjunction with /fast) |
sandbox_mode | Sandbox level | read-only / workspace-write / danger-full-access |
sandbox_workspace_write.network_access | Whether to allow network access in workspace-write mode | true / false |
sandbox_workspace_write.writable_roots | Additional writable directories | ["/path/a", "/path/b"] |
approval_policy | Approval policy | untrusted / on-request / never |
web_search | Web search mode | disabled / cached / live (default is cached) |
review_model | Model used by /review | If left blank, the current session model is used |
model_instructions_file | Use a specific file to replace built-in instructions | A file path |
A minimal working config.toml looks like this; copy and modify it to use:
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = false💡 One-line summary: Setting the four keys
model,model_reasoning_effort,sandbox_mode, andapproval_policyinconfig.tomldefines Codex's 'default personality', leaving temporary invocation flags to override them.
05 Permissions and Sandbox Levels
The sandbox determines to what extent Codex can modify your machine, while the approval policy determines whether it asks before acting. These two work together as a combo. Analogy: The sandbox dictates 'which rooms the intern can enter', and the approval policy dictates 'whether he needs to call you before making changes'.
Sandbox Level (--sandbox / sandbox_mode) | What it can do | Suitable Scenarios |
|---|---|---|
read-only | Read-only, cannot modify files | Have it read and analyze first, without touching the code |
workspace-write | Can modify files within the workspace | The sweet spot for daily local development |
danger-full-access | Full disk read/write, unrestricted network | Use only in isolated containers / CI runners |
Approval Policy (--ask-for-approval / approval_policy) | Meaning |
|---|---|
untrusted | Approve only commands it deems trusted, ask for everything else |
on-request | Recommended value for interactive runs; pauses to ask you only when needed |
never | Never ask; used for non-interactive/CI runs |
The official recommendation for low-friction local work is just one line:
codex --sandbox workspace-write --ask-for-approval on-requestAdding two lessons I learned: If you want to grant Codex access to an additional writable directory, don't go straight to danger-full-access for convenience; use --add-dir to precisely authorize just that single directory; --full-auto is an old compatibility style that has been deprecated, and all new scripts should switch to --sandbox workspace-write.
💡 One-line summary: Local default is '
workspace-write+on-request', CI uses 'specified sandbox +never', and if you want to grant permissions, think first if you can use--add-dirinstead of opening everything.
06 Model and Reasoning Effort Comparison
Selecting a model is 'who to send', while adjusting reasoning effort is 'how long to let them think before acting'. These two knobs are independent. Analogy: The model is the person you hire, and reasoning effort is the thinking time you give them—don't make an expert ponder over a simple chore, and don't let a novice rush through a tough challenge.
| Model | Positioning | When to use |
|---|---|---|
gpt-5.5 | Flagship, strongest | Complex programming, refactoring, and heavy research tasks |
gpt-5.4-mini | Lightweight, fast, cost-effective | Miscellaneous tasks, batch operations, subagents |
gpt-5.3-codex-spark | Instant research preview (ChatGPT Pro only) | Real-time iterations seeking near-instantaneous responses |
gpt-5.2 and gpt-5.3-codex are deprecated; stop writing them in configurations or --model.
Reasoning effort is controlled by model_reasoning_effort with five levels:
| Value | Thinking Intensity | Typical Scenarios |
|---|---|---|
minimal | Minimal thinking, fastest | Fixing typos, renaming, running a command |
low | A slight ponder | Minor bug fixes |
medium | Default sweet spot | Vast majority of daily programming |
high | Deep deliberation | Multi-file changes, design trade-offs |
xhigh | Maximum (model-dependent) | Truly tough challenges that are worth the wait |
My own default is using 'gpt-5.5 + medium' for everything, raising it to high manually only when I'm certain I'm tackling a tough challenge. In article 30, I mentioned the stupid mistake I made—locking it to xhigh long-term and waiting a minute just to fix a typo. The time saved by avoiding that 'strongest anxiety' is way more than you think.
💡 One-line summary: Use 'flagship +
medium' for daily tasks, drop tominimal/lowfor routine labor, raise tohigh/xhighonly for tough challenges, and don't touch any deprecated models.
07 MCP / Subagents / Skills Critical Entry Points
These three are all advanced capabilities, whose principles have their own dedicated articles (Articles 20, 21, and 22). Here, we only provide the entry points for 'which command/configuration to start from', saving you from scrolling back. Analogy: This is the 'door handle location' for these three doors—remember where the handles are, and refer to the dedicated articles for details on how to push the doors open.
| Capability | Critical Entry Point | Description |
|---|---|---|
| MCP (External tools, like a USB port) | codex mcp list / codex mcp add <name> ... | Manage servers via command line; use /mcp in a session to view available tools (experimental) |
| MCP (HTTP server login) | codex mcp login <name> | Only supports streamable HTTP servers with OAuth |
| Configure MCP Servers | [mcp_servers.<id>] in config.toml | Keys like command/args/url define a server |
| Subagents (Parallel execution) | [agents] / agents.<name>.* in config.toml | max_threads defaults to 6; use /agent in a session to switch threads |
| Skills (Task-specific skills) | /skills in a session | Browse and select; use [[skills.config]] (with path/enabled) in config.toml to override and enable |
Note that the entire codex mcp suite is currently marked as 'experimental'. Subcommands and behaviors may change with versions; refer to codex mcp --help before using.
💡 One-line summary: MCP uses the
codex mcpcommand, subagents rely on the[agents]configuration +/agentswitching, and Skills are selected with/skills—remembering these three entry points ensures you'll never wonder 'where do I start' with advanced capabilities.
08 Hands-on: Verify the Commands You Found Actually Take Effect
No matter how comprehensive the cheatsheet is, it is better to run a command yourself to confirm that it actually works on your local machine. Below is a minimal three-step example that does not depend on any existing projects.
Step 1: Confirm login status (does not modify anything, purely checking):
codex login statusExpected output: If logged in, the current authentication method will be printed with an exit code of 0; if not logged in, it will prompt you to run codex login.
Step 2: Run a non-interactive command to write the result to a file—verifying codex exec, -o, and the read-only sandbox all at once:
codex exec --sandbox read-only -o /tmp/codex-check.txt "用一句话说明当前目录是不是一个 Git 仓库"Expected: The terminal prints that sentence, and /tmp/codex-check.txt (replace with your temporary directory on Windows) also writes the exact same sentence. Seeing the content when opening the file indicates that -o works.
Step 3: Confirm that you did not misremember the flag name—ask the CLI directly:
codex exec --helpExpected: Lists all flags supported by codex exec. Whenever you are unsure whether a flag exists or what it is called, --help is always the most up-to-date and accurate reference, even more so than this cheatsheet.
💡 One-line summary:
login statusverifies login,codex exec -overifies that the command actually works, and--helpverifies that the flag names are correct—running these three successfully shows that the cheatsheet is 'live' on your local machine.
Summary
This article did not introduce new concepts, but condensed the 'feel' from the previous thirty-plus articles into seven tables:
- Startup Trifecta: Installation,
codex login, andcodex login statusconfirmation; runcodex doctorfirst if issues arise. - CLI Commands and Flags: Subcommands dictate 'where to go', and flags dictate 'how to get there'. The high-frequency five-piece set consists of
-m/-s/-a/-o/--json. - Slash Commands: Train
/model,/status,/compact, and/diffin the session into muscle memory first. config.toml: Setmodel,model_reasoning_effort,sandbox_mode, andapproval_policyto define the default personality.- Permissions & Sandbox: Local is '
workspace-write+on-request', CI is 'specified sandbox +never', and prioritize--add-dirover full access when granting permissions. - Model & Effort: Rule the world with flagship
gpt-5.5+medium; do not touch deprecated models. - Advanced Entry Points: MCP goes through
codex mcp, subagents rely on[agents], and Skills are selected with/skills.
You should now be able to: Discard that messy cheat sheet txt file. Whichever command, configuration key, or level you need, just scan this page and go; use --help as a backup when unsure, without having to open a browser to search the documentation.