--- title: "Codex CLI Tutorial: Setup and First Workflow" description: "OpenAI Codex CLI tutorial: install it, sign in with ChatGPT or an API key, write an AGENTS.md, and run your first task safely. Current setup and workflow for 2026." type: "guide" locale: "en" category: "Codex" canonical: "https://agenticschool.dev/guides/codex-cli-tutorial" datePublished: "2026-06-13" dateModified: "2026-06-13" --- # Codex CLI Tutorial: Setup and First Workflow - Category: Codex - Keywords: codex cli tutorial, openai codex cli, codex cli setup, agents.md, codex cli getting started - Canonical URL: https://agenticschool.dev/guides/codex-cli-tutorial - Locale: en > OpenAI Codex CLI tutorial: install it, sign in with ChatGPT or an API key, write an AGENTS.md, and run your first task safely. Current setup and workflow for 2026. Codex CLI is OpenAI's terminal-based coding agent: you run one command in your project, describe what you want in plain language, and the agent reads your files, plans, edits code and runs commands in your terminal. This tutorial takes you from nothing installed to a productive first workflow: how to install Codex CLI, how to sign in (with your ChatGPT account or an API key), how to give it project rules with an AGENTS.md, and how to run a first task safely. If you are weighing it against Anthropic's agent, see our Claude Code vs Codex CLI comparison; the two are close cousins and the habits transfer. Everything here was verified against the official OpenAI Codex docs in June 2026, and because this tool evolves fast, the exact commands are the part to double-check against the docs. ## What Codex CLI is Codex CLI is an agent harness from OpenAI: a lightweight coding agent that runs in your terminal, wraps a model in a loop with tools (read files, edit files, run shell commands), and works directly in your repository toward a goal you set. Like Claude Code, it does not just hand you snippets to paste; it makes multi-file changes and runs commands, and you stay in control by reviewing what it proposes and approving the actions that matter. It is open source and grew quickly: by early 2026 it had passed two million weekly active users. The project configuration model is AGENTS.md, an open, tool-agnostic convention for giving a coding agent its standing instructions, which is the Codex equivalent of Claude Code's CLAUDE.md. See the glossary on the agent harness for the underlying concept. - A terminal coding agent that reads, edits and runs code in your repo, not an autocomplete. - You supervise: it proposes actions and you approve the ones that matter. - Open source, with more than two million weekly active users by early 2026. - Configured with AGENTS.md, an open, tool-agnostic standing-instructions convention. ## Installing Codex CLI Install Codex CLI with npm or Homebrew. The npm install puts the codex binary on your path globally and needs Node.js 18 or later; the Homebrew cask is the convenient option on macOS. Pick one, then confirm it is on your path. These commands are current as of June 2026 against the official quickstart, but because the tool moves fast, check the OpenAI Codex docs if anything has shifted. ```bash # npm (needs Node.js 18+) npm install -g @openai/codex # Homebrew on macOS brew install --cask codex # Confirm it is installed and on your path codex --version ``` Install Codex CLI with npm or Homebrew, then verify the version. Verified against the official docs in June 2026. ## Signing in On first run, Codex prompts you to authenticate, and you have two paths. The recommended one for most people is signing in with your ChatGPT account, which uses Codex as part of a paid ChatGPT plan (Plus, Pro, Business, Edu or Enterprise). The alternative is an OpenAI API key, billed per token, which is the right choice for automation, CI, or if you prefer usage-based billing; note that some functionality may differ between the two. To use a key, set it as an environment variable before launching, or follow the in-app sign-in flow for ChatGPT. Just run codex and pick "Sign in with ChatGPT" when prompted. ```bash # Start Codex; on first run it walks you through sign-in codex # Option A (recommended): choose "Sign in with ChatGPT" in the prompt # uses your paid ChatGPT plan (Plus, Pro, Business, Edu, Enterprise) # Option B: authenticate with an API key (good for CI and automation) export OPENAI_API_KEY="your-api-key" codex ``` Authenticate with your ChatGPT account (recommended) or an OpenAI API key for automation and CI. ## Giving it rules with AGENTS.md AGENTS.md is how you teach Codex your project's standing rules, the same role CLAUDE.md plays for Claude Code, and because it is an open convention many agents read it. Codex builds an instruction chain when it starts, walking from a global file down to your current directory and concatenating them, with files closer to your working directory taking precedence in a conflict. That means three useful scopes: a global ~/.codex/AGENTS.md for your personal defaults, an AGENTS.md at your repository root for project rules everyone shares, and nested AGENTS.md files in subdirectories for area-specific overrides. Keep it focused on setup, conventions and test requirements; Codex respects a default size limit (about 32 KiB across the chain), and like any standing-instructions file, a tight one beats a sprawling one. ```markdown # AGENTS.md (at your repository root) ## Setup - Install with `bun install`. The dev server is `bun run dev`. ## Conventions - TypeScript only. Use "-" not em dashes. Border radius is always rounded-sm. ## Tests and quality gate - Before you call a task done, run: bun run lint && bun run typecheck && bun run test. ## Out of scope - Do not edit files under /generated; they are built, not hand-edited. ``` A compact AGENTS.md at the repo root. Codex reads global, then project, then nested files, with the closest winning. ## Your first task Open a terminal inside the project you want to work on and run codex. Start small to build trust: ask it to explain the project or find where something lives before you have it change anything. When you do ask for an edit, prefer to have it propose its approach first, review the change it makes, and keep your tests green. A safety habit the docs recommend is to commit a clean Git checkpoint before a task and again after, so a change you do not like is one git restore away. Codex offers approval modes that control how much it can do without asking; start more cautious, where it asks before running commands or editing, and loosen it only once you trust the workflow on a given repo. - Run codex inside your project; begin with a read-only request like "explain what this project does". - For edits, have it propose the approach, then review the diff before you accept it. - Commit a Git checkpoint before and after a task so you can roll back cleanly. - Start with a cautious approval mode (it asks before acting) and loosen it only once you trust it. ## Where to go next Once the basics click, the habits that make Codex reliable are the same ones that make any coding agent reliable, and they transfer directly from our other guides. Lean on the Prompt Patterns for Coding Agents guide for how to brief it well, the Context Engineering guide for keeping its window sharp on long tasks, and the What Is Agentic Engineering pillar for the discipline of directing and verifying rather than accepting unchecked output. If you also use Anthropic's agent, the Claude Code vs Codex CLI comparison lays out where each fits, and the Foundations course installs and runs both side by side. - Prompt Patterns for Coding Agents: how to brief Codex with a spec, examples and a verification loop. - Context Engineering: keep its context window sharp across long tasks. - Claude Code vs Codex CLI: which terminal agent fits which job. - Foundations course: installs and runs Claude Code and Codex side by side. ## Steps ### 1. Install Codex CLI Install with npm ("npm install -g @openai/codex", needs Node.js 18+) or Homebrew ("brew install --cask codex" on macOS). Confirm with "codex --version". ### 2. Sign in Run "codex" and choose "Sign in with ChatGPT" to use a paid ChatGPT plan, or set OPENAI_API_KEY in your environment to authenticate with an API key for automation and CI. ### 3. Write an AGENTS.md Add an AGENTS.md at your repository root with your setup, conventions and quality-gate command. Codex reads global, project and nested files, with the closest to your working directory winning. ### 4. Run a first task safely Run "codex" in your project, start with a read-only request, commit a Git checkpoint before and after, and use a cautious approval mode so it asks before running commands or editing. ### 5. Review and continue Read the diff before accepting any change, keep your tests green, and loosen the approval mode only once you trust the workflow on that repo. ## FAQ ### How do I install OpenAI Codex CLI? Install it with npm using "npm install -g @openai/codex" (which needs Node.js 18 or later), or on macOS with Homebrew using "brew install --cask codex". Confirm the install with "codex --version". These commands are current as of June 2026; check the official OpenAI Codex docs as the tool evolves. ### How do I sign in to Codex CLI? Run "codex" and you will be prompted to authenticate. The recommended path is "Sign in with ChatGPT", which uses Codex as part of a paid ChatGPT plan (Plus, Pro, Business, Edu or Enterprise). Alternatively, set the OPENAI_API_KEY environment variable to authenticate with an API key, which suits automation and CI. ### What is AGENTS.md in Codex CLI? AGENTS.md is the file that gives Codex your project's standing instructions, the same role CLAUDE.md plays for Claude Code. Codex builds an instruction chain from a global ~/.codex/AGENTS.md, then a project-root AGENTS.md, then nested files in subdirectories, concatenating them with the file closest to your working directory taking precedence. ### Is Codex CLI free? Codex CLI itself is open source, but using it requires either a paid ChatGPT plan (signing in with your ChatGPT account) or an OpenAI API key billed per token. There is no fully free tier for running the agent; you pay through one of those two paths. ### What is the difference between Codex CLI and Claude Code? Both are terminal-based coding agents that read, edit and run code in your repo. Codex CLI is OpenAI's, configured with AGENTS.md and signed in via ChatGPT or an API key; Claude Code is Anthropic's, configured with CLAUDE.md. The workflows are very similar. See our Claude Code vs Codex CLI comparison for a current, honest breakdown. ### How do I run my first task with Codex CLI safely? Open a terminal in your project and run "codex". Start with a read-only request to build trust, commit a clean Git checkpoint before and after the task so you can roll back, and use a cautious approval mode so Codex asks before running commands or editing files. Review every diff before you accept it.