OpenAI Codex CLI Guide: Install, Auth & Workflows (2026)
The OpenAI Codex CLI is OpenAI's coding agent in your terminal: an open-source, Rust-based command-line tool that runs locally against your own checkout, so you describe a task in plain language and it reads, edits, and runs code in your project. The install is a single command and the first session is quick to reach, but the parts that pay off most, signing in the right way, choosing an approval mode that matches your trust level, switching models for the task, and handing long jobs to Codex Cloud, are not obvious from the welcome prompt. This guide walks the path: installing the tool on macOS, Linux, or Windows, signing in with a ChatGPT account or an API key, using the interactive TUI, picking a model and reasoning effort, scripting with exec, and delegating work to the cloud.
'%20stroke-width='4'/%3E%3C/svg%3E)
Before anything else: the Codex CLI is open source under Apache 2.0, but running it draws on a paid account. Codex is included in ChatGPT Plus, Pro, Business, Edu, and Enterprise, or you can authenticate with an OpenAI API key billed separately. We cover both sign-in paths below.
What the OpenAI Codex CLI Is
Getting started is quick. You run one install command, launch the tool, sign in once, and you are working in your project. The thing to understand up front is that the command line is one of three Codex surfaces. There is also an IDE extension for VS Code and its forks Cursor and Windsurf, plus JetBrains, and a web surface at chatgpt.com/codex. They share the same agent and connect to Codex Cloud, so the workflow you learn here carries over.
One thing to settle early: if you are pointing Codex at private or proprietary code, decide which sign-in path and approval mode fit your organization's policy before the first real session. Both choices affect how, and where, your code is processed.
Install the CLI
On macOS and Linux, the fastest path is the official install script. It downloads the CLI and puts it on your path in a single command.
For an unattended install, such as inside a provisioning script or a container build, set the CODEX_NON_INTERACTIVE=1 environment variable first so the script does not stop to prompt you.
On Windows you have two supported routes. The CLI runs natively in PowerShell using the Windows sandbox, or you can run it inside WSL2 for a Linux-style environment. Pick whichever matches how the rest of your toolchain is set up.
Other install methods
The script is not the only option. The CLI is also distributed through common package managers and as standalone binaries, which is useful when you want version pinning or cannot pipe a script to a shell.
| Method | When to use it |
|---|---|
| Install script | Fastest path on macOS and Linux; one command |
| npm | You already manage Node tooling and want it alongside your other CLIs |
| Homebrew | You manage macOS or Linux packages through brew |
| GitHub Releases | You want a prebuilt binary, a pinned version, or an air-gapped install |
| IDE extension | You prefer the editor surface: VS Code Marketplace, or JetBrains |
Piping a script to a shell: the curl ... | sh pattern runs whatever the URL returns. It is the vendor's documented method, but if your environment forbids it, use a package manager or download a binary from GitHub Releases instead.
Sign In
The first time you launch the OpenAI Codex CLI it prompts you to sign in, and there are two ways to authenticate. Each draws on a different account and bills differently, so the choice matters before you start a real session.
- ChatGPT account – sign in with the account behind your ChatGPT subscription. Codex usage then draws on your plan's usage credits. This is the simplest path if Codex is already included in your plan.
- OpenAI API key – supply an API key instead, and usage is billed against your API account rather than a ChatGPT plan. This suits automation and team setups that already manage API keys.
Codex is included in ChatGPT Plus, Pro, Business, Edu, and Enterprise. In the JetBrains extension, a JetBrains AI subscription is also a supported way in. OpenAI does not publish a single flat figure for CLI usage or hard numeric rate limits in these sources, so check current plan inclusions and limits on OpenAI's own pricing and rate-limit pages rather than relying on a number you read elsewhere.
Which to choose: if you already pay for ChatGPT and want to try Codex, sign in with your ChatGPT account. If you are wiring Codex into scripts or CI, an API key keeps usage on a billing surface built for automation.
Use the Interactive TUI
Run codex in your project folder and the OpenAI Codex CLI opens an interactive terminal UI. This is where most of your day-to-day work happens. You type a task in plain language, the agent reads the relevant parts of your codebase, proposes edits and commands, and you review what it wants to do before it does it.
codex
The loop is deliberately a review loop. The agent shows its plan and the changes it intends to make, and you accept, refine, or redirect. For a first session, give it a small, well-scoped task you can read in a few minutes, such as adding a test or fixing a contained bug, then read what it changed before accepting. Once you trust how it behaves, you can hand it larger work.
Beyond plain code edits, the CLI agent can use a local code review capability to inspect changes, run a web search when a task needs current information, connect to third-party tools over MCP, and accept image inputs such as a screenshot of a UI bug or a diagram, alongside generating images. These turn the terminal into more than a code generator: it can gather context and verify its own work.
Pick a Model and Approval Mode
Two settings shape how Codex behaves on a task: which model runs it, and how much the agent can do without asking. The latest model referenced is GPT-5.5, with GPT-5.4 also available. You switch between them with the /model command inside the TUI, and you can set the reasoning effort to low, medium, or high depending on how much deliberation a task deserves.
Approval modes
Approval modes are the safety dial. They control how far the agent can go before it pauses to ask you, and choosing the right one is the single biggest factor in whether a session feels safe or reckless.
| Mode | What it allows |
|---|---|
| Chat | Read-only, conversational. The agent answers and suggests but does not change files |
| Agent | The agent edits files and runs commands in the workspace, asking for approval as needed |
| Agent (Full Access) | Most prompts removed for trusted, sandboxed work where you want it to run end to end |
On model names: the available models change as OpenAI ships new versions. Confirm what is currently offered in the /model picker and OpenAI's documentation rather than relying on any fixed list.
Script with exec and Subagents
The TUI is for interactive work, but the OpenAI Codex CLI also runs without a human at the keyboard. The non-interactive exec mode lets you invoke the agent from a script, a Makefile target, or a continuous-integration pipeline, passing the task as an argument and capturing the result programmatically.
This is how the same agent capability moves from your editor into automation. You can run Codex as a step that drafts changes, generates tests, or triages a failing build, then gate its output behind your normal review and CI checks.
Subagents for parallel work
For larger tasks, Codex supports subagents: it can break work into parts and run them in parallel rather than marching through one long sequence. The practical benefit is that independent pieces of a task, such as touching several modules that do not depend on each other, can progress at the same time. As with everything here, start small and let the scope grow once you trust the output.
Treat exec output as a draft: non-interactive runs skip the live review loop, so the discipline shifts to your pipeline. Run generated changes through tests and human review before they merge, exactly as you would a pull request from a teammate.
Delegate to Codex Cloud
Some jobs are too long to sit and watch. From the CLI you can launch a Codex Cloud task, which runs the work remotely on OpenAI's hosted surface at chatgpt.com/codex while you keep working in your terminal. You are not blocked: you monitor the task's progress, and when it finishes you preview the diffs and apply them back to your local checkout.
The mental model is a division of labor. Quick, interactive changes stay in the local TUI where you review each step. Long or batch jobs go to the cloud, where they run unattended and come back as reviewable diffs. Because both surfaces use the same Codex agent, you are not learning two tools, just choosing where a given task should run.
This is also where the three surfaces connect. The IDE extension and the web surface can hand work to the same cloud, so a task you start in your editor can be picked up, reviewed, or applied from wherever you are working.
Troubleshooting
These are the questions newcomers run into most often, with the practical answer for each.