How to install OpenAI Codex CLI (and what happened when I used it)

I spend an unreasonable amount of time testing AI tools that promise to make work faster.

Some are useful. Some create more work than they save. And some produce an enthusiastic pile of code that looks convincing until you try to run it.

Codex CLI is more interesting.

It is OpenAI’s open-source coding agent for the terminal. You open it inside a project, describe what you need, and it can inspect the repository, explain unfamiliar code, edit files and run commands – with permissions you control.

That last part matters. Codex is not just a chatbot sitting beside your code. It can actually work on it.

What is Codex CLI?

Codex CLI is a coding agent that runs from your terminal. It can:

  • Read and explain an existing codebase.
  • Find the files responsible for a feature or bug.
  • Write and edit code.
  • Run tests, builds and other terminal commands.
  • Review its own changes.
  • Work through larger tasks over several steps.

The interface runs locally, inside the directory you choose. However, prompts and relevant project context are sent to OpenAI’s models for processing. It would therefore be misleading to say your source code never leaves your machine.

What you do control is which project Codex can access, what it is allowed to change and whether commands require your approval.

Before you install it

You will need:

  • A supported macOS or Linux machine.
  • Windows 11 with WSL2 if you use Windows.
  • A terminal.
  • An OpenAI or eligible ChatGPT account.
  • A project you can safely experiment with.
  • Git, ideally, so you can inspect or reverse changes.

OpenAI currently lists macOS 12+, Ubuntu 20.04+/Debian 10+ and Windows 11 through WSL2 among the supported environments. Git is optional but recommended. Check the current system requirements.

How to install Codex CLI

OpenAI now provides a standalone installer, which is the simplest option for most readers.

macOS and Linux

Open your terminal and run:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Once installation finishes, check that Codex is available:

codex --version

Windows

Codex’s documented Windows environment is WSL2. If you already use WSL, open its terminal and follow the Linux installation above.

OpenAI also publishes a PowerShell installer:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Install with npm

If you already have a current version of Node.js and npm, you can install Codex this way:

npm install -g @openai/codex

Then confirm the installation:

codex --version

Install with Homebrew

brew install --cask codex

These are the installation methods currently listed in the official Codex repository.

A note about Node.js

When I first tried the npm installation, the process froze on an older Node.js setup. Moving to Node.js 22 fixed it.

That does not mean every reader must install Node.js 22. The standalone installer does not require you to manage Node yourself.

But if you choose the npm route and the installation hangs or throws an operating-system error, check these first:

node --version
npm --version

Updating Node and npm is usually a better first move than repeatedly running the same failed command and hoping the computer changes its mind.

How to sign in

Move into the project you want Codex to examine:

cd path/to/your-project

Start Codex:

codex

The first launch should guide you through authentication. For most people, the easiest option is to sign in with a ChatGPT account in the browser.

Codex is currently available across ChatGPT plans, although usage limits vary. Check OpenAI’s current plan information.

You can also start the login flow directly:

codex --login

Using an API key instead

If you prefer API billing – or you work through an organisation that provides API credentials – you can authenticate with an OpenAI API key. Never paste the key into your source code or commit it to Git.

On macOS or Linux:

export OPENAI_API_KEY="your-api-key-here"

In PowerShell:

$env:OPENAI_API_KEY = "your-api-key-here"

Then start Codex from the project directory:

codex

API usage is billed separately from a normal ChatGPT subscription, so check that the correct API organisation and billing method are configured before testing. For most individual users, signing in with ChatGPT is the less fiddly route. Read OpenAI’s authentication guide.

Your first Codex session

Do not begin with:

Improve my entire application.

That is not a brief. It is a cry for help.

Give Codex something bounded and verifiable instead:

Explain how authentication works in this repository. Do not change any files.

Or:

Find the cause of the failing checkout test. Explain the problem before editing anything.

Once you trust its diagnosis, give it permission to implement the change:

Fix the failing checkout test. Keep the change narrowly scoped and run the relevant tests afterwards.

A good prompt usually includes the outcome you want, the part of the project in scope, anything it must not change and the evidence that will prove the work is complete.

Permissions and sandboxing

The older Codex CLI described its behaviour using three modes: Suggest, Auto Edit and Full Auto. Current versions use more flexible approval and sandbox settings, so those old labels should not be treated as the permanent interface.

The important distinction remains the same: how much can Codex do before it has to ask you?

  • It can be restricted to reading files.
  • It can be allowed to write within the current workspace.
  • It can ask before running commands that need additional access.
  • It can work with broader permissions when you explicitly allow them.

My rule is simple: begin cautiously in an unfamiliar repository. Let Codex inspect the project and explain its proposed approach before giving it room to edit.

Never approve a command merely because the tool sounds confident. Read it.

What I asked Codex to do

My first test was deliberately ordinary: inspect a project and design the database for a CRUD application.

Codex proposed the tables, relationships, constraints and indexes. I then asked it to produce the SQL and explain the decisions.

That was useful, but generating SQL is not the most revealing test. Plenty of AI tools can produce a plausible schema.

The more interesting moment came when I gave it an existing repository. Codex could trace how the project was organised, locate the relevant files and work with the conventions already in use. I did not have to paste fragments into a browser and explain where each one belonged.

That continuity is the real advantage.

Where Codex can go wrong

Codex is capable. It is not magically correct.

A change can compile and still be a poor product decision. A test can pass while missing the behaviour users care about. An agent can also misunderstand an ambiguous instruction with impressive efficiency.

  • Watch for changes that quietly expand beyond the original task.
  • Check that tests validate behaviour rather than implementation details.
  • Question new dependencies that were not necessary.
  • Do not accept security assumptions made without enough context.
  • Review commands that modify external systems or production data.
  • Ask for evidence instead of trusting confident claims.
Implement the fix, run the relevant tests and summarise exactly what changed. If anything could not be verified, say so clearly.

That final sentence is doing useful work.

Is Codex CLI private?

Codex operates on files in the local workspace you open, and its sandbox controls what it can access or change. But it is not an offline model.

Relevant prompts, code and command output may be sent to OpenAI so the model can perform the task. The applicable data controls depend on whether you authenticate through an individual ChatGPT account, a business workspace or the API.

If you work with sensitive code, check your organisation’s policy and OpenAI’s current data terms before connecting the repository. Do not treat “runs in your terminal” as meaning “nothing is transmitted.”

My verdict

Codex CLI removes one of the most annoying parts of using AI for development: constantly moving between the editor, terminal and browser while manually carrying context between them.

It can inspect the real project, make changes in the right files and run the commands needed to check its work.

The installation is now easier than it was during my first test, particularly with the standalone installer and ChatGPT sign-in.

The bigger learning curve is not operating the tool. It is learning to brief it properly.

Give it a vague request and you may receive a large, energetic interpretation. Give it a clear outcome, sensible boundaries and a definition of done, and it becomes much more valuable.

Would I use it on a production repository?

Yes – but with Git, sensible permissions and my eyes open.

That is also how I would work with a human developer I had only just met.

If you enjoy practical tests of AI tools – without pretending every new launch has changed civilisation overnight – you can find more of my reviews on YouTube.