View source for Codex‑CLI Power User Guide (2025)

<span id="codexcli-power-user-guide-2025"></span>
= Codex‑CLI Power User Guide (2025) =

<span id="what-is-codexcli"></span>
== 1) What is Codex‑CLI? ==

Codex‑CLI is a '''local coding agent''' you run from your terminal. It can '''read files''', '''edit code''', and '''run commands''' in the directory you choose. You talk to it with plain English (and even attach screenshots). It plans, makes diffs, runs tests, and iterates — like a teammate who works directly in your repo.

'''Great for:''' fixing CI failures, adding tests, refactors, feature spikes, migration work, documentation, “what broke?” investigations.


-----

<span id="quick-setup-macos-linux"></span>
== 2) Quick Setup (macOS &amp; Linux) ==

<syntaxhighlight lang="bash"># Install (pick one)
npm install -g @openai/codex
brew install codex

# Run
codex</syntaxhighlight>
'''First run:''' log in with your ChatGPT account (Plus/Pro/Team/Edu/Enterprise) or use an API key.

'''Windows:''' use WSL for best results.


-----

<span id="your-first-session-5-minutes"></span>
== 3) Your First Session (5 minutes) ==

<ol style="list-style-type: decimal;">
<li><p>'''Open the repo''' you want Codex to work in:</p>
<syntaxhighlight lang="bash">cd ~/code/my-app
codex</syntaxhighlight></li>
<li><p>'''Tell it the job:'''</p>
<pre>&quot;Add unit tests for the cart service and fix any failing ones.&quot;</pre></li>
<li><p>'''Watch the plan → diffs → runs.'''</p></li>
<li><p>If you like the changes, '''commit''' (you can ask Codex to make a conventional commit message too).</p></li></ol>

<blockquote>Tip: Start with '''one clear goal'''. Let Codex finish, then give the next goal.
</blockquote>

-----

<span id="models-reasoning-use-the-best"></span>
== 4) Models &amp; Reasoning — use the best ==

<ul>
<li><p>In the Codex UI, type:</p>
<pre>/model</pre>
<p>then choose '''GPT‑5‑Codex''' and set '''Reasoning: High''' for tough jobs.</p></li>
<li><p>From the shell (non‑interactive):</p>
<syntaxhighlight lang="bash">codex --model gpt-5-codex</syntaxhighlight></li></ul>

'''When to pick High reasoning:''' big refactors, flaky CI hunts, performance work, multi‑step migrations.


-----

<span id="approval-sandbox-modes-safety-vs.-speed"></span>
== 5) Approval &amp; Sandbox Modes (safety vs. speed) ==

Codex can act with different levels of freedom:

* '''Auto (default):''' edits and runs inside the current directory. Asks before touching things '''outside''' your workspace or using the '''network'''.
* '''Read‑Only:''' plan and review only. No file writes or command runs.
* '''Full Access:''' no prompts — fastest, but use with care.

Switch inside the UI:

<pre>/approvals</pre>
<blockquote>Tip: Keep '''Auto''' for everyday use. Switch to '''Full Access''' only when you trust the task and the repo state.
</blockquote>

-----

<span id="attach-images-logs-screenshots-diagrams"></span>
== 6) Attach Images (logs, screenshots, diagrams) ==

Codex understands images — useful for test failures, UI issues, or error screenshots.

<syntaxhighlight lang="bash">codex -i screenshot.png "Explain this error and fix the cause"
# or multiple
codex --image img1.png,img2.jpg "Summarize these diagrams and generate code"</syntaxhighlight>

-----

<span id="noninteractive-mode-scripts-ci"></span>
== 7) Non‑interactive mode (scripts &amp; CI) ==

Run a single instruction without opening the TUI:

<syntaxhighlight lang="bash">codex exec "find TODOs and create a .plans/ file per TODO with a step‑by‑step implementation plan"</syntaxhighlight>
'''Ideas:''' nightly autofix for flaky tests, automated changelog cleanups, codebase audits, dead‑code sweeps.


