The Codex CLI is OpenAI’s coding agent that lives inside your terminal: you describe a task in natural language, it reads your repository, proposes the changes and runs commands inside a sandbox you control. Unlike a plain autocomplete, it reasons about the whole task and chains the actions needed, but every sensitive action goes through an approval policy that you decide. In this guide you will see what the Codex CLI is, how to install it and authenticate, how its approval and sandbox modes work, how to work in a real repository and how it differs from other terminal agents. The same explanation is available in Spanish.

Key takeaways

  • The Codex CLI is an open-source coding agent (Apache 2.0 licence) that you run in the terminal; it has over 98,000 stars on GitHub and is written 96.7% in Rust.
  • It installs in seconds with npm (npm install -g @openai/codex, needs Node.js 22 or higher), with Homebrew or with a one-command standalone installer.
  • You authenticate two ways: by signing in with your ChatGPT account (Free, Go, Plus, Pro, Business, Edu or Enterprise, with included usage) or with an API key from the OpenAI platform, which bills by consumption.
  • It combines three sandbox modes (read-only, workspace-write and danger-full-access) with three approval policies (untrusted, on-request and never) to tune how much autonomy you grant.
  • The project moves fast: rewritten from TypeScript to Rust in June 2025 and with more than 1,100 releases shipped since it launched in April 2025.

What is the Codex CLI?

The Codex CLI is OpenAI’s command-line tool for coding with an agent, described in its GitHub repository[1] as "a lightweight coding agent that runs in your terminal". Instead of living inside an editor, it runs as a terminal program: you open a project folder, type codex, describe what you want and the agent takes care of reading the files, planning and applying the changes.

It is free software under the Apache 2.0 licence, so you can read and audit all of its code. It has had a huge reception: it holds more than 98,000 stars on GitHub. One detail that says a lot about its pace is that in June 2025, barely two months after its first open-source version, OpenAI rewrote it completely from TypeScript to Rust; today 96.7% of the code is Rust, which gives it a fast binary with no heavy dependencies. Since then the project has passed 1,100 published releases in just over a year, a pace of several releases a week.

At heart it is an AI agent specialised in writing and editing code, with the difference that its home is the terminal, not the editor. That makes it ideal for automation, for headless servers and for anyone who prefers to work at the keyboard.

Installation and authentication

Installing it takes less than a minute. The most common route is npm (you need Node.js 22 or higher):

npm install -g @openai/codex

# Alternative on macOS with Homebrew
brew install --cask codex

# Alternative with the standalone installer (macOS/Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

With the binary installed, go into your project folder and launch the agent:

cd my-project
codex

The first time it will ask you to authenticate, and here there are two paths. The first, sign in with ChatGPT: you choose "Sign in with ChatGPT" and use your existing subscription. Usage counts against your plan’s included limits (Free, Go, Plus, Pro, Business, Edu or Enterprise), with a rolling 5-hour window shared across the terminal, the web and the editor extension plus an additional weekly cap that stacks on top; if you run out of quota you can buy extra credits. With Plus ($20/mo) you have plenty for normal use; Pro (from $100/mo) multiplies that quota by 5x or 20x depending on the tier, meant for intensive agentic work.

The second path is an API key from the OpenAI platform, meant for automation and CI/CD flows: the bill goes by token consumption for whichever model you pick. By default the Codex CLI uses the GPT-5.6 family, with three tiers: sol (the most capable, for demanding tasks), terra (the balanced option, recommended as the default, around $2.50 per million input tokens and $15 for output) and luna (the cheapest, for high volume). The specialised GPT-5.3-Codex model is still available and runs a bit cheaper ($1.75 input and $14 output per million tokens). The persistent configuration lives in ~/.codex/config.toml, where you set the model, the default approval policy and any MCP servers you want to connect, for example:

model = "gpt-5.6-terra"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[mcp_servers.docs]
url = "http://localhost:3000"

Approval and sandbox modes

Here is what sets the Codex CLI apart: it separates what it can do (the sandbox) from when it must ask you for permission (the approval). As OpenAI’s documentation puts it, "the sandbox is the boundary that lets the agent act autonomously without giving it unrestricted access to your machine".

The sandbox has three levels:

  • read-only: it only reads files and answers; any edit, command or network access requires your approval.
  • workspace-write (the default): it reads, edits files and runs commands inside your project, but going outside that folder or reaching the network needs permission.
  • danger-full-access: no sandbox and no approvals, full system access; use it only in a throwaway container.

