A Codex Cli Tutorial For Installing, Authenticating, And Running Your First Session

Codex CLI is OpenAI's open source, terminal based coding agent that reads, edits, and runs code from natural language prompts.

This codex cli tutorial walks through installing it, signing in, and running your first session, plus the commands and settings you'll actually use.

What Is Codex CLI? A Codex Cli Tutorial Overview

Codex CLI is a command line tool built by OpenAI. According to TechCrunch, OpenAI introduced it as a lightweight, open source coding agent designed to run locally in a developer's terminal.

It runs directly inside your terminal, reads the files in your project directory, and can edit them, run shell commands, and carry out multi step tasks based on plain English instructions.

It doesn't need a separate code editor to function. Open a terminal, point it at a folder, and it works from whatever is already there.

This codex cli tutorial focuses on the parts of the tool most people actually reach for: getting it installed, signed in, and running, then understanding the settings that control how much it's allowed to do on its own.

In practice, most people treat it less like a chatbot and more like a colleague who can read the whole repository before answering.

What You Need Before Installing Codex CLI

A few things need to be in place first:

• A ChatGPT account with Codex access (this comes with paid ChatGPT plans), or an OpenAI API key as an alternative
• Node.js 18 or later, if you're installing through npm
• macOS or Linux for full support. Windows works too, but support there is still described as experimental, and running it through WSL tends to be smoother

None of this is unusual by CLI tool standards. Teams commonly report that the Node.js version mismatch is the single most common install snag, so it's worth checking node -v before anything else.

How to Install Codex CLI

There are three confirmed ways to install it, and which one makes sense depends mostly on what's already on your machine.

Install via npm

npm install –global @openai/codex

This is the most common method and requires Node.js to already be installed.

Install via Homebrew (macOS)

brew install codex

Straightforward if you're already using Homebrew for other command line tools.

Install via the Standalone Installer (macOS/Linux)

curl -fsSL https://chatgpt.com/codex/install.sh | sh

This skips Node.js entirely. Platform specific binaries are also available directly from GitHub releases, which is worth knowing if you're setting this up on a machine without internet access to npm.

Verify the Installation Step of This Codex Cli Tutorial

Once it's installed, confirm it actually worked:

codex –version

You should see output similar to codex-cli 0.77.0. The exact version number will differ depending on when you install, since it updates regularly.

How to Authenticate Codex CLI

Codex needs to know who you are before it does anything useful.

Sign In With ChatGPT

Run codex or codex login, and it opens a browser window to authorize access. Once approved, usage is billed through your existing ChatGPT plan rather than separately.

Authenticate With an API Key

For automation, scripts, or CI/CD pipelines, an API key works better than an interactive login:

export OPENAI_API_KEY=YOUR_API_KEY

This is the method most teams use when Codex is being called from a pipeline rather than a person typing at a keyboard.

Starting Your First Codex CLI Session

Open a Project Directory

Navigate to your project first:

cd ~/your-project

If typing terminal commands isn't second nature yet, most file browsers let you right click a folder and open a terminal directly at that location. Either route gets you to the same place.

Launch Codex

codex

The first time you run this inside a given project, it asks which approval mode to use. That choice matters more than it seems, and it's covered in detail below.

Try a First Prompt

Simple prompts work fine to start:

• "Explain the structure of this project"
• "Add error handling to the database connection module"

Codex reads the relevant files, proposes a change, and shows a diff before touching anything. Nothing gets modified without your review, at least not under the default settings.

Understanding Codex CLI Approval Modes

This is one part of the codex cli tutorial worth slowing down for, because it's the setting most likely to catch people off guard later. Approval modes decide how much Codex can do without asking first.

Mode	What It Does
Auto (default)	Reads, edits, and runs commands inside your working directory automatically. Asks before doing anything outside that scope.
Read-only	Keeps Codex consultative. It can look at files and suggest changes, but it won't edit or run anything without explicit approval.
Full Access	Grants broader autonomy, including network access. Best reserved for tasks where you already trust the scope of work.

Switch between modes mid session with /permissions (some versions use /approval).

Interestingly, a lot of the "why isn't Codex doing X" confusion people run into traces back to a restrictive mode blocking an action quietly rather than the tool actually failing.

Core Codex CLI Commands

Slash Commands

Press / inside a session to see the full list. The ones you'll use most:

