GPTMap

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.

TL;DR
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.
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.

How to

  1. 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.

  2. 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.)

  3. 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.

  4. 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.

  5. 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.

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

  1. Define 'done' up front — what does success look like?
  2. Pick the right model using the comparison above.
  3. Run the minimal example end to end; record parameters and the model version.
  4. Integrate into your existing code.
  5. 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

Copilot CLI suggests commands and explains shell output; Codex CLI is an autonomous agent that reads your repo, edits multiple files, runs tests, and iterates on its own errors. Copilot is best for one-shot suggestions inside a terminal; Codex is best for handing off a well-scoped task (a bug fix, a refactor, a feature stub) and reviewing the diff.

Official references

Related articles

Codex
5 min

Codex Cloud Setup: Environments, Cloud Tasks, and the codex cloud CLI

Codex Cloud (called Codex Web in the source) is the hosted Codex surface: tasks run in cloud environments organized per GitHub repo, and the codex cloud CLI submits, tracks, and pulls diffs back to your machine.

Read article
Codex
3 min

Codex CLI config.toml: The Complete Guide to Models, Approvals, MCP and Layered Config

Codex CLI centers on ~/.codex/config.toml: model picks the model, approval_policy gates prompts, sandbox_mode sets boundaries, mcp_servers wires tools, profiles switch scenarios.

Read article
Codex
4 min

Codex CLI Sandbox Modes: sandbox_mode and approval_policy Explained

Codex CLI sandbox has four levels — read-only, workspace-write, external-sandbox, danger-full-access — plus a separate approval_policy axis. Every value checked against the codex source enums.

Read article

Subscribe to GPTMap Weekly

One email every Monday: curated OpenAI updates, deep dives, and best practices. No ads, unsubscribe anytime.

Submitting opens Buttondown in a new tab to confirm your subscription.

GPTMap EditorialPublished 2026-07-12Updated 2026-07-14 2 min read
Test environment (EEAT)
Last tested: 2026-07-14
Model used: gpt-5.6
Codex#codex#OpenAI#guide