Installation, Setup, and Your First Task
Now that you understand what Codex is and how it fits the AI coding landscape, it is time to get it running on your machine. In this lesson, you will install Codex CLI, authenticate your account, and run your very first coding task.
What You Will Learn
- How to install Codex CLI using npm or Homebrew
- How to authenticate with your OpenAI account
- How to launch Codex and navigate the interface
- How to run your first coding task from start to finish
- How to access Codex Cloud through the desktop app
Installing Codex CLI
Codex CLI can be installed through three methods. Choose the one that fits your environment.
Option 1: npm (Recommended for most developers)
If you have Node.js installed, this is the simplest approach:
npm install -g @openai/codex
This installs the codex command globally on your system.
Option 2: Homebrew (macOS)
If you prefer Homebrew on macOS:
brew install --cask codex
Option 3: Manual Download
You can download platform-specific binaries directly from the GitHub Releases page at github.com/openai/codex. Binaries are available for:
- macOS (arm64 and x86_64)
- Linux (x86_64 and arm64)
After downloading, move the binary to a directory in your PATH and make it executable.
Verifying the Installation
After installation, verify that Codex is available:
codex --version
You should see a version number printed to your terminal. If you get a "command not found" error, make sure the installation directory is in your system PATH.
Authentication
Codex supports two authentication methods:
Method 1: ChatGPT Sign-In (Recommended)
The simplest way to authenticate is to sign in with your ChatGPT account. When you first run codex, it will prompt you to sign in through your browser. This gives you access to Codex features included with your plan:
- ChatGPT Plus — Standard Codex access
- ChatGPT Pro — Enhanced usage limits
- ChatGPT Team/Enterprise — Organizational access with admin controls
- ChatGPT Edu — Educational institution access
Method 2: API Key
If you prefer to use an API key directly, you can set the OPENAI_API_KEY environment variable:
export OPENAI_API_KEY="your-api-key-here"
To make this permanent, add the line to your shell profile (~/.bashrc, ~/.zshrc, or equivalent).
Note: API key usage is billed separately from your ChatGPT subscription.
Launching Codex
To start Codex CLI, simply type:
codex
This launches the interactive Codex interface in your terminal. You will see a prompt where you can type natural language instructions.
You can also pass a task directly as an argument:
codex "explain what this project does"
This starts Codex and immediately begins working on the task you specified.
Your First Task: Understanding a Project
Let us walk through a complete first task. Navigate to any project directory and run:
cd your-project-directory
codex "explain the structure of this project and what each top-level directory does"
Here is what happens step by step:
- Codex reads your project — It scans the directory structure, key configuration files (package.json, Cargo.toml, pyproject.toml, etc.), and source files
- It analyzes the structure — The agent identifies frameworks, languages, and architectural patterns
- It presents its findings — You get a clear, organized explanation of your project
This is a safe first task because it only reads files. Codex does not modify anything when you ask it to explain or analyze.
Your Second Task: Making a Change
Now try something that modifies code. Create a simple test project first:
mkdir codex-test && cd codex-test
echo "console.log('hello');" > index.js
codex "add a function called greet that takes a name parameter and returns a greeting string, then update the main code to use it"
Codex will:
- Read the existing
index.jsfile - Plan the changes needed
- Show you what it wants to do (in Suggest mode, the default)
- Wait for your approval before making changes
- Write the updated file
After you approve, check the result:
cat index.js
You should see a greet function and updated code that uses it.
Accessing Codex Cloud
To open the Codex desktop app for cloud-based tasks:
codex app
This launches the Codex application where you can:
- Create projects and organize your work
- Dispatch tasks to run in cloud sandboxes
- Monitor multiple tasks running in parallel
- Review results and apply changes
You can also access Codex Cloud through the web at chatgpt.com/codex.
Common Setup Issues
"command not found" after installation:
Make sure the npm global bin directory is in your PATH. Run npm bin -g to find the directory, then add it to your shell profile.
Authentication fails: Ensure you have an active ChatGPT subscription or a valid API key. Check your internet connection and try signing in again.
Slow responses on first run: The first task may take longer as Codex indexes your project. Subsequent tasks will be faster as the agent builds context.
Key Takeaways
- Install Codex CLI with
npm install -g @openai/codexorbrew install --cask codex - Authenticate via ChatGPT sign-in (recommended) or an API key
- Launch with
codexfor interactive mode orcodex "your task"for direct execution - Start with read-only tasks like "explain this project" before making changes
- Access Codex Cloud via
codex appor chatgpt.com/codex - The default mode is Suggest, which shows you changes before applying them