How do I install OpenAI's Codex CLI on a Mac or Windows PC?
Codex is OpenAI's coding agent, and it runs on your own computer. Here is how to install it on a Mac or a Windows PC, sign in, and make sure it works, with every command spelled out.
By Lucas Mack, founder and CEO of SMGPPublished 8 minute read
The short answer
Codex CLI installs with one command in a terminal. On a Mac, open Terminal and run the install script from chatgpt.com, or use Homebrew or npm if you already have them. On Windows, open PowerShell and run the install script from the same place, or use npm, or run the Mac command inside WSL. Then type codex, choose Sign in with ChatGPT, and sign in with a Plus, Pro, Business, Edu or Enterprise plan. Confirm the install with codex --version.
Key takeaways
Codex CLI is a coding agent from OpenAI that runs locally on your computer, and the whole install is one command in a terminal.
Mac users run the install script, Homebrew or npm. Windows users run the PowerShell script, npm, or the Mac command inside WSL.
You sign in with your ChatGPT account. Plus, Pro, Business, Edu and Enterprise plans are the recommended route, and an API key works with extra setup.
Start Codex inside the folder you want it to work in, and give that folder an AGENTS.md file so Codex knows your rules.
Questionsbefore you start.
Short answers to what people ask before they open a terminal. Anything else, ask below: the answer comes from this guide and the official docs.
Do I need Homebrew, Node.js or Git before I install Codex CLI?
Not for the install itself. The install script puts Codex on the machine and needs nothing else. Install them anyway, before Codex: Node.js brings npm and npx, which is how most MCP servers start, Git is how you make the checkpoints OpenAI tells you to create before and after a task, so you can undo what Codex changed, and on a Mac Homebrew is how you add tools like those. The steps are in what to install first, and they take a few minutes.
What are Homebrew, winget, npm and npx, in one line each?
Homebrew is a free package manager for the Mac: one command installs or updates a tool, so you never hunt for downloads. winget is the same idea, and it is already part of Windows. npm is the package manager that comes with Node.js. npx runs a package without a permanent install, which is why the setup line for most MCP servers starts with npx.
Is a terminal already on my computer, and which one do I open?
Yes, on both systems. A Mac ships with Terminal, and the shell inside it, Zsh or Bash, is already there, so there is nothing to install. Windows ships with PowerShell, and the Codex installer runs there, not in Command Prompt. The prompt tells you where you are: it starts with PS in PowerShell. Bash on Windows is an extra download, Git for Windows, and the install-first steps in this guide include it.
How long does the whole setup take?
Plan on about fifteen minutes the first time. Homebrew and Node.js on a Mac, or Git for Windows and Node.js on a PC, take most of it, the Codex install script takes a minute or two, and the sign-in is a browser click. The commands show little while they run, so a quiet window is normal.
Your earlier questions on this guide, kept in this browser.
Answers come from this guide and the official documentation, checked live, and follow-up questions build on the ones before. For anything bigger, contact our team.
How to install Codex CLI on a Mac or Windows PC, in about a minuteA video with no sound. Every word is on screen.Read the video transcript
SMGP explains. How to install Codex CLI on a Mac or Windows PC. In about a minute.
Codex is OpenAI's coding agent on your own computer.
You type the task in a terminal. Codex reads, edits and runs.
What you need first.
A ChatGPT account: Plus, Pro, Business, Edu or Enterprise.
A terminal. Terminal on a Mac, PowerShell on Windows.
A folder to work in, even an empty one.
Mac: run the install script from chatgpt.com in Terminal. Windows: run the PowerShell installer from chatgpt.com.
Mac: or Homebrew. Or npm if Node.js is installed. Windows: or npm. Or the Mac command inside WSL.
Then sign in and check.
Open a new terminal. Run codex --version.
Move into your project folder and type codex.
Choose Sign in with ChatGPT and approve it in the browser.
Your first ten minutes.
Give it one small, real task in that folder.
Add an AGENTS.md file with your rules.
Type /mcp to see which tools are connected.
AI engineering begins with an agent on your own machine.
Installing one is the first hour. The weeks after are where the value is.
SMGP. Embedded GTM engineering and embedded AI engineering. smgp.co
What is Codex CLI, in plain English?
Codex CLI is a coding agent from OpenAI that runs locally on your computer. You open a terminal, type what you want done in plain English, and Codex reads the files in the folder, edits them and runs commands until the task is finished. It pauses to ask before it does anything you have not already allowed.
CLI stands for command line interface, which means Codex lives in a terminal window rather than a normal app with buttons. That sounds technical, and the first ten minutes are. After that, most of what you type is ordinary English. If you have never opened a terminal, this guide starts there.
Codex also runs as an extension inside code editors, in the cloud at chatgpt.com/codex, and inside the ChatGPT desktop app. This post covers the terminal version, because it works on every machine, and because the editor extension and the desktop app share the MCP setup you create here.
What do you need before you start?
Three things, and you probably have all of them.
A ChatGPT account. OpenAI recommends signing in with a Plus, Pro, Business, Edu or Enterprise plan. You can also use an API key, but that needs additional setup, so start with the account.
A terminal. On a Mac, press Command and Space, type Terminal, and press Return. On Windows, open the Start menu, type PowerShell, and open it. Both come with the operating system.
A folder to work in. Codex works on the folder you start it from, so make a folder for the project before you begin, even if it is empty.
You do not need Node.js for the main install method. You only need it if you choose the npm route below.
What should you install first, before Codex CLI?
The install script needs none of this. Codex does, usually within the first week. OpenAI’s own documentation tells you to create Git checkpoints before and after a task so you can revert what Codex changed, and its review feature works on your uncommitted changes or a commit, so Git is the first thing it reaches for. Most MCP servers, the connectors that let Codex operate your other software, start with npx, which comes with Node.js, and the example server in OpenAI’s MCP documentation is one of them. On a Mac, Homebrew is how you add tools like these. On Windows, winget does the same job and is already part of the system. Put them in place now and the first week has no detours.
On a Mac:
Install Homebrew, the package manager for the Mac. Paste this in Terminal and press Return. It explains what it is about to do, pauses, asks for your Mac password, and installs Apple’s Command Line Tools if the Mac does not have them yet. Git comes with those tools.
Read the “Next steps” the installer prints at the end and run the commands it shows. They add Homebrew to your PATH so brew works in every new window, and Homebrew’s own docs say it will not work if you skip them.
Open a new Terminal window and install Node.js. It brings npm and npx with it.
brew install node
Check all three. Each command prints a version number.
Install Git for Windows. It brings Git and Git Bash, a Bash window for Windows. Download the installer from git-scm.com and accept the defaults, or run this in PowerShell through winget, which does the same thing in one line.
winget install --id Git.Git -e --source winget
Install Node.js, the LTS release, which is the one npm’s own docs tell you to pick. It brings npm and npx with it. The installer from nodejs.org does the same job if you would rather click.
winget install OpenJS.NodeJS.LTS
Close PowerShell and open a new window, so it picks up both installs. Then check all three. Each command prints a version number.
git --versionnode --versionnpx --version
Not every machine matches these steps. Homebrew supports Apple silicon Macs on macOS Sequoia or newer, and its documentation calls an Intel Mac or an older macOS an unsupported setup that may still work. On that Mac, install Node.js with the installer from nodejs.org, get Git by running xcode-select --install, and carry on. On a Windows PC where winget is missing, the installers from git-scm.com and nodejs.org do the same job with a few clicks. Inside WSL you are on Linux, so Git and Node.js come from the Linux distribution’s own package manager, not from these steps. Codex itself installs the same way on every machine this guide covers.
How do you install Codex CLI on a Mac?
Open Terminal and run the official install script from OpenAI:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
This downloads Codex and puts it on your path, which means your terminal will recognize the word codex from now on. The command shows little while it runs, so wait for the prompt to come back.
If you already use Homebrew, the package manager many Mac users keep their tools in, you can install Codex that way instead:
brew install --cask codex
If you already have Node.js installed, npm works too:
npm install -g @openai/codex
Pick one method and stay with it, because each one updates differently. The script is the simplest if you have no preference, and it needs nothing else on the machine.
How do you install Codex CLI on Windows?
Open PowerShell, not Command Prompt, and run the official installer:
This downloads the installer from OpenAI and runs it. The ExecutionPolicy part lets this one script run; it does not change your computer’s settings for anything else. You can tell you are in PowerShell because the prompt starts with PS.
There are two alternatives. If Node.js is installed on your PC, the npm command is the same as on a Mac:
npm install -g @openai/codex
If you use WSL, the Windows Subsystem for Linux, open your Linux terminal and run the Mac and Linux command instead:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Inside WSL, Codex sees the files inside the Linux environment, so keep your project folders there if you go that route.
How do you sign in and check it works?
Close the terminal window and open a new one, so the computer picks up the new command. Then confirm the install:
codex --version
A working install prints a version number. If the terminal says the command is not found, the install folder is not on your path yet. A fresh terminal window fixes most cases, and OpenAI’s Codex CLI documentation covers the rest.
Now move into your project folder and start Codex:
cd your-projectcodex
The first run asks how you want to sign in. Choose Sign in with ChatGPT, approve it in the browser window that opens, and come back to the terminal. Codex is now signed in and working in that folder.
What should you run first?
Give it a small, real task in the folder you opened. Something like “read every file in this folder and tell me what it does,” or “write a short README that explains this project.” Watch what it asks permission for, and answer yes or no. That ten minutes teaches you more about how the tool behaves than any article can.
Then add a file called AGENTS.md to the folder. It is a plain text file where you write the rules Codex should follow in that project: what the project is, what it must never touch, how you like things named. Codex reads it at the start of every session, which saves you repeating yourself.
Inside a session, type /mcp to see which MCP servers are connected. MCP is how Codex reaches tools outside the folder, such as your automation platform, and the first connection we recommend is n8n, through its MCP server, because that is where the work a business runs on lives. Codex keeps its settings in a file called ~/.codex/config.toml, which is where each server is added, and the npx you installed earlier is what starts most of them.
How do you keep Codex updated?
OpenAI ships changes to Codex often, so update when something looks different from this guide. The update command depends on how you installed.
If you used the install script, on a Mac or in WSL, run the same command again:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
If you used npm, install the latest version of the package:
npm install -g @openai/codex@latest
If you used Homebrew, upgrade the cask:
brew upgrade --cask codex
Run codex --version afterward to confirm the new version is the one your terminal uses.
What goes wrong most often?
The terminal says codex is not found. You are in a terminal window that opened before the install finished. Close it, open a new one, and try again.
The Windows command fails with an error about irm or &&. You ran it in the wrong shell. The PowerShell installer only runs in PowerShell, where the prompt starts with PS.
Codex cannot see your files. It only sees the folder you started it in. Quit, move into the right folder with cd, and start it again.
You tried an API key instead of a ChatGPT account and it did not work. An API key needs additional setup that the ChatGPT sign-in does not. Sign in with your plan first, and follow OpenAI’s documentation if you later need the key.
Two installs on one machine. Installing with the script and with npm leaves two copies that update separately. Remove one, or stay with the method you used first.
AI engineering, the way we practice it at SMGP, begins with a coding agent on the founder’s own machine. Installing one is the first hour of the work. The weeks after that are where the value is: pointing the agent at the invoicing, the reporting, the company memory and the internal tools a business runs on, which is what embedded AI engineering means.
We use both Codex and Claude Code. Codex built parts of the smgp.co website you are reading. Claude Code built our finance software, our company memory and most of our automations, which you can read about on how SMGP runs on AI. If you are choosing your first agent, we start with Claude Code, and our guide to installing Claude Code on a Mac is the matching walkthrough. The Windows version is in the related guides below.
Written by Lucas Mack
Lucas is the founder and CEO of SMGP. He has done every job in the company, runs the strategy and the sales, and built every system SMGP runs on, from the outbound engine to the finance software. He writes about what he builds and what he has learned building it.
No. You need to be comfortable opening a terminal and pasting a few commands, which this guide walks through. After the install, most of what you type is plain English: what you want done, in which folder, and what Codex should leave alone.
Which ChatGPT plan do I need for Codex?
OpenAI recommends signing in with a ChatGPT Plus, Pro, Business, Edu or Enterprise plan. An API key also works, but it needs additional setup, so start with the plan you already have. Usage limits change often, so check OpenAI's Codex documentation for the current ones.
Should I install Codex with the script, Homebrew or npm?
Use the install script unless you have a reason not to. It needs nothing else on the machine. Choose Homebrew if you already manage your Mac software with it, and choose npm if Node.js is already installed and you keep your command-line tools there. Each method updates differently, so pick one and stay with it.
Can I run Codex CLI on Windows without WSL?
Yes. Open PowerShell and run the Windows installer from chatgpt.com, and Codex runs on Windows itself. WSL, the Windows Subsystem for Linux, is an option if your projects already live in a Linux environment, in which case you run the Mac and Linux install command inside WSL instead.
How do I update Codex CLI?
If you used the install script, run the same command again and it installs the newest version. If you used npm, install the latest package again. If you used Homebrew, upgrade the cask. The exact commands are in the update section of this guide.
Thirty minutes on your business: where a GTM engineer or an AI engineer would make the biggest difference, and what to build first. You leave with a plan either way.
