Codex CLI Tutorial: How to Install and Run OpenAI's Terminal Coding Agent

This codex cli tutorial covers what Codex CLI does, how to install it, how to sign in, and how to run your first task from a project folder.By the end, you'll have a working session and a sense of what to try next.

Codex CLI Tutorial: What Is Codex CLI

Codex CLI is OpenAI's open source coding agent that runs inside your terminal. According to Wikipedia, it was released in April 2025 and was built for software engineering tasks like writing code and fixing bugs.

You describe a task in plain language, and it reads your files, proposes edits, and can run commands on your machine. Nothing leaves your local environment unless you tell it to.

In practice, most people reach for it the same way they'd reach for a very capable pair programmer who happens to live in a terminal window instead of a chat app.

That's really the whole idea behind this codex cli tutorial: getting you from a blank terminal to a working session without guesswork.

Prerequisites Before You Install Codex CLI

A few things need to be in place first.

  • A ChatGPT account with Codex access, which comes with paid ChatGPT plans, or an OpenAI API key as an alternative
  • Node.js installed, if you're using the npm install method
  • macOS or Linux for full support. Windows works too, but it's still considered experimental, and running Codex inside WSL tends to be smoother

Teams that skip the prerequisite check usually end up troubleshooting an install failure that had nothing to do with Codex itself. Confirming Node.js is present first saves that detour.

Codex CLI Tutorial: Installation Steps

There are a few install paths, and which one you pick mostly comes down to what's already on your machine.

Install Codex CLI via npm

npm install –global @openai/codex

This is the most common route, since most developers already have Node.js set up.

As reported by TechCrunch, OpenAI described the original goal of Codex CLI as giving users a minimal, transparent interface for connecting AI models directly to local code and tasks, which is part of why the install process stays this simple.

Install Codex CLI via Homebrew (macOS)

brew install codex

A reasonable option if you already manage your command line tools through Homebrew.

Install Codex CLI via Standalone Installer

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

Works on macOS and Linux without needing Node.js at all.

Codex CLI Tutorial: Confirming the Installation

codex –version

You should see a version number printed back, something like codex-cli 0.77.0. The exact number will differ depending on when you install it, since Codex CLI updates fairly often. That's normal. What matters is that a version prints at all.

If nothing comes back, the install didn't complete, and it's worth rerunning the command before moving on.

How to Authenticate Codex CLI

Once it's installed, Codex needs to know who you are before it'll do anything useful.

Sign In With ChatGPT

Run codex for the first time, then choose "Sign in with ChatGPT" when prompted. This is the path most people take, and usage is included as part of your ChatGPT plan rather than billed separately.

Authenticate With an API Key

For automation, scripts, or CI pipelines where a browser sign-in doesn't make sense, set an environment variable instead:

export OPENAI_API_KEY=your-api-key

This method skips the interactive login entirely, which is the point.

Starting Your First Codex CLI Session

With installation and sign-in out of the way, this is where the tutorial actually gets useful.

Open a Project Directory

Navigate to a project folder in your terminal, or on macOS, right-click the folder in Finder and choose "New Terminal at Folder." Either gets you to the same place.

Run Your First Task

codex

From here, describe what you want. Something simple works well as a first test, like asking it to explain the project structure.

A slightly more hands-on example might be asking it to add error handling to a specific file. Codex reads the relevant files first, then proposes a change rather than just guessing at one blindly.

Review Changes Before They Apply

Codex shows proposed edits in a diff view. You accept or reject each change individually rather than approving everything at once.

This step is where most of the actual trust building happens. Once you've watched it make a handful of sensible, small edits, running it with less oversight starts to feel less risky.

Understanding Codex CLI Approval Modes

This is one part of the tutorial worth slowing down on, because the three modes genuinely change how much Codex can do without asking first.

Approval Mode

What It Allows

Best For

Auto (default)

Reads, edits, and runs commands inside your working directory. Asks first for anything outside that scope

Everyday tasks where you want speed without giving up all oversight

Read-only

Consultative only. No file edits, no commands run

Exploring or understanding a codebase before making changes

Full Access

Broader autonomy, including network access

Users who've already built confidence in how Codex behaves

Switch modes mid-session with /permissions. Some versions of Codex also respond to /approval, so if one doesn't work, try the other.

There's no universally correct mode here. Someone working solo on a side project might jump straight to full autonomy. A team touching production code will usually stay closer to the default, at least at first.

Useful Codex CLI Commands

A handful of commands come up often enough that they're worth memorizing early.