-----

<span id="bestpractice-workflow"></span>
== 8) Best‑practice Workflow ==

'''Before each big task'''

<ul>
<li><p>Make a '''git checkpoint''':</p>
<syntaxhighlight lang="bash">git checkout -b chore/codex-checkpoint-2025-10-10
git commit -am "checkpoint: before Codex task"</syntaxhighlight></li>
<li><p>Tell Codex the '''constraints''' (style, frameworks, minimum versions, CI tools).</p></li>
<li><p>Keep prompts '''short and concrete'''; let Codex propose a plan.</p></li></ul>

'''While it works'''

* Ask Codex to '''explain diffs''' and '''justify''' changes.
* If it’s heading the wrong way, say '''“stop, new plan”'''.

'''After'''

* Run your test suite yourself once.
* Ask Codex for a '''conventional commit message''' or a '''PR description'''.


-----

<span id="powerful-prompt-patterns-copypaste"></span>
== 9) Powerful Prompt Patterns (copy‑paste) ==

<ul>
<li><p>'''Refactor safely'''</p>
<blockquote><p>“Refactor the <code>user/profile</code> module to remove duplicated logic. Keep public APIs stable. Add tests that codify the new behavior.”</p></blockquote></li>
<li><p>'''Kill a flaky test'''</p>
<blockquote><p>“Find the three flakiest tests in this repo and stabilize them. Show me a short summary of root causes.”</p></blockquote></li>
<li><p>'''Performance pass'''</p>
<blockquote><p>“Profile the slowest API endpoint locally, propose 3 fixes, implement the least risky one, and add a benchmark script.”</p></blockquote></li>
<li><p>'''Security sweep'''</p>
<blockquote><p>“Scan for unsafe deserialization or SQL injection in <code>server/</code>. Add minimal fixes and unit tests.”</p></blockquote></li>
<li><p>'''Documentation'''</p>
<blockquote><p>“Create a <code>docs/architecture.md</code> with an overview diagram and key data flows. Link to code folders.”</p></blockquote></li>
<li><p>'''Bug report to fix'''</p>
<blockquote><p>“Reproduce the bug described in <code>issues/1245.md</code>. Write a failing test, then fix it.”</p></blockquote></li></ul>


-----

<span id="configuration-make-it-yours"></span>
== 10) Configuration (make it ''yours'') ==

Codex stores settings in <code>~/.codex/config.toml</code>. Common tweaks:

<pre class="toml"># ~/.codex/config.toml

# Use the best model by default
model = &quot;gpt-5-codex&quot;
# Reasoning effort: &quot;low&quot; | &quot;medium&quot; | &quot;high&quot;
model_reasoning_effort = &quot;high&quot;

# When to pause for approval: &quot;read-only&quot; | &quot;on-request&quot; | &quot;auto&quot;
approval_policy = &quot;auto&quot;

# How much access Codex has to your files/network
sandbox_mode = &quot;workspace-write&quot;

# Limit which env vars Codex can forward to spawned commands
[shell_environment_policy]
include_only = [&quot;PATH&quot;, &quot;HOME&quot;]

# Optional: different setups
[profiles.safe]
model = &quot;gpt-5-codex&quot;
model_reasoning_effort = &quot;medium&quot;
approval_policy = &quot;read-only&quot;

[profiles.speed]
model = &quot;gpt-5-codex&quot;
model_reasoning_effort = &quot;high&quot;
approval_policy = &quot;auto&quot;</pre>
Use a profile on the fly:

<syntaxhighlight lang="bash">codex --profile safe</syntaxhighlight>
<blockquote>Tip: Check this file into '''dotfiles''', not into your project repo.
</blockquote>

-----

<span id="mcp-model-context-protocol-give-codex-tools"></span>
== 11) MCP (Model Context Protocol) — give Codex ''tools'' ==

MCP lets Codex connect to external tools and extra context (docs, browsers, etc.). Two common ways:

<ul>
<li><p>'''Interactive:'''</p>
<syntaxhighlight lang="bash">codex mcp add</syntaxhighlight>
<p>(Follow the prompts to register a server.)</p></li>
<li><p>'''Config‑based (example):'''</p>
<pre class="toml"># ~/.codex/config.toml
[mcp_servers.docs]
command = &quot;npx&quot;
args = [&quot;-y&quot;, &quot;@modelcontextprotocol/server-docs&quot;]</pre></li></ul>

'''Good starters:''' a docs server for your framework, a browser/search server, a GitHub helper. Only connect servers you trust.


-----

<span id="login-upgrades-and-headless-machines"></span>
== 12) Login, Upgrades, and Headless machines ==

<ul>
<li><p>'''Normal login:''' run <code>codex</code> and choose '''Sign in with ChatGPT'''.</p></li>
<li><p>'''API‑key login (headless / CI):'''</p>
<syntaxhighlight lang="bash">printenv OPENAI_API_KEY | codex login --with-api-key</syntaxhighlight></li>
<li><p>'''Upgrade:'''</p>
<syntaxhighlight lang="bash">npm install -g @openai/codex@latest
# or
brew upgrade codex</syntaxhighlight></li></ul>


-----

<span id="speed-reliability-tips"></span>
== 13) Speed &amp; Reliability Tips ==

* Keep your '''working directory small''' (avoid checking out giant monorepos if you only need one package; <code>cd</code> into the subfolder you care about).
* '''State is power''': add an <code>AGENTS.md</code> at your repo root with architecture notes, naming rules, and “how to run tests”. Codex will use it as memory.
* Prefer '''one big goal''' → finish → '''next big goal'''. Avoid stacking five unrelated tasks.
* When Codex stalls, ask: '''“Summarize the plan so far and what you need.”'''
* Save '''reusable prompts''' in <code>.plans/</code> or <code>scripts/codex/</code>.


-----

<span id="safety-privacy"></span>
== 14) Safety &amp; Privacy ==

* Use '''Read‑Only''' when exploring unfamiliar repos.
* Keep '''Auto''' for day‑to‑day to avoid surprises outside your workspace.
* Consider '''Zero‑Data Retention''' options if your company requires it.
* Limit environment variables (see <code>shell_environment_policy</code>).


-----

<span id="troubleshooting-quick-wins"></span>
== 15) Troubleshooting Quick Wins ==

* '''Login fails on a remote server:''' try API‑key login via stdin (see above).
* '''CLI is old:''' upgrade Codex (see upgrade commands) and try again.
* '''MCP server flaky:''' disable the server, re‑add later. Keep only what you need.
* '''Weird diffs?''' Ask Codex to '''explain the change''' and back it out if needed.
* '''Windows quirks:''' prefer '''WSL'''.


-----

<span id="handy-oneliners"></span>
== 16) Handy One‑Liners ==

<syntaxhighlight lang="bash"># Switch model on launch
codex --model gpt-5-codex

# Use a safer profile
yes | codex --profile safe "Review all changes in src/ and propose a cleanup plan"

# Fix CI quickly (non‑interactive)
codex exec "Diagnose failing CI job and push the minimal fix with tests"

# Add tests for a folder
codex "Write unit tests for services/payment. Keep public APIs stable."

# Generate release notes from commits
yarn release && codex "Draft release notes from last 50 commits with links"</syntaxhighlight>

-----

<span id="where-to-go-next"></span>
== 17) Where to go next ==

* Try the '''IDE extension''' (VS Code, Cursor, Windsurf) if you prefer editing in your editor.
* Explore '''cloud tasks''' if you want to spin up parallel sandboxes for larger jobs.
* Wire up the '''TypeScript SDK''' or '''GitHub Action''' for CI / automation.


-----

'''You’re ready!''' Keep prompts clear, review diffs, and let Codex handle the heavy lifting. Happy shipping 🚀