Codex CLI Beginner's Guide: From Installation to Your First AI Coding Task

What This Tutorial Teaches

Codex CLI is OpenAI's coding agent that runs in your terminal. It can inspect your project, edit files, run commands, and automate repeatable work — all from a command line. By the end of this tutorial, you will be able to install Codex CLI, sign in, and complete your first AI-assisted coding task.

Time needed: 15–20 minutes

Difficulty: Beginner

Before You Start

What is a terminal? A terminal (also called command line) is a window where you type commands instead of clicking buttons. On Windows it is called PowerShell; on macOS it is called Terminal. This tutorial uses codex commands, which you type into this window and press Enter.

What is Node.js? Node.js is a free program that lets you install tools with the npm command. You only need it if you choose the npm install method below. If you do not have it, install it from nodejs.org (choose the LTS version).

What is an API key? An API key is a secret code that identifies your account when paying per use. You generate it once at platform.openai.com → API keys. Treat it like a password — never share it.

How to Open Your Terminal (Step by Step)

If you are not sure how to open a terminal, follow the steps for your system below. You will use it for every command in this tutorial.

Download and Install

Choose Your Version

What is Homebrew? Homebrew is a free package manager for macOS. You type brew install to install programs, just like an app store for the command line. Only choose this option if you already use Homebrew.

Install for Your System

Select your system below. Each tab contains the complete steps for that operating system.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

codex --version

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Sign In

1. 1Open a terminal and go to a project folder (replace path/to/your/project with your own folder path):

cd path/to/your/project

1. 1Start Codex:

codex

1. 1The first time, choose a sign-in method:

• Sign in with ChatGPT — use your ChatGPT account (subscription). A browser window opens; after you sign in, the browser returns your credentials to Codex automatically.
• Use an API key — paste the key you generated at platform.openai.com when asked.

1. 1After signing in, you will see the Codex prompt, ready for your first task.

Installation Troubleshooting

Fix for "codex: command not found" — Windows:

1. 1Press the Windows key, type environment variables, and click Edit the system environment variables.
2. 2Click the Environment Variables... button.
3. 3In the lower list (System variables), find Path, select it, and click Edit....
4. 4Click New, add the folder where Codex was installed (default: C:\Users\<your username>\.local\bin), and click OK on every window.
5. 5Close PowerShell completely and open it again, then run codex --version.

Fix for "codex: command not found" — macOS/Linux:

1. 1Open Terminal and copy-run this command:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

1. 1Reload the settings:

source ~/.zshrc

1. 1If you use Bash instead of Zsh, use ~/.bashrc in both commands above.
2. 2Run codex --version to confirm.

Your First Task

Step 1: Open a project

Go to the project folder you want Codex to work on (replace the path with yours):

cd path/to/your/project

Step 2: Start Codex

codex

Step 3: Ask your first question

Type this request and press Enter:

Tell me about this project

Codex reads the project files and explains what it finds. Try a few more:

• Explain the main function in this file — explains the main function of this file
• Find the bug in this code — looks for bugs in this code
• Add a comment header to every file — adds a comment header to every file

Step 4: Approve what Codex wants to do

When Codex wants to edit files or run commands, it asks for your permission first. This is normal. Type y and press Enter to approve, or n to reject. Review each change — you stay in control of what happens on your machine.

Step 5: Exit Codex

When you are done, type /exit and press Enter, or press Ctrl + C twice.

Useful Commands

Frequently Asked Questions

Do I need a paid plan?

You need either a ChatGPT subscription or an OpenAI API key. The free ChatGPT plan does not include Codex CLI access. Check the official pricing page for current options.

Does Codex work outside a git repository?

Codex works best inside a git project. If you are starting from scratch, create a repository first:

git init

Can Codex run my code?

Yes, with your permission. Codex can run shell commands and tests on your machine, and it always shows you what it runs before asking. Use the permission settings to control what it can do without asking.

Is my code sent to OpenAI?

When you use Codex with OpenAI models, your prompts and file contents are processed by OpenAI according to the data controls of your account type (subscription or API organization settings). Review the official data controls documentation for details.

What's Next

• Add project guidance: Create an AGENTS.md file in your repository to give Codex durable instructions about your project.
• Automate with scripts: Use codex exec in CI pipelines and repeatable workflows.
• Connect tools with MCP: Use codex mcp to give Codex access to external data and services.
• Try Codex cloud: Hand long-running work to the cloud and return to the terminal later.