Quick takeaways
- OpenAI Codex CLI turns your terminal into an agentic coding assistant that can edit files and run commands.
- It works best for developers who prefer keyboard-driven workflows and scripted automation.
- Use approval modes and sandboxing to keep file changes and shell commands under control.
OpenAI Codex CLI explained
AI Foundations explains Codex CLI setup, commands, and how it compares to other terminal coding agents.
What Codex CLI is
Codex CLI is a command-line tool from OpenAI that brings agentic coding to the terminal. It can explore a repository, propose edits, run tests or build commands, and report back. Because it is open source, you can inspect how it works, run it locally, and integrate it into scripts or CI pipelines.
Unlike an IDE plugin, Codex CLI has no visual editor. You describe what you want, review the proposed changes, and apply them. That makes it lightweight and a good fit for terminal-first developers, remote servers, and automation.
Install and setup
You can install Codex CLI with a package manager. Make sure you have Node.js and an OpenAI API key, or sign in through your ChatGPT account.
npm:
npm install -g @openai/codex
Homebrew:
brew install codex
After installation, run codex to start an interactive session. On first use it
will ask you to authenticate. You can also set your API key as an environment variable if you
prefer not to use the interactive login.
Core terminal commands
The simplest pattern is to pass a prompt directly to Codex CLI:
codex "refactor the auth middleware to use async/await"
Useful flags and patterns include:
codex— start an interactive session in the current directory.codex --approval-mode suggest "task"— show a plan and wait for approval before editing.codex --approval-mode auto-edit "task"— apply file edits automatically, but ask before running commands.codex --quiet "task"— run non-interactively, useful for scripts or CI.codex --model gpt-5-codex "task"— choose a specific model for the run.
Approval modes are the most important safety setting. Start with suggest until
you trust the workflow, then move to tighter automation if it fits your team.
Agentic workflow
Codex CLI follows a predictable loop:
- Inspect: reads relevant files and summarizes what it finds.
- Plan: proposes a set of changes and asks for approval.
- Edit: writes file changes in small, reviewable diffs.
- Verify: runs tests, type checks, or build commands you specify.
- Report: returns a summary of changes, results, and any risks.
You can guide the agent with project-level instructions. Create a
.codex/instructions.md or codex.md file in your repo to document
conventions, test commands, and files to avoid. For more on structuring agent tasks, see our
AI coding agents guide.
OpenAI ecosystem integration
Codex CLI uses your OpenAI account for model access and billing. That means it works with the same API key or subscription you may already use for ChatGPT, the OpenAI API, or other OpenAI developer tools. The default models are optimized for coding, and you can select different models if your account supports them.
Because it is scriptable, Codex CLI also slots into automation. You can call it from Git
hooks, CI jobs, or Makefile targets in --quiet mode. Pair it with the OpenAI API
for custom workflows, or use it alongside the web-based Codex app when you need a visual
interface.
Pricing
The Codex CLI tool itself is free and open source, but model usage is not. You pay through your OpenAI account based on the model and tokens consumed. If your ChatGPT subscription includes Codex access, some usage may be covered. For exact API rates, check AI model API pricing compared.
| Cost category | How it works |
|---|---|
| CLI software | Free, open-source install |
| Interactive usage | Billed to your OpenAI API account or covered by a subscription |
| CI/automation | API usage only; monitor token volume carefully |
When to use Codex CLI
Limitations
- OpenAI dependency: it requires an OpenAI account and usage billing.
- No built-in editor: all edits happen through diffs; you need a separate editor for visual review.
- Platform support: macOS and Linux are first-class; Windows support may require WSL.
- Sandboxing: automatic command execution should be limited; use sandboxed environments where possible.
- Context limits: very large repos may need you to narrow the scope manually.
Without AI vs. with AI
| Task | Without AI | With AI |
|---|---|---|
| Scaffolding projects | Developers copy templates, rename files, and configure boilerplate manually. | Codex CLI generates project structure and files from a natural-language prompt. |
| Running scripts | Developers write one-off scripts, test them, and then discard or maintain them. | Codex CLI creates, runs, and refactors scripts conversationally in the terminal. |
| Code review prep | Authors manually summarize changes and check for obvious issues before opening a PR. | Codex CLI can summarize diffs, run checks, and suggest fixes before review. |
| CI automation | Teams write custom CI steps for linting, tests, and small checks. | Codex CLI can run locally or in CI with --quiet mode for repeatable coding tasks. |
| Learning APIs | Developers read docs and copy examples into their editor. | Codex CLI generates example calls and integrates them directly into the codebase. |
FAQ
Do I need ChatGPT Plus to use Codex CLI?
No. You can authenticate with an OpenAI API key and pay for usage directly. Some subscriptions may include Codex access.
Is Codex CLI safe for production code?
Use it the way you would use any coding agent: review every diff, run tests, and avoid auto-executing commands on sensitive systems.
Can I use Codex CLI in CI?
Yes, with the --quiet flag. Keep tasks narrow and log outputs so failures are easy to trace.
Does it work on Windows?
Windows support is improving, but the smoothest experience is usually through WSL or a Unix-like environment.
How is Codex CLI different from GitHub Copilot?
Copilot focuses on inline completions inside an editor. Codex CLI is a terminal agent that can plan, edit files, and run commands.
What models does Codex CLI use?
It uses OpenAI coding-optimized models, with options to select specific models if your account supports them.
Can Codex CLI edit files automatically?
It can in auto-edit approval mode, but start with suggest mode until you trust the workflow.
Is Codex CLI open source?
Yes. You can inspect the source, run it locally, and contribute to development.
How do I configure project-specific instructions?
Create a .codex/instructions.md or codex.md file to document conventions, test commands, and files to avoid.
Can I use Codex CLI in a team?
Yes, but align on approval modes, API billing, and review practices before sharing workflows.