Skip to main content

​
Quickstart

This guide will help you get Codex CLI running and execute your first commands. You’ll go from installation to your first AI-powered task in just a few minutes.

​
Before you begin

Make sure you have:
  • Codex CLI installed (see Installation)
  • A ChatGPT account (Plus, Pro, Team, Edu, or Enterprise) or an OpenAI API key
  • A terminal running macOS 12+, Linux (Ubuntu/Debian), or Windows 11 with WSL2

​
Get started with Codex

1

Install Codex CLI

Install Codex globally using npm or Homebrew:
npm install -g @openai/codex
Verify the installation:
codex --version
2

Sign in with ChatGPT

Run codex and select Sign in with ChatGPT. This is the recommended method for using Codex with your ChatGPT plan.
codex
When you run this command, Codex will:
  1. Start a local login server on http://localhost (random port)
  2. Open your browser to authenticate
  3. Complete authentication and return to the terminal
We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. Learn more about what’s included in your ChatGPT plan.
On a remote or headless machine? Use device code authentication instead:
codex login --device-auth
Alternatively, you can use an API key (see Authentication for details).
3

Run your first command

Once authenticated, run Codex interactively:
codex
Or provide a prompt directly:
codex "explain this codebase to me"
Codex will analyze your project and provide an explanation.
4

Try an example task

Let’s have Codex write a simple script. Try this command:
codex "create a simple Python script that prints Hello World"
Codex will:
  1. Create a Python file
  2. Write the code
  3. Ask for your approval before saving (in default “suggest” mode)
  4. Show you the result
You’ll see output similar to:
I'll create a simple Python script for you.

[Codex proposes changes]

Approve? [Y/n]:
Type y to approve and apply the changes.

​
Understanding approval modes

Codex operates in three approval modes that control how much autonomy the agent has:

Suggest

Default modeCodex reads files and suggests changes. You approve all file writes and shell commands.

Auto Edit

Codex reads and writes files automatically. You approve shell commands.Use: codex --approval-mode auto-edit

Full Auto

Codex reads, writes files, and executes commands autonomously. Everything runs in a sandbox.Use: codex --approval-mode full-auto
In full auto mode, commands run network-disabled and confined to your working directory. Codex will warn you if your directory is not tracked by Git.

​
Example workflows

Here are some common tasks you can ask Codex to perform: 
codex "Refactor the Dashboard component to React Hooks"
Codex will:
  • Read the component file
  • Rewrite it using React Hooks
  • Run tests to verify the changes
  • Show you a diff of the changes
codex "Write unit tests for utils/date.ts"
Codex will:
  • Analyze the date.ts file
  • Generate comprehensive unit tests
  • Execute the tests
  • Iterate until they pass
codex --approval-mode full-auto "create a todo-list app with React and TypeScript"
Codex will:
  • Scaffold the project structure
  • Install dependencies
  • Write the application code
  • Run it in the sandbox
  • Show you the live result
codex "fix all TypeScript errors in this project"
Codex will:
  • Run the TypeScript compiler
  • Identify all type errors
  • Fix them one by one
  • Verify the fixes compile

​
Interactive vs non-interactive mode

Interactive mode (default) Run codex to start an interactive REPL session: 
codex
You can have a back-and-forth conversation with Codex, approve changes, and iterate on tasks. Non-interactive mode Provide a prompt as a command-line argument: 
codex "create a README for this project"
Codex will execute the task and exit when complete. Quiet mode (for CI/CD) Run Codex headless in pipelines: 
codex -q "update CHANGELOG for next release"
Or set the environment variable: 
export CODEX_QUIET_MODE=1

​
Passing images

Codex is multimodal and can understand images. Pass screenshots or diagrams: 
codex -i screenshot.png "implement this design"
Codex will analyze the image and implement the visual design.

​
Next steps

Learn about authentication

Explore all authentication methods and configuration options

Core concepts

Understand approval modes, sandboxing, and security model

Configuration

Customize Codex with config files and environment variables

CLI reference

Explore all available commands and options