Install the OpenAI Codex CLI on Mac, Windows or Linux

VibeiDE.dev — Tue, 06 Oct 2026 00:10:47 +0000

The Codex CLI is OpenAI's coding agent for the terminal. It reads your repository, edits files, runs commands and explains what it did, all from one prompt. Installing it takes one command; using it well takes a few choices most guides skip: how to sign in, how much the agent may do without asking, how to keep it updated and how to run it from scripts.

This guide covers all of it, from the install command for macOS, Linux or Windows to checking and updating your version, your first session, the sandbox and approval settings, configuration, and codex exec for automation. Commands are based on the official Codex repository and command reference as of October 2026.

Install the Codex CLI

Pick one method. They all install the same codex command.

npm (any system with Node.js):

npm install -g @openai/codex

Homebrew on macOS:

brew install --cask codex

Install script on macOS or Linux:

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

Windows PowerShell:

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

You can also download a binary for macOS (arm64 or x86_64) or Linux (x86_64 or arm64) from the latest GitHub release, extract it and rename the executable to codex.

Check that it worked

Open a new terminal and run:

codex --version

If it prints a version number, the install worked. If your shell says codex: command not found, the new terminal did not pick up the updated PATH yet; close it and open another. With npm, check that your global npm bin directory is on PATH (npm prefix -g shows where global packages go).

Codex CLI on Windows

On Windows, the Codex CLI runs natively in PowerShell with its own Windows sandbox, so you do not need WSL or a virtual machine. According to the Windows sandbox documentation, the sandbox has two modes you can set in config.toml: elevated (preferred, uses a dedicated lower-privilege sandbox user and firewall rules) and unelevated (a fallback that uses a restricted token from your own user):

[windows]
sandbox = "elevated"

Use WSL2 instead when your toolchain already lives in Linux or you need Linux-native tools. In that case, install Codex inside the WSL distribution with the npm or install script method, and start it from your Linux shell.

Update the Codex CLI

Codex changes quickly, so update regularly. The CLI has its own update command:

codex update

It updates Codex to the latest version when the installed release supports it. If you prefer to update through the package manager you installed with, use the matching command:

Installed with	Update command
Codex itself	`codex update`
npm	`npm install -g @openai/codex@latest`
Homebrew	`brew upgrade --cask codex`
GitHub release binary	Download the newer release and replace the `codex` file

Run codex --version afterwards to confirm the new version. Stick to one install method per machine: two copies on PATH (for example one from npm and one from Homebrew) is the usual reason an update seems to do nothing.

Sign in

Run codex in any folder. The first run asks how you want to sign in:

Sign in with ChatGPT uses your ChatGPT plan. The README lists Plus, Pro, Business, Edu and Enterprise plans. Usage then counts against that plan's Codex allowance.
API key bills usage to an OpenAI API account and needs a little more setup. From a script, codex login --with-api-key reads the key from stdin, for example printenv OPENAI_API_KEY | codex login --with-api-key.

Which plans include Codex and how much usage they allow changes over time, so check the official Codex pricing page for current details. You can switch accounts later with codex logout and codex login.

Your first session

Start Codex from the root of a project:

cd ~/code/my-app
codex

Then run /init. It generates an AGENTS.md scaffold in the current directory, the file Codex reads at the start of every run to learn your build commands, layout and conventions. Edit it down to what matters; our guide to AGENTS.md for Codex explains how Codex discovers and combines these files.

Now give Codex a small, concrete task, such as "add a test for the empty cart case in src/cart.ts". Watch what it reads and proposes before you hand it anything larger.

The slash commands you will use most:

Command	What it does
`/init`	Generate an AGENTS.md scaffold
`/model`	Choose the model and reasoning effort
`/plan`	Switch to plan mode before editing
`/permissions`	Set what Codex can do without asking
`/diff`	Show the git diff, including untracked files
`/review`	Ask Codex to review your working tree
`/status`	Show session configuration and token usage
`/compact`	Summarize the conversation to free context
`/resume`	Continue a saved conversation
`/new`	Start a fresh conversation in the same session

Moving from Claude Code? /import brings over your Claude Code setup, project files and recent chats.

Sandbox and approvals: how much Codex may do

Two separate settings decide how freely Codex acts. Getting them right is the difference between a helpful agent and one that either asks about everything or touches things it should not.

The sandbox limits what commands can technically do:

