Installing and Running the Codex CLI
From zero to running your first agentic coding session: install the Codex CLI, authenticate, and understand the interactive session lifecycle.
Prerequisites: One Decision Before You Install
You do not need a Node.js toolchain to run the Codex CLI — the recommended install is a standalone binary. You do, however, need a way to authenticate. From the previous lesson you have two valid options: sign in with your ChatGPT account on first run, or set an OPENAI_API_KEY. Either works for the CLI. If you want to use a key, export it now so it persists:
export OPENAI_API_KEY=sk-proj-...your-key-here...
Add that line to your ~/.zshrc or ~/.bashrc. If you would rather sign in with your ChatGPT account, you can skip the key — the CLI will prompt you to sign in the first time you run it.
Installing the CLI
The recommended install is the standalone install script, which downloads a prebuilt binary — no Node.js required:
# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
On Windows, run the PowerShell installer instead:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
Homebrew is also supported on macOS:
brew install --cask codex
npm fallback. If you prefer to manage the CLI through npm, it is still published there — it is a thin wrapper that downloads the prebuilt binary, and its engines field asks for a recent Node LTS (check node --version; install or upgrade from nodejs.org or via nvm/fnm if needed). The standalone installer above sidesteps Node entirely:
npm install -g @openai/codex
The -g flag installs it globally, making the codex command available in any directory. Whichever install method you used, verify it worked:
codex --version
If you get command not found, your global npm bin directory is not in your PATH. Run npm prefix -g to find the global install prefix, then add its bin subfolder to your PATH in your shell profile. (Older guides mention npm bin -g, which printed the bin directory directly — but that command was removed in npm v9.)
Your First Session
Open a terminal in any project directory. A real project with actual files gives you a more useful first experience than an empty folder — the agent's value comes from reading your existing code.
cd ~/your-project
codex
The first time you run it, Codex walks you through authentication — it prompts you to sign in with your ChatGPT account (opens a browser to confirm) or to use an API key if you set OPENAI_API_KEY. Once that is done, you are in the interactive session.
Give it a concrete task in plain English:
Add a README.md to this project that explains what it does based on the code you see.
Codex reads the files in your project, proposes a plan (listing what it intends to create or modify), and waits for your approval before touching anything.
The Session Lifecycle
Once you understand the lifecycle, working with Codex becomes fluent. The loop is the same whether you are fixing a bug, adding a feature, or writing tests.
Prompt. You give a task. Plain English. The more specific you are, the better the plan. "Refactor auth.ts" is weaker than "Refactor auth.ts to use async/await throughout and add JSDoc comments to all exported functions."
Plan. Codex reads your repository and proposes the approach: which files it will touch, what it will change, and in what order. This is your primary review point.
Approve. Press Enter to proceed, type feedback to redirect, or Ctrl+C to cancel. If the plan looks wrong, say so — Codex will revise and show you a new plan.
Edit. Codex applies the changes. You can watch the diffs as they are written. Multiple files can be edited in a single step.
Run. After editing, Codex executes any verification commands it determines are appropriate — typically your test suite, linter, or build command. It reads the output to check for failures.
Observe. If tests pass, the session completes. If tests fail, Codex reads the error output and loops back to the edit step, proposing a fix. This iteration continues until the tests pass or Codex asks you for guidance on something it cannot resolve autonomously.
Done. The session transcript is saved to ~/.codex/. The changes are applied to your files. If you are on a Git branch (and you should be — always work on a feature branch, never on main), you commit and push when you are satisfied with the result.
Useful Flags and Commands
# Show all available options
codex --help
# Run non-interactively (for scripts and CI) with the exec subcommand
codex exec "fix all TypeScript errors"
# Control autonomy with two independent flags:
# --ask-for-approval (untrusted | on-request | never)
# --sandbox (read-only | workspace-write | danger-full-access)
codex --ask-for-approval on-request --sandbox workspace-write "refactor auth.ts"
# Resume a recent session
codex resume
# Specify a model (-m for short); use a current model name from the docs
codex --model <model-name> "add input validation"
Two things worth knowing here. First, the non-interactive entry point is the codex exec subcommand — that is what you reach for in CI, not a --no-interactive flag. Second, autonomy is governed by two separate flags rather than one combined mode: --ask-for-approval decides when Codex pauses to ask you, and --sandbox decides what it is technically allowed to do. (You may still see an older --full-auto shorthand in tutorials; it is a deprecated compatibility flag — prefer the explicit --sandbox/--ask-for-approval pair. The “Approvals, Sandboxing, and Safety” lesson covers this two-axis model in depth.)
For the current list of flags and the current model names, check codex --help and developers.openai.com/codex — the CLI evolves with new releases, and the live documentation is always more current than any lesson or tutorial.
Configuration at ~/.codex/
Codex stores its configuration in a hidden directory in your home folder: ~/.codex/. Here you can find past session transcripts, and configuration files for things like default model, approval mode, and sandbox settings.
The exact schema of the config files is documented in the Codex repository (@openai/codex on npm / GitHub). For most users getting started, the defaults are sensible — you do not need to edit these files to start being productive. They become relevant once you want to tune behavior for a specific workflow.
How Knox Uses This Pattern
The workflow you are learning here — give a plain-English task, review the plan, approve, observe — is exactly how teams run agentic coding tools like Claude Code in production. The agent reads a configuration file (a CLAUDE.md for Claude Code, an AGENTS.md for Codex), reads the codebase, and operates within the rules established in that file.
The same discipline applies regardless of which tool you use: work on a feature branch, review the plan before approving, verify the result after the agent completes. The agent is not infallible — its judgment is only as good as its understanding of your intent and your codebase. Your review is the quality gate.
For deeper case studies on how production AI coding workflows are structured and what the failure modes look like at scale, jeremyknox.ai documents the real patterns — not tutorials, but the actual architecture of running AI agents in a live engineering operation. For the psychology and cognition side of working effectively with AI tools, Rewired Minds covers how humans and AI systems collaborate well.