OpenAI Codex CLI: Getting Started in 10 Minutes

OpenAI’s Codex CLI is a coding agent that lives in your terminal: it reads your repository, edits files, runs commands in a sandbox, and explains what it did. Setup is three steps: install with npm i -g @openai/codex (or brew install codex), sign in with your ChatGPT account, and run codex inside a project. The CLI is open source and free; what you pay for is the capacity behind it, either the Codex usage included in your ChatGPT plan or metered API tokens.

Install the CLI

Both installers ship the same binary from github.com/openai/codex:

npm i -g @openai/codex
# or, on macOS
brew install codex

codex --version

If codex --version prints a version, step one is done. Updates arrive the same way: npm update -g @openai/codex or brew upgrade codex. OpenAI ships frequently, so updating before you debug a weird behavior is a good habit.

Sign in: ChatGPT account or API key

The recommended route is your ChatGPT account:

codex login

This opens a browser for OpenAI’s sign-in flow. Codex is included in ChatGPT Free, Go, Plus, Pro, Business, Edu, and Enterprise plans, so once you are signed in, CLI usage draws from your plan instead of an API meter. Sign in with ChatGPT and Codex bills to the flat subscription you already pay for.

The alternative is an API key, billed per token:

printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key

The choice matters more than it looks. Plans give you flat capacity inside usage windows; keys give you metered spend and cleaner credential handling in shared CI. We compare the two properly in Codex auth: API key vs ChatGPT sign-in.

On a machine with no browser, codex login --device-auth prints a code you approve at chatgpt.com from any device. The full server story, including systemd and auth file handling, is in our headless guide.

Wherever you sign in, the session lands in ~/.codex/auth.json. Treat that file exactly like a password: it is a live credential for your account. Keep it out of repos, out of shared backups, and off machines other people use.

Your first session

Start Codex inside a project, not your home directory, so it has something to read:

cd your-project
codex

Good first prompts, in rough order of trust:

• “Explain the structure of this codebase and where the entry points are.”
• “Write tests for src/utils/dates.ts and run them.”
• “The build fails on main. Find out why and propose a fix.”

Codex plans, edits files, and runs commands, asking before anything risky by default. Watch the proposed commands the first few sessions instead of approving on reflex; you will learn its habits fast, and it will learn yours from the corrections you give it.

If the repo has an AGENTS.md file at the root, Codex reads it for standing instructions: conventions, test commands, things it should never touch. Creating one early is the cheapest quality lever the CLI has.

Config basics

Two safety dials control most of the CLI’s behavior: the approval policy (when Codex asks permission) and the sandbox (what it may touch). Persistent settings live in ~/.codex/config.toml:

# ~/.codex/config.toml
approval_policy = "on-request"    # untrusted | on-failure | on-request | never
sandbox_mode = "workspace-write"  # read-only | workspace-write | danger-full-access

The defaults are sensible. Loosen them only when you understand the trade: never plus danger-full-access is appropriate inside a throwaway container and reckless on your laptop.

Pick a model with the /model command inside the session. OpenAI rotates the available Codex models over time, so we will not hardcode names here. /status shows your account, model, and current usage whenever you want a readout.

Where codex exec fits

The interactive session is for pairing. For scripts, pipelines, and cron, the CLI has a documented non-interactive mode:

codex exec "extract all TODO comments as a JSON array"

It runs the prompt to completion, prints the result to stdout, and exits, which makes Codex composable with everything else in your toolchain. The full treatment, including session resume and CI patterns, is in the codex exec guide.

The limits you will meet eventually

Plan-backed usage is flat but not infinite. OpenAI meters Codex over a rolling window of roughly five hours, with weekly components on some plans, and the exact capacity varies by plan and model. Light interactive use rarely notices the meter; agent-heavy days do. The whole system, including credits and resets, is mapped in Codex usage limits, explained. Read it before you wire Codex into anything that runs unattended.

That is the setup: install, log in, run it in a repo, tune two config keys. If what you actually want from Codex is programmatic, an endpoint your apps call rather than a terminal you type into, that is the part we run for you: Codex Hosted keeps the official, unmodified CLI signed in with your own account in a managed container, behind one OpenAI-compatible URL.