Common Slash Commands

  • /init, creates an AGENTS.md file with starter instructions
  • /new, clears the current session and starts fresh
  • /model, switches the active model
  • /compact, condenses conversation history to save on tokens
  • /status, shows current session configuration and usage
  • /permissions, adjusts what Codex is allowed to do
  • /quit, ends the session

Running Bash Commands Inside a Session

Prefix any shell command with ! and it runs immediately, with the output staying visible in the conversation:

!ls

!pwd

!git status

This turns out to be a small but genuinely useful detail. Instead of switching to a separate terminal tab to check git status and then explaining what you saw, you just run it inline. Codex sees the same output you do.

Resuming a Previous Codex CLI Session

Sessions don't just disappear when you close the terminal. Exit with Ctrl+C, and Codex shows a session ID. Reopen it with:

codex resume [session-id]

Or, for the most recent conversation specifically:

codex resume –last

Session logs are stored locally in a structured text format, which is part of why resuming works as cleanly as it does. Context from the earlier conversation carries forward instead of starting from zero.

Customizing Codex With an AGENTS.md File

An AGENTS.md file sits at the root of your project and gives Codex standing instructions it reads at the start of every session. Create one manually, or run /init to generate a starting template.

A basic version might describe your tech stack, your coding conventions, and any commands Codex should run before considering a task finished, like a test suite. Once it's in place, you stop repeating the same context in every session, which is really the entire point of having it.

Connecting External Tools With MCP

MCP, short for Model Context Protocol, is an open standard that lets Codex talk to tools outside your local filesystem, things like browsers, project management tools, or documentation sites.

Adding an MCP Server

codex mcp add [server-name] [command]

Check what's connected at any point with:

codex mcp list

Alternatively, MCP servers can be defined directly inside the Codex configuration file, which some people prefer for anything they want to persist without re-adding it each time.

Teams experimenting with MCP for the first time commonly report that the setup step is straightforward, but knowing which server actually fits a given workflow takes a bit more trial and error.

Troubleshooting Common Codex CLI Issues

Most early friction comes down to one of two things.

If Codex can't take an action inside your project directory, check that the current approval mode actually grants that access. Switching modes with /permissions usually resolves it.

If you're on Windows and running into odd behavior, that lines up with what's expected right now. Windows support is still labeled experimental, and running Codex inside WSL tends to sidestep most of the friction.

Conclusion

Codex CLI comes down to a repeatable pattern: install, sign in, run a task, review the diff. Once that loop feels familiar, approval modes, AGENTS.md, and MCP extend what it can handle without much extra effort.

Frequently Asked Questions

Is Codex CLI free to use?

Not on its own. It requires either a paid ChatGPT plan that includes Codex access, or an OpenAI API key, which is billed separately based on usage.

What operating systems does Codex CLI support?

macOS and Linux have full support. Windows currently works but is labeled experimental, and running it through WSL tends to be more reliable.

Can I use Codex CLI without a ChatGPT account?

Yes. Authenticating with an OpenAI API key instead of signing in works well for automation, scripts, or CI pipelines that don't involve a browser.

How do I switch models in Codex CLI?

Run /model during an active session. Available models change periodically, so it's worth checking what's currently listed rather than assuming.

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

Auto allows edits and commands inside your working directory by default. Read-only permits no changes at all. Full Access extends autonomy further, including network access.

Adrian Lee
Adrian Lee

Adrian Lee is the Data Visualization Specialist and Statistical Analyst at ViolinPlot. Based in Boston, Massachusetts, Adrian utilizes a robust background in statistics and data science to create compelling and insightful visualizations that help interpret complex data.

With extensive experience in data analysis and visualization techniques, Adrian specializes in developing violin plots and other advanced graphical representations to convey statistical information effectively. Adrian’s expertise includes statistical modeling, data interpretation, and the creation of interactive visualizations.

At ViolinPlot, Adrian is responsible for transforming raw data into visual narratives that are both informative and engaging.

By employing state-of-the-art visualization tools and statistical methods, Adrian ensures that the visual representations are accurate, clear, and valuable for decision-making processes.

Adrian’s dedication to enhancing data comprehension through visual tools has established ViolinPlot. As a leading resource for data visualization and statistical analysis.

Articles: 78

Ready to Unlock Deeper Data Insights?

Transform complex datasets into clear, interactive visualizations with Violin Plot. Start exploring data distributions in a way that empowers insight and drives smarter decisions.

LEARN MOre
100% satisfaction guaranteed
McAfee SECURE
ssl-secured
verisign-secured
BEST-PRICE-GUARANTEED-free-trust-badge
guaranteed-safe-checkout-1