read-only: Codex can read files but not write them. Good for exploring an unfamiliar codebase or asking questions.
workspace-write: Codex can edit files inside the project. This is the default for interactive sessions and the right choice for most work.
danger-full-access: no sandbox at all. Use it only in a disposable environment, such as a container you can throw away.

The approval policy decides when Codex stops to ask you: on-request pauses for approval when Codex needs to go beyond the sandbox, and never never pauses.

Set both per run with flags:

codex --sandbox read-only
codex --sandbox workspace-write --ask-for-approval on-request

The older --full-auto flag is deprecated; use --sandbox workspace-write instead. There is also --dangerously-bypass-approvals-and-sandbox (alias --yolo), which removes both protections. Treat it like running an unknown script with your own permissions. Our guide to the Codex sandbox goes deeper into network access, extra writable folders and when full access is reasonable.

Useful flags

A few flags make everyday runs faster:

-m or --model picks a model for this run instead of the configured one.
-C or --cd sets the working directory, handy when you launch Codex from elsewhere.
-i or --image attaches screenshots or design files to your prompt.
--search lets Codex use live web search for the task.

Other subcommands worth knowing: codex resume --last reopens your most recent session (our guide to codex resume covers the picker, forks and resuming scripted runs), codex mcp manages Model Context Protocol servers, and codex completion generates shell completions.

Configure Codex once

Instead of repeating flags, put your defaults in ~/.codex/config.toml:

sandbox_mode = "workspace-write"
approval_policy = "on-request"

Any single run can still override a setting with -c key=value, and /debug-config shows which configuration layers are active when something behaves unexpectedly. The same folder holds your global AGENTS.md, for personal preferences that apply to every repository.

Automate with codex exec

codex exec runs a task without the interactive interface. It is how you use Codex from shell scripts, git hooks and CI jobs.

codex exec "summarize the changes on this branch"
codex exec --json "list the failing tests and their causes" > events.jsonl
codex exec --sandbox workspace-write "fix the failing test in tests/api.test.ts"

codex exec runs in a read-only sandbox by default. Add --sandbox workspace-write when the task must edit files.
--json streams machine-readable events, so a script can react to what Codex did.
-o or --output-last-message writes only the final message to a file, which is ideal for summaries and reports.
--skip-git-repo-check lets Codex run outside a git repository.

Our full guide to codex exec covers stdin input, --output-schema, codex exec resume and running Codex in CI.

Common questions

How do I check which Codex version I have?

Run codex --version. Compare it with the latest release on the Codex GitHub releases page if you are unsure whether an update worked.

How do I update the Codex CLI?

Run codex update, or update with the package manager you installed with: npm install -g @openai/codex@latest or brew upgrade --cask codex.

Does the Codex CLI work on Windows?

Yes. Install it with the PowerShell command above and it runs natively with a Windows sandbox. Use WSL2 if your project and tools already live in Linux.

How do I start Codex after installing it?

Change into your project folder and run codex. The first run asks you to sign in with ChatGPT or an API key.

Where Codex fits next to other agents

Codex is one of several strong terminal agents. If you are deciding between them, our comparisons of Codex vs Claude Code, OpenCode vs Codex and OpenCode vs Claude Code cover model access, sandboxing, instruction files and which tasks suit each. When you hit your plan's usage limit, our page on Codex rate limits explains how to plan work around it.

Where VibeiDE fits

VibeiDE is a desktop app that coordinates the Codex, Claude Code and OpenCode CLIs you already installed, and you sign in to Codex with your own account. Codex runs in an embedded terminal that shows the original CLI interface, so everything in this guide works the same inside it. Each project gets its own task queue, the usage display shows provider-reported usage and reset countdowns where Codex reports them, and when Codex reaches a usage limit the terminal explains that you can continue in the same terminal after the reset. See the Codex page or set it up in about three minutes with a 14-day trial and no card.

Takeaways

Install with npm, Homebrew, the install script or PowerShell; all give you the same codex command.
Check the install with codex --version and update with codex update or your package manager.
On Windows, Codex runs natively with its own sandbox; use WSL2 only when your tools live in Linux.
Sign in with a ChatGPT plan or an API key, and check the official pricing page for current plans.
Run /init first so Codex has an AGENTS.md to work from.
Keep the sandbox at workspace-write for daily work and read-only for exploring; avoid --yolo outside disposable environments.
Use codex exec for scripts and CI; it starts read-only unless you raise the sandbox.

Originally published at vibeide.dev.

DEV Community: VibeiDE.dev