OpenAI Codex CLI Tutorial

There is a boom in agent-centric IDEs like Cursor AI and Windsurf that can understand your source code, suggest changes, and even run commands for you. All you have to do is talk to the AI agent and vibe with it, hence the term "vibe coding."

OpenAI, perhaps feeling left out of the vibe coding movement, recently released their open-source tool that uses a reasoning model to understand source code and help you debug or even create an entire project with a single command.

In this tutorial, we will learn about OpenAI’s Codex CLI and how to set it up locally. After that, we will use the Codex command to build a website using a screenshot. We will also work on a complex project like training a machine learning model and developing model inference with a custom user interface.

We keep our readers updated on the latest in AI by sending out The Median, our free Friday newsletter that breaks down the week’s key stories. Subscribe and stay sharp in just a few minutes a week:

You can learn more about Cursor AI and Windsurf in separate guides, and get some hands-on experience with our OpenAI Fundamentals skill track.  

Image by Author

What is OpenAI’s Codex CLI?

OpenAI Codex CLI is an open-source command-line tool that brings the power of OpenAI's latest reasoning models (o4) directly to your terminal. This Lightweight CLI tool lets you read, modify, and execute code directly on your local machine. 

It is designed to help developers build features more quickly, fix bugs, and better understand unfamiliar code. Importantly, because the CLI operates locally, your source code remains secure within your environment unless you share it.

Here are the key features of Codex CLI:

1. Zero-setup installation: You can get started with a simple NPM command.
2. Multimodal inputs:  The CLI allows you to pass text, screenshots, or diagrams, enabling the AI agent to generate or edit code accordingly.
3. Rich approvals workflow: You can choose your level of involvement with three distinct modes: Suggest, Auto Edit, and Full Auto.
4. Runs entirely in your terminal: This feature turns your simple terminal into a code editor, AI assistant, and powerful debugger. 

Here is more information on approval modes:

• Suggest (default): The agent reads files and proposes edits or shell commands, requiring your approval before making changes. 
• Auto Edit: The agent can read and write files automatically but still asks permission before executing shell commands. 
• Full Auto: In this mode, the agent autonomously reads, writes, and executes commands within a sandboxed, network-disabled environment scoped to the current directory. 

If you are new to AI and want to learn the basics, we highly recommend completing the AI Fundamentals track.

Setting Up Codex CLI 

Follow these steps to set up OpenAI Codex CL on your system.

System requirements

Before installing Codex CLI, ensure your system meets the following requirements:

• Operating Systems:
• macOS 12+
• Ubuntu 20.04+/Debian 10+
• Windows 11 (optional WSL2)
• Node.js: Version 22 or newer (LTS recommended)
• Git: Version 2.23+ (optional but recommended for built-in PR helpers).
• RAM: Minimum 4 GB (8 GB recommended for better performance).

Installation steps

1. Install Node.js: Ensure you have Node.js version 22 or newer installed. You can download it from the official Node.js website.
2. Install Git: If you don’t already have Git installed, download and install it from git-scm.com. 
3. Set up Powershell: If you are using Windows, configure your powershell terminal as follows:
• Open your PowerShell profile by running:

$PROFILE

• Add the following line to your profile to set up Git Bash as the default shell:

Set-Alias sh.exe "C:\Program Files\Git\bin\bash.exe"

4. Install Codex CLI: Run the following command to install Codex CLI globally:

npm install -g @openai/codex

5. Set Your OpenAI API Key: To use Codex CLI, you need an OpenAI API key. Export your API key as an environment variable:

export OPENAI_API_KEY="your-api-key-here"

Using Codex CLI

1. Type the following command in your terminal to launch the interactive mode:

codex

2. If you are not inside a Git repository, you will see a warning stating that it is dangerous to build a project outside of a Git repository. When prompted, press “N” to proceed.

3. Navigate to your project directory using the cd command:

cd <project-directory>

