Codex CLI: getting started

Beginner 15 min

Codex CLI is OpenAI’s coding agent in the terminal. It can read your project, explain code, propose changes, edit files, and run commands in the directory where you start it.

Requirements

macOS, Linux, or Windows through WSL
Node.js/npm or Homebrew
Git
A ChatGPT account or OpenAI API key
A project you can test on

OpenAI documents Windows support, but WSL is the best Windows path for most CLI workflows.

Install Codex CLI

npm install -g @openai/codex
codex --version

brew install codex
codex --version

Install Node.js or Homebrew inside WSL, then run:

npm install -g @openai/codex

Start Codex:

codex

The first run prompts you to sign in with ChatGPT or an OpenAI API key. If you use an API key, store it through the CLI flow or an environment variable. Do not paste secrets into prompts.

First safe session

Enter a project:
Terminal window
```
cd your-project
git status
```
Start Codex:
Terminal window
```
codex
```

Send a read-only task:

Explain this project from the repository files. Do not make changes.
Tell me which test or build commands you would run, but do not run them yet.

Allow a small edit only after the explanation looks correct.

Permissions, models, and AGENTS.md

Codex uses sandboxing and approval prompts. Useful in-session commands:

Command	Use
`/model`	Choose model and reasoning level
`/permissions`	Switch between read-only, auto, and broader access
`/review`	Run a local code review
`/status`	Show active directory, sandbox, and session

OpenAI currently recommends gpt-5.4 for most Codex tasks:

codex --model gpt-5.4

Three Good Codex Workflows

Explain the repository

Start read-only. Ask Codex to find build, test, deploy, data models, and risky files without changing anything.

Small change

Ask for one concrete change, let Codex run the relevant checks, and read the diff before committing.

Review before commit

Use /review on uncommitted changes, a commit, or a branch before you push.

Good first task after installation:

Find the project's build, test, and lint commands.
Explain which files control routing, deployment, and environment variables.
Do not make changes.

Good first write task:

Fix only the smallest necessary issue in [file or component].
Use existing patterns.
Run the relevant check.
Stop and explain if the change requires a new dependency or deploy.

Flags You Should Know

Flag or command	Use
`codex --cd path/to/app`	Start Codex in the right project folder without running `cd` first.
`codex --add-dir ../shared`	Grant access to one extra folder without opening the whole machine.
`codex --sandbox read-only`	Read and explain without file edits. Good for unknown code.
`codex --full-auto`	Work in the workspace with approvals for riskier actions. Use in clean Git repos.
`codex --search`	Use live web search when the task needs current sources. Treat web content as untrusted.
`codex exec --json "..."`	Use Codex in scripts with JSONL events.
`codex exec --output-last-message result.md "..."`	Save the final summary for a script or CI job.
`codex resume --last`	Continue the latest session in the same project.

Codex reads AGENTS.md as project instructions:

# AGENTS.md

## Project
- Run `npm run build` after site changes.
- Prefer existing Starlight components.
- Do not deploy without an explicit instruction.

## Done when
- Build passes.
- Git diff has been reviewed.

Codex layers instructions from global AGENTS.md, the repository AGENTS.md, and more specific files closer to the folder where you started. In a monorepo, that means a short root file plus precise rules in apps/site/AGENTS.md usually works better than one huge root file.

Keep the file short. OpenAI notes that large instruction files and many MCP servers can increase context and usage.

Script Mode

Use codex exec for automation or one-off tasks:

codex exec "Explain the main risks in this repo without changing files"

Script mode is best for tasks with clear output: reports, review, changelogs, CI triage, or repeated checks. If the task can edit files, keep Git clean and use sandboxing or a separate worktree.

Example read-only review automation:

codex exec \
  --sandbox read-only \
  --ask-for-approval never \
  --output-last-message codex-review.md \
  "Read this diff and find concrete bugs, regression risks, and missing tests. Do not make changes."

Cost in Practice

Codex can use ChatGPT login with included limits or an API key with token-based billing. Usage grows especially when:

the prompt is broad
the repository is large
AGENTS.md is long
many MCP servers are enabled
you use subagents
the agent rereads many files

For routine work, gpt-5.4-mini can stretch local-message limits further than heavier models. Use gpt-5.4 for hard debugging, architecture, and high-risk changes.

Sources

Last checked: April 11, 2026.