On Linux, that isolation relies on bwrap (bubblewrap) plus seccomp; on macOS, on Seatbelt (sandbox-exec). On top of that base act the three approval policies: untrusted (runs only read operations known to be safe), on-request (the agent decides when to ask you for permission, recommended for interactive sessions and the default alongside workspace-write) and never (never interrupts; blocked operations fail and are returned to the agent, ideal for automated runs with an external safety boundary). The old on-failure policy is now deprecated: current docs recommend replacing it with on-request for interactive sessions or never for automation. For example, read-only plus on-request is ideal for exploring an unfamiliar repository without risking anything; workspace-write plus never fits a CI pipeline where you already control the environment upfront.

Working in a real repository

The everyday flow is simple. Inside the repository, you launch codex and describe the task; the agent explores the code, proposes a plan and applies changes you can review. A good first step is to generate an AGENTS.md file with the /init command: there you describe your project’s conventions (how it builds, how it tests, what style to follow) and the agent reads it in every session.

For non-interactive tasks or scripts, there is the codex exec subcommand, which runs an instruction and finishes without opening the interface:

# Interactive session
codex "add email validation to the signup form and a test"

# Non-interactive mode (for CI or scripts)
codex exec "run the tests and fix the failure in the payments module"

In a typical session you will see something like this, with the agent proposing actions and waiting for your go-ahead according to the active approval policy:

You:   Add pagination to the product list.
Codex: [plan]  I will edit src/products/list.ts and update the query.
Codex: [edit]  Proposes diff of src/products/list.ts   ->  [Approve] [Reject]
Codex: [shell] Run: npm test                           ->  [Allow] [Cancel]

Because it is built for the terminal, it fits naturally with Git: you review the changes with git diff before committing, and if something does not convince you, you discard it with git restore <file> (or git reset --hard if it is several files) and ask again with a more precise instruction. That closeness to version control is the main day-to-day safety net.

Codex CLI versus other terminal agents

It is not the only agent that lives in the terminal, and the choice depends mainly on which models you want to tie yourself to. The Codex CLI shines if you already pay for ChatGPT and want OpenAI’s models with a robust built-in sandbox. Google’s Gemini CLI plays the card of a very generous free tier with the Gemini models. Goose, from Block, is provider-agnostic and bets heavily on the Model Context Protocol to add tools. And Aider is the veteran focused on Git, working with almost any model and chaining changes as commits.

The Codex CLI’s big difference is its integration with the OpenAI ecosystem and its layered security approach. If you work mostly with OpenAI models, it is the most polished option; if you want total model freedom or a broad free tier, another agent may fit better. They all share the same underlying idea: an agent that plans, edits and runs under your supervision.

Frequently asked questions

Is the Codex CLI free?

The tool is open source and free (Apache 2.0 licence): you do not pay for the binary. What costs money is model usage. If you sign in with ChatGPT, consumption is drawn from the limits included in your plan (including the Free plan, with a modest quota); if you use an API key, you pay per token at the OpenAI platform’s rates. For normal interactive use, the $20/mo Plus plan usually suffices.

Do I need a paid OpenAI account?

Paying is not mandatory to try it, because Codex is also included in the free ChatGPT plans with limited usage. That said, for serious work a Plus or Pro plan, or an API key with credit, is advisable. Unlike an agent such as Cline (a VS Code extension that acts as an autonomous coding agent inside the editor) or Aider, the Codex CLI is meant to be used with OpenAI’s models, so you cannot connect just any provider with the same ease.

Is it safe to let it run commands?

Yes, as long as you use the sandbox and approvals sensibly. By default it starts in workspace-write with the on-request policy, which limits writes to your project and asks permission to reach the network. Reserve danger-full-access for a throwaway container and review each diff before approving it. The project itself keeps improving its detection of dangerous commands in every release.

Conclusion

The Codex CLI brings AI-assisted coding to the terminal with two clear ideas: an agent that plans and executes, and a layered safety control that separates what it can do from when it must ask you for permission. It installs with one npm command, authenticates with your ChatGPT account or an API key, and its Rust binary makes it light and fast. The next step is to install it in a test repository, start in workspace-write with on-request approval and compare it with the Gemini CLI or with Aider to decide which fits your workflow best.

Sources: [1] Codex CLI on GitHub[1], [2] Official Codex CLI documentation[2], [3] Using Codex with your ChatGPT plan, OpenAI Help Center[3], [4] Analysis of the Codex CLI features, Augment Code[4].

Visitas: 0

Sources

  1. GitHub repository
  2. Official Codex CLI documentation
  3. Using Codex with your ChatGPT plan, OpenAI Help Center
  4. Analysis of the Codex CLI features, Augment Code

Route: AI Coding Agents