4. If your project is not already a Git repository, initialize it by running:

git init

5. Once inside your project directory, type the following command to start using Codex CLI in interactive mode:

codex

In this mode, you can interact with the AI agent conversationally, similar to ChatGPT. Simply type your coding-related queries, and the AI will assist you by generating, debugging, or modifying code as needed.

Building the Website with Codex CLI

In this project, we will use Codex CLI to build a website inspired by CodeCut using a screenshot of its design. Why CodeCut? I’m a big fan of Khuyen Tran’s work, and I wanted to replicate her website’s style while adding my own unique flavor to it.

1. First, visit the CodeCut website and take a screenshot of the landing page.

Source: CodeCut

2. Provide the location of the screenshot to Codex CLI using the following command:

 codex --image "C:\Users\abida\Pictures\Screenshots\Screenshot 2025-04-19 213702.png"

3. The Codex CLI agent will analyze the screenshot and prompt you to ask a follow-up question. 

By default, it uses the new O4-Mini model. You can learn the basics of the O4 model by reading the O4-Mini: Tests, Features, O3 Comparison, Benchmarks, and More guide.

4. Ask the agent to build a similar website with the logo “🙌” and company name handsup.

5. The agent may ask follow-up questions to execute commands for creating files and adding the code to the files.

6. At the end of the process, the agent will provide a summary of the changes it made. 

7. To update the hero image, navigate to the assets folder and replace the current image with your selected illustration. Be sure to rename the new file using the name of the original hero image. The original image was quite simple, and I would like to use an illustration that shows everyone raising their hands in an office space.
8. Double-click on the index.html file to see your website. 

The result was better than I imagined. The logo, title, color scheme, links, and overall design were all perfectly aligned with my vision. 

Building the ML Inference Application 

In this second project, we will tackle something more complex: building a complete machine learning application. This project will cover everything from data loading to creating a model inference pipeline with a custom user interface. 

Additionally, we will grant the agent full autonomy, allowing it to execute commands without requiring user intervention. 

1. Using the command below, we instructed Codex to build the application:

codex --approval-mode full-auto "Build a proper FastAPI ML application with user interface."

As a result, the agent has built a project that includes all the necessary files and configurations. All you need to do is follow the command at the end to run the application.

2. To install the Python packages, run:

pip install -r requirements.txt

3. Next, execute the training script:

$ python train.py

Model saved to C:\Repository\GitHub\ML App with Codex\model\model.pkl

4. Then, you can run the app using:

uvicorn app.main:app -reload

5. Open your browser and paste the URL http://127.0.0.1:8000 to access the app.

The application is fully functional and delivers high accuracy. 

I was particularly impressed by the user interface and how quickly the Codex CLI generated all the files without any bugs. 

While this project serves as an example and has been implemented by many developers before, it’s worth noting that even for such a straightforward task, most large language models (LLMs) struggle to produce a working solution in one go. However, with Codex, I simply typed a single command, and it delivered exceptional results. I am genuinely impressed.

We haven't discussed the inner workings of the CLI. If you want to learn about and use the OpenAI API for your projects, then take the Developing AI Systems with the OpenAI API course.

Final Thoughts

While OpenAI Codex CLI is not a completely original concept, the standout feature of Codex CLI is that it’s open-source and allows you to connect your OpenAI account to leverage even more advanced models.

Personally, I find Codex CLI to be a better alternative in many cases. It requires fewer steps to achieve goals, is incredibly fast, and streamlines the development process. However, the only way to determine if this tool will work for your specific use case is to try it yourself. While it excels in straightforward workflows, it may not be the best fit for complex projects with many moving parts.

As we’ve seen, OpenAI has recently launched a new model, GPT-4.1, alongside its existing o4-mini and o3 models. For those interested in learning more about GPT-4.1, including its features, comparisons with GPT-4o, and how to access it, read GPT 4.1: Features, Access, GPT-4o Comparison, and More blog.