Getting started with OpenAI Codex CLI: from install to daily use
A practical guide to installing OpenAI's Codex CLI, configuring auth, shipping your first change, and integrating it into daily coding.
How to
Install Codex CLI and log in
Run npm i -g @openai/codex. Launch codex and use /login to choose OPENAI_API_KEY or a ChatGPT subscription — the subscription is cheaper for everyday use.
Restrict changes with a sandbox
Codex runs inside an OS sandbox. Pick a mode: --sandbox read-only (read but not write), --sandbox workspace-write (edit the current directory), --sandbox danger-full-access (no limits). Approval prompts are separate — pass --ask-for-approval never to skip them. (--full-auto is deprecated shorthand for workspace-write + never-ask.)
Move Codex into an isolated git worktree
Run git worktree add ../mycodex-feature-branch main. Codex works on the branch, you review the diff, then merge.
Let Codex fix a real bug
Describe the problem in natural language ("fix the NPE in src/foo.ts"). Codex reads, edits, and self-checks; review with git diff before merging.
Pre-merge safety checks
Confirm Codex did not touch secrets, lockfiles, or CI configs. Block sensitive paths with a hook. Review per your CODEOWNERS flow before merging.
Getting started with OpenAI Codex CLI: from install to daily use
The OpenAI Codex CLI is a terminal-based coding agent that reads a local repo, edits files, runs commands, and iterates on errors using a hosted Codex model.
1. Overview
Codex CLI is OpenAI's local coding agent. It runs in your terminal, talks to a hosted Codex model, reads the repo, edits files, runs commands, and self-corrects. This walkthrough takes you from a clean install to a real change landed on a branch.
2. Key points
- Installs with a single npm command on macOS, Linux, and Windows (WSL)
- Auth via OPENAI_API_KEY or a ChatGPT subscription; the subscription is cheaper for everyday use
- Interactive /codex subcommands or -q (quiet) mode for headless batch tasks
- Codex runs inside an OS-enforced sandbox; values: --sandbox read-only / workspace-write / danger-full-access. Approval prompts are separate, set via --ask-for-approval. --full-auto is shorthand for workspace-write + never-ask (deprecated in 0.128.0)
- Best practice: put Codex in its own git worktree, review the diff, then merge
3. How it works
The sections below unpack each point. Skim alongside the OpenAI documentation for full context.
4. Practical steps
- Define 'done' up front — what does success look like?
- Pick the right model using the comparison above.
- Run the minimal example end to end; record parameters and the model version.
- Integrate into your existing code.
- Monitor logs and failure modes; review weekly.
5. Common errors and fixes
- 401: invalid or expired API key — rotate it.
- 429: rate limit hit — enable exponential backoff retries.
- 400: bad request — verify the model name and messages shape.
- Poor quality output: try a different model, add few-shot examples, trim the prompt.
6. Next steps
Once you are comfortable here, continue with:
- ChatGPT Complete Guide (2026): From Beginner to Expert
- Prompt Engineering Core Patterns: 8 Templates That 2x GPT Output
- OpenAI API Beginner: Your First GPT-5.6 Call
Key points
- Installs with a single npm command on macOS, Linux, and Windows (WSL)
- Auth via OPENAI_API_KEY or a ChatGPT subscription; the subscription is cheaper for everyday use
- Interactive /codex subcommands or -q (quiet) mode for headless batch tasks
- Codex runs inside an OS-enforced sandbox; values: --sandbox read-only / workspace-write / danger-full-access. Approval prompts are separate, set via --ask-for-approval. --full-auto is shorthand for workspace-write + never-ask (deprecated in 0.128.0)
- Best practice: put Codex in its own git worktree, review the diff, then merge
❓ Frequently asked questions
Official references
Subscribe to GPTMap Weekly
One email every Monday: curated OpenAI updates, deep dives, and best practices. No ads, unsubscribe anytime.