Installing Codex CLI: a basic guide

Goal

By the end you'll have Codex CLI installed, authenticated (with your ChatGPT account or an API key), and a first session running against a real project, with approval and model settings tuned to your taste.

Codex CLI is OpenAI's terminal coding agent. It reads your codebase, edits files, and runs commands from natural-language instructions, with a sandbox and an approval model that decide how much it can do without asking. It runs interactively or non-interactively (codex exec) and supports MCP servers.

Prerequisites

macOS, Linux, or Windows.
A terminal with permission to install binaries onto your PATH.
One of: a ChatGPT plan that includes Codex (Plus, Pro, Business, Edu, or Enterprise), or an OpenAI API key with credit.
A local project to work on.
A recent Node.js LTS (20+) only if you install via npm; the standalone installer and Homebrew don't need it.

This guide covers Codex CLI as of September 2026.

Steps

1. Install the binary

Pick the method for your system.

macOS / Linux (standalone installer):

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

Windows (PowerShell):

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

Homebrew:

brew install --cask codex

npm:

npm install -g @openai/codex

To update later, re-run the installer command, or brew upgrade --cask codex / npm install -g @openai/codex@latest.

2. Verify the install

codex --version

Expected check: it prints the installed version. If the shell says "command not found", open a new terminal so it picks up the updated PATH.

Navigate to a project and start Codex:

cd path/to/your/project
codex

On first launch it asks how to authenticate:

Sign in with ChatGPT (recommended) — a browser opens; usage counts against your ChatGPT plan.
API key — run codex login --api-key and paste a key, or export it before launching:

export OPENAI_API_KEY=your-api-key
codex

Over SSH, copy the URL printed in the terminal and open it on your local machine.

4. Set approvals and model

Inside the session:

/permissions   # Read Only, Auto, or Full Access
/model         # pick the model and reasoning effort
/status        # show the current session configuration

Read Only answers questions without touching anything. Auto edits files and runs commands inside the workspace, asking before anything outside it. Full Access removes the prompts — use it only in a sandbox or throwaway environment.

5. Run your first task

Describe the change in plain language:

Add input validation to the signup handler and a test for it

Codex plans, edits, runs the test, and reports back.

6. Run it non-interactively

For scripts and CI:

codex exec "generate a CHANGELOG entry from the last 5 commits"

Expected result

codex --version prints a version.
codex launches and /status shows you authenticated, with a model and approval mode set.
A first natural-language task produces real file changes.
codex exec "..." runs without an interactive prompt.

Troubleshooting

Common issues

codex: command not found after installing: the installer updated your PATH but the current shell didn't reload it. Open a new terminal.
npm install fails or errors on old Node: the npm package needs a current Node.js LTS (20+). Upgrade Node, or use the standalone installer / Homebrew instead, which bundle their own runtime.
401 / auth errors with an API key: confirm OPENAI_API_KEY is exported in the same shell, and that the key's project has credit. codex login --api-key re-stores it.
ChatGPT sign-in loops or won't open: copy the printed URL into a browser manually; useful over SSH.
Codex won't edit files: you're in Read Only mode. Switch with /permissions.
A conflicting OPENAI_API_KEY overrides your ChatGPT sign-in: if you meant to use your plan, unset the variable in your shell profile.

Next step

Configure Codex per machine in ~/.codex/config.toml (default model, reasoning effort, MCP servers, approval defaults), and add project context in an AGENTS.md file at the repo root.