OpenAI Codex Quick Start Guide
Get Codex running in under 5 minutes. Covers CLI installation on every platform, authentication with ChatGPT or API keys, your first tasks, the desktop app, Codex Cloud, and IDE extensions.
Key Takeaways#
- Install in one command — Codex CLI is available via npm, Homebrew, or GitHub releases for macOS, Linux, and Windows.
- Sign in with ChatGPT or use an API key — two auth paths get you coding in under two minutes.
- Run your first task from the terminal —
codex Add-a-hello-world-function-to-main.pycreates real code changes. - Use the desktop app for a GUI workflow — launch Codex App for a visual, conversational coding experience.
- Access Codex Cloud for browser-based tasks — head to chatgpt.com/codex to run tasks without installing anything.
- Pair with your IDE — VS Code, Cursor, and Windsurf extensions integrate Codex directly into your editor.
System Requirements#
| Requirement | Minimum |
|---|---|
| macOS | 12+ (Monterey) |
| Linux | Ubuntu 20.04+ / Debian 10+ |
| Windows | 10+ (native or WSL2) |
| Node.js | 22+ (for npm install) |
| RAM | 4 GB |
| Network | Outbound HTTPS to api.openai.com |
Installation#
npm (All Platforms)#
The fastest way to install Codex CLI globally:
npm install -g @openai/codex
This works on macOS, Linux, and Windows. Node.js 22 or later is required. Verify the install:
codex --version
Homebrew (macOS / Linux)#
For macOS and Linux users who prefer Homebrew:
brew install --cask codex
GitHub Releases#
Download the latest binary directly from the OpenAI Codex GitHub repository releases page. This is ideal for CI environments or machines without Node.js:
- Go to the Codex GitHub releases page.
- Download the archive for your OS and architecture.
- Extract the binary and add it to your PATH.
Tip: GitHub releases include standalone binaries with no runtime dependencies, making them the best option for Docker containers or minimal server installs.
Authentication#
Codex offers two authentication methods. Choose the one that fits your workflow.
1. Sign In with ChatGPT#
The simplest option for users with a ChatGPT Plus, Pro, Team, or Enterprise subscription:
codex auth login
This opens a browser window for OAuth login. After you authenticate with your OpenAI account, you are ready to go. No API key management required.
2. API Key#
For pay-as-you-go usage with an OpenAI API key:
codex auth login --api-key
Alternatively, set the OPENAI_API_KEY environment variable:
export OPENAI_API_KEY="sk-..."
Add this line to your shell profile (~/.bashrc, ~/.zshrc) to persist it across sessions.
Verify Your Auth#
codex auth status
This confirms your active account type and session validity.
Your First CLI Task#
- Navigate to a project directory:
cd ~/projects/my-app
- Run your first Codex task:
codex "Add a hello world function to main.py"
Codex reads your codebase, understands the context, and generates the change. It shows you a diff before applying it, so you stay in control.
- Try more prompts:
- codex "Write unit tests for the auth module"
- codex "Fix the type error in src/api/handlers.ts"
- codex "Add JSDoc comments to all exported functions"
- codex "Refactor the database connection to use a connection pool"
- Use Codex in full-auto mode for trusted tasks:
codex --full-auto "Add input validation to the registration form"
Caution: --full-auto applies changes without confirmation. Use it only for low-risk tasks or in throwaway branches.
Helpful CLI Flags#
| Flag | What It Does |
|---|---|
| --model | Switch the underlying model (e.g., codex --model o4-mini) |
| --full-auto | Apply changes without asking for confirmation |
| --quiet | Suppress non-essential output |
| --help | List all available flags and subcommands |
Codex Desktop App#
For a visual, conversational workflow, use the Codex desktop application:
codex app
The desktop app provides:
- A chat-based interface for describing tasks in natural language
- A file browser showing which files Codex plans to modify
- One-click approval or rejection of proposed changes
- Session history so you can review past tasks
The app is available on macOS and Windows. Download it from the OpenAI Codex product page if you have not installed it already.
Codex Cloud#
Run Codex tasks directly in your browser — no local installation required:
- Go to chatgpt.com/codex.
- Sign in with your ChatGPT account.
- Describe your task in natural language.
- Review the generated code diff and approve it.
Codex Cloud executes tasks in a sandboxed environment. It supports public GitHub repositories out of the box, and private repos can be connected with a single authorization step. This is the fastest way to try Codex if you want to evaluate it before installing anything locally.
IDE Integrations#
Codex integrates directly into popular code editors through official extensions.
VS Code#
- Open the Extensions marketplace in VS Code (Ctrl+Shift+X or Cmd+Shift+X).
- Search for OpenAI Codex.
- Click Install.
- Authenticate when prompted — the extension uses the same ChatGPT or API key credentials.
Cursor#
- Open Cursor Settings.
- Navigate to the Extensions panel.
- Search for OpenAI Codex and install it.
- Codex commands appear in the Command Palette (Ctrl+Shift+P).
Windsurf#
- Open the Windsurf marketplace.
- Search for OpenAI Codex.
- Install the extension and authenticate.
Once installed, you can invoke Codex from your editor sidebar or command palette, review proposed diffs inline, and accept or reject changes without leaving your IDE.
Next Steps#
- Codex configuration — Learn how CODEX.md files set project-level instructions and guardrails.
- Full CLI reference — Explore all flags, subcommands, and advanced usage patterns.
- Codex Cloud deep dive — Set up private repo access, configure sandbox options, and manage team permissions.
- MCP integration — Connect external tools and data sources to expand Codex capabilities.