• /init: creates an AGENTS.md file with project instructions
• /status: shows current session configuration and token usage
• /model: switches the model or reasoning effort
• /review: reviews uncommitted changes, a commit, or a branch for issues
• /new: starts a fresh conversation, clearing prior context
• /compact: summarizes and compresses conversation history to save tokens
• /quit: ends the session

Bash Passthrough Commands

Prefix any shell command with ! to run it directly without leaving the session:

!ls

!pwd

!git status

The output stays visible in the conversation, so Codex can reference it without you having to describe what you're seeing.

In practice, this usually saves more time than it looks like on paper, since it removes the back and forth of switching terminal windows.

Referencing Specific Files

Use @filename to point Codex directly at a file rather than letting it search the whole directory.

Resuming a Previous Codex CLI Session

Closing a session doesn't lose your context. Exiting gives you a session ID, and you can pick back up with:

codex resume ID

Or, to grab the most recent one without hunting for the ID:

codex resume –last

Session logs are stored locally in JSON Lines format under ~/.codex/sessions/. What's often overlooked is that these same session files are shared with supported editor extensions, so a conversation started in the terminal can continue inside an editor, and vice versa.

Customizing Codex CLI With a Project Configuration File

Codex reads a file called AGENTS.md at the start of every session if one exists at the project root.

It's a plain markdown file describing conventions for that specific project, such as the tech stack, testing rules, and formatting preferences.

Teams commonly report that setting this up once at the start of a project saves them from repeating the same instructions in every session afterward.

A basic version might just list the stack and a couple of hard rules, like requiring tests to pass before a commit.

Extending Codex CLI With MCP Servers

What Is MCP?

Model Context Protocol, or MCP, is an open standard that lets Codex connect to tools outside your local filesystem, such as a browser, a design tool, or a documentation source.

According to Wikipedia, the protocol was introduced in November 2024 to standardize how AI systems integrate and share data with external tools, and it has since been adopted by major AI providers, including OpenAI.

Adding an MCP Server

A server can be added with a single command:

codex mcp add [server-name] [command]

Confirm it's connected with:

codex mcp list

Alternatively, servers can be configured directly by editing ~/.codex/config.toml. This route is more manual but gives more visibility into exactly what's connected and how.

Packaging Workflows as Skills

A Skill is a reusable set of instructions, stored in a SKILL.md file alongside any needed resources or scripts, that Codex can run on demand for a repeatable task.

Rather than re-explaining a multi step workflow every time, a Skill lets you trigger it with a short phrase.

This tends to matter most once a workflow has been repeated a few times manually. At that point, packaging it into a Skill removes the repetition without needing to script it separately outside of Codex.

Troubleshooting Common Codex CLI Issues

A handful of problems come up often enough to be worth listing directly.

• "Command not found" after installing: check that Node.js is installed correctly and that your PATH includes the global npm directory.
• Codex won't take an action you expect: check your current approval mode with /status, since a restrictive mode can silently block file edits or command execution.
• Authentication fails: confirm your ChatGPT plan includes Codex access, or re-run codex login to restart the authorization flow.

Conclusion

Getting Codex CLI running comes down to a short sequence: install it, sign in, run your first session, and understand approval modes before handing it more autonomy.

Everything else, from MCP servers to Skills, builds on that same foundation.

Frequently Asked Questions

Is Codex CLI free to use?

Not entirely on its own. It requires either a paid ChatGPT plan that includes Codex access, or billing through an OpenAI API key. There's no standalone free tier confirmed for ongoing use.

Does Codex CLI work on Windows?

It runs on Windows, but support is described as experimental. For a more stable experience, running it inside WSL (Windows Subsystem for Linux) is the commonly recommended approach.

What's the difference between Codex CLI's approval modes?

Auto handles edits and commands automatically within your working directory. Read-only limits it to suggestions. Full Access allows broader autonomy, including network access, for tasks where more trust is warranted.

Can I use Codex CLI without a ChatGPT account?

Yes. Authenticating with an OpenAI API key instead of a ChatGPT sign in works, and it's the more common route for automation or CI/CD use rather than interactive sessions.

Where are Codex CLI session logs stored?

Locally, in JSON Lines format, under ~/.codex/sessions/ on your machine. These same files are also read by supported editor extensions, so sessions can carry over between terminal and editor.