Modern Code Consulting

Codex

OpenAI Codex CLI Setup: Install, Sign In and Configure

OpenAI Codex CLI setup guide: install commands for Mac, Linux and Windows, signing in, config.toml, codex exec for scripts, and mistakes we avoid on builds.

By
Published

Last verified

The OpenAI Codex CLI installs in one command and takes about two minutes to sign in. Run npm install -g @openai/codex, type codex in a project folder, pick Sign in with ChatGPT, and you are talking to a coding agent that can read the repo, edit files and run commands. The rest of this guide covers what happens after that first prompt: the config that decides how much freedom the agent gets, the commands for scripted runs, and the setup mistakes we have made so you do not repeat them.

We use Codex as a second lane next to Claude Code on long builds, so this is written from that seat. If you want the comparison between the two tools, we wrote it up in Claude Code vs Codex. If you want the whole agent setup done for your business, that is our Claude Code and Codex setup service.

Install the OpenAI Codex CLI

There are four install routes and they end up with the same codex binary. We pick the one that matches how the machine is managed.

  • npm suits a box where Node is already installed and you want Codex next to your other global tools.
  • Homebrew suits a Mac where everything else comes from brew.
  • The standalone installer suits a fresh server or a machine with no Node. It downloads from releases.openai.com and falls back to GitHub Releases.
  • The PowerShell installer is the Windows route in OpenAI's README. The docs we fetched give no WSL-specific guidance, so if you run Windows with WSL, test the install on the Linux side and see which route holds up for you.

Updating works like installing: the docs list the standalone installer command under "Update Codex". If you installed through npm or brew, update through that tool so you do not end up with two copies on the PATH. The symptom of two copies is a version number that never changes after you "update".

Sign in: ChatGPT account or API key

On first run, codex asks how to sign in. OpenAI recommends the ChatGPT account route so Codex usage counts against your plan. An API key works too, with extra setup, and usage is billed at API rates instead of against a plan allowance.

For a personal machine, sign in with the account. For a server that runs scheduled jobs, use an API key set for one command at a time. OpenAI's non-interactive docs show CODEX_API_KEY=<key> codex exec --json "<task>" and warn against setting the key as a job-level environment variable in workflows that run repository code, because build scripts and dependencies could read it. The same docs say to treat a saved ~/.codex/auth.json like a password.

Configure ~/.codex/config.toml

Two settings matter on day one: approval_policy, which decides when Codex stops to ask before running a command, and sandbox_mode, which decides what those commands can touch. This is the shape of the file, using the keys from OpenAI's config page:

model = "gpt-6.1-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"

Treat the model name as an example from the docs on the day we checked, not a recommendation. Model names change often, so look at what your install defaults to before you pin one.

Precedence runs from CLI flags, then a project .codex/config.toml, then any profile you select, then your user file, then system and built-in defaults. A project config only loads after you trust the project, which is a sensible default: a cloned repo cannot quietly loosen your sandbox.

Codex also reads an AGENTS.md file for project instructions. If you already keep a CLAUDE.md, the cleanest setup is one AGENTS.md as the source of truth with a CLAUDE.md that imports it. That is how this site's repo is wired, so both agents read the same rules.

Run Codex in scripts with codex exec

For business work, codex exec matters more than the chat window. It runs one task, streams progress to stderr and prints only the final message to stdout, so you can pipe it or redirect it to a file.

codex exec "Summarize failing tests in this repo" -o summary.txt
codex exec --sandbox workspace-write "Fix the lint errors in app/"
cat error.log | codex exec "Explain the root cause of this failure"

We reach for three flags: --json for a machine-readable event stream, -o to write the last message to a file, and --output-schema when a downstream script needs the answer in a fixed shape. The default sandbox is read-only, so a run that should edit files needs --sandbox workspace-write. The older --full-auto flag is no longer supported.

This is the same pattern behind the recorded run on our lead list personalization page: an agent makes the judgment calls and a script does the exact work. That page was built with Claude Code, and the pattern carries over to Codex as long as each run has one narrow job.

Plans, limits and commands as of November 19, 2026

This is the section that goes stale, so it is dated and kept in one place. Everything in it comes from OpenAI's own pages, fetched on November 19, 2026.

ItemWhat OpenAI publishes
Install (npm)npm install -g @openai/codex
Install (Homebrew)brew install --cask codex
Install (Mac and Linux)curl -fsSL https://chatgpt.com/codex/install.sh | sh
Install (Windows)powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
Plans listing Codex CLIPlus ($20/month), Pro (from $100/month), Business, Enterprise and Edu, or an API key
Plus usage limitEstimates per model per five-hour period, not fixed message counts
Pro usage limitThe pricing page says Pro plans currently have no five-hour limit

The per-model limit ranges are wide and move often, so we do not copy them here. Read the current numbers on the OpenAI pricing page and the Codex CLI docs before you commit a team to a plan. The docs also moved from developers.openai.com to learn.chatgpt.com, so older bookmarks redirect.

Mistakes we would avoid

  1. Opening the sandbox wide on day one. Start with workspace-write and on-request, and loosen one setting at a time when a task proves it needs it.
  2. Forgetting that codex exec is read-only by default. A scripted run that "succeeds" and changes nothing looks like a prompt problem for far too long when it is a sandbox setting.
  3. Putting an API key in job-level environment variables on a CI runner that builds code you do not control.
  4. Giving one run several jobs. A narrow task with a stated done condition finishes. A vague one wanders, and you pay for the wandering.

What we would do

Install with whichever route matches the machine, sign in with a ChatGPT account on your own laptop, and keep the first week interactive so you learn how it reads your repo. Write an AGENTS.md before you script anything. Then move one repeating job into codex exec, read-only at first, and add write access once the output looks right.

If you want that set up on your own stack, including the instruction files, the scripted runs and the guardrails, our Claude Code and Codex service covers it.

Frequently asked questions

How do I install the OpenAI Codex CLI?
Run npm install -g @openai/codex, or brew install --cask codex, or use the standalone installer: curl -fsSL https://chatgpt.com/codex/install.sh | sh on Mac and Linux, or the PowerShell installer on Windows. Then run codex in a project folder and choose Sign in with ChatGPT. The exact commands are in the dated section above.
Is the Codex CLI free?
The CLI itself costs nothing to install, but running it uses either a ChatGPT plan that includes Codex or an API key billed at API rates. OpenAI lists Codex CLI under Plus, Pro, Business, and Enterprise and Edu plans as of November 19, 2026, and its pricing page did not list Free or Go in that table. Check the pricing page before you plan around a free tier.
What is the difference between codex and codex exec?
codex opens the interactive terminal session where you chat with the agent and approve actions, while codex exec runs one task non-interactively and prints the final message to stdout. Use codex exec in scripts, cron jobs and CI. It starts in a read-only sandbox, so you pass --sandbox workspace-write when the task needs to edit files.
Where does the Codex CLI keep its config?
User-level settings live in ~/.codex/config.toml, and a repo can add a .codex/config.toml that only loads once you trust the project. CLI flags override both. A system file at /etc/codex/config.toml sits near the bottom of the precedence list on Unix.

Want this built for your business?

Book a free 15-minute call. Tell us what's eating your team's hours and we'll tell you what we'd automate first, how we'd build it and what it would cost.

Book a